摘要：譯者說(shuō)于年月日發(fā)布，該版本正式支持的關(guān)鍵字，并且用舊版本編譯同樣可以使用這兩個(gè)關(guān)鍵字，這無(wú)疑是一種進(jìn)步。其次，這是最后一個(gè)支持和的版本了，在后續(xù)的版本了會(huì)移除對(duì)它們的兼容。

Tornado 4.3于2015年11月6日發(fā)布，該版本正式支持Python3.5的async/await關(guān)鍵字，并且用舊版本CPython編譯Tornado同樣可以使用這兩個(gè)關(guān)鍵字，這無(wú)疑是一種進(jìn)步。其次，這是最后一個(gè)支持Python2.6和Python3.2的版本了，在后續(xù)的版本了會(huì)移除對(duì)它們的兼容?，F(xiàn)在網(wǎng)絡(luò)上還沒(méi)有Tornado4.3的中文文檔，所以為了讓更多的朋友能接觸并學(xué)習(xí)到它，我開(kāi)始了這個(gè)翻譯項(xiàng)目，希望感興趣的小伙伴可以一起參與翻譯，項(xiàng)目地址是tornado-zh on Github，翻譯好的文檔在Read the Docs上直接可以看到。歡迎Issues or PR。

Tornado 包含一個(gè)簡(jiǎn)單,快速并靈活的模板語(yǔ)言. 本節(jié)介紹了語(yǔ)言以及相關(guān)的問(wèn)題,比如國(guó)際化.

Tornado 也可以使用其他的Python模板語(yǔ)言, 雖然沒(méi)有準(zhǔn)備把這些系統(tǒng)整合到 RequestHandler.render 里面. 而是簡(jiǎn)單的將模板轉(zhuǎn)成字符串并傳遞給 RequestHandler.write

默認(rèn)情況下, Tornado會(huì)在和當(dāng)前.py文件相同的目錄查找關(guān)聯(lián)的模板文件. 如果想把你的模板文件放在不同的目錄中, 可以使用template_pathApplication setting (或復(fù)寫(xiě) RequestHandler.get_template_path 如果你不同的處理函數(shù)有不同的模板路徑).

為了從非文件系統(tǒng)位置加載模板, 實(shí)例化子類 tornado.template.BaseLoader并為其在應(yīng)用設(shè)置(application setting)中配置template_loader.

默認(rèn)情況下編譯出來(lái)的模板會(huì)被緩存; 為了關(guān)掉這個(gè)緩存也為了使(對(duì)目標(biāo)的)修改在重新加載后總是可見(jiàn), 使用應(yīng)用設(shè)置(application settings)中的compiled_template_cache=False或debug=True.

一個(gè)Tornado模板僅僅是用一些標(biāo)記把Python控制序列和表達(dá)式嵌入HTML(或者任意其他文本格式)的文件中:

    
       
          
       
       
         

           {% for item in items %}
             
{{ escape(item) }}
           {% end %}
         
       
     

如果你把這個(gè)目標(biāo)保存為"template.html"并且把它放在你Python文件的相同目錄下, 你可以使用下面的代碼渲染它:

    class MainHandler(tornado.web.RequestHandler):
        def get(self):
            items = ["Item 1", "Item 2", "Item 3"]
            self.render("template.html", title="My title", items=items)

Tornado模板支持控制語(yǔ)句(control statements)和表達(dá)式(expressions).控制語(yǔ)句被包在{%和%}中間, 例如,{% if len(items) > 2 %}. 表達(dá)式被包在{{和}}之間, e.g.,{{ items[0] }}.

控制語(yǔ)句或多或少都和Python語(yǔ)句類似. 我們支持if,for,while, 和try, 這些都必須使用{% end %}來(lái)標(biāo)識(shí)結(jié)束. 我們也支持 模板繼承(template inheritance) 使用extends和block標(biāo)簽聲明, 這些內(nèi)容的詳細(xì)信息都可以在 tornado.template 中看到.

表達(dá)式可以是任意的Python表達(dá)式, 包括函數(shù)調(diào)用. 模板代碼會(huì)在包含以下對(duì)象和函數(shù)的命名空間中執(zhí)行 (注意這個(gè)列表適用于使用 RequestHandler.render
和RequestHandler.render_string渲染模板的情況. 如果你直接在RequestHandler之外使用tornado.template模塊, 下面這些很多都不存在).

escape: tornado.escape.xhtml_escape 的別名

xhtml_escape: tornado.escape.xhtml_escape 的別名

url_escape: tornado.escape.url_escape 的別名

json_encode: tornado.escape.json_encode 的別名

squeeze: tornado.escape.squeeze 的別名

linkify: tornado.escape.linkify 的別名

datetime: Python datetime 模塊

handler: 當(dāng)前的 RequestHandler 對(duì)象

request: handler.request 的別名

current_user: handler.current_user 的別名

locale: handler.locale 的別名

_: handler.locale.translate 的別名

static_url: handler.static_url 的別名

xsrf_form_html: handler.xsrf_form_html 的別名

reverse_url: Application.reverse_url 的別名

所有從ui_methods和ui_modules`Application`設(shè)置的條目

任何傳遞給 RequestHandler.render 或RequestHandler.render_string 的關(guān)鍵字參數(shù)

當(dāng)你正在構(gòu)建一個(gè)真正的應(yīng)用, 你可能想要使用Tornado模板的所有特性,尤其是目標(biāo)繼承. 閱讀所有關(guān)于這些特性的介紹在 tornado.template部分 (一些特性, 包括UIModules是在 tornado.web 模塊中實(shí)現(xiàn)的)

在引擎下, Tornado模板被直接轉(zhuǎn)換為Python. 包含在你模板中的表達(dá)式會(huì)逐字的復(fù)制到一個(gè)代表你模板的Python函數(shù)中. 我們不會(huì)試圖阻止模板語(yǔ)言中的任何東西; 我們明確的創(chuàng)造一個(gè)高度靈活的模板系統(tǒng), 而不是有嚴(yán)格限制的模板系統(tǒng). 因此, 如果你在模板表達(dá)式中隨意填充(代碼), 當(dāng)你執(zhí)行它的時(shí)候你也會(huì)得到各種隨機(jī)錯(cuò)誤.

所有模板輸出默認(rèn)都會(huì)使用 tornado.escape.xhtml_escape 函數(shù)轉(zhuǎn)義.這個(gè)行為可以通過(guò)傳遞autoescape=None給 Application 或者tornado.template.Loader 構(gòu)造器來(lái)全局改變, 對(duì)于一個(gè)模板文件可以使用{% autoescape None %}指令, 對(duì)于一個(gè)單一表達(dá)式可以使用{% raw ...%}來(lái)代替{{ ... }}. 此外, 在每個(gè)地方一個(gè)可選的轉(zhuǎn)義函數(shù)名可以被用來(lái)代替None.

注意, 雖然Tornado的自動(dòng)轉(zhuǎn)義在預(yù)防XSS漏洞上是有幫助的, 但是它并不能勝任所有的情況. 在某一位置出現(xiàn)的表達(dá)式, 例如Javascript 或 CSS, 可能需要另外的轉(zhuǎn)義. 此外, 要么是必須注意總是在可能包含不可信內(nèi)容的HTML中使用雙引號(hào)和 xhtml_escape , 要么必須在屬性中使用多帶帶的轉(zhuǎn)義函數(shù)(參見(jiàn) e.g. http://wonko.com/post/html-escaping)

當(dāng)前用戶的區(qū)域設(shè)置(無(wú)論他們是否登錄)總是可以通過(guò)在請(qǐng)求處理程序中使用self.locale或者在模板中使用locale進(jìn)行訪問(wèn). 區(qū)域的名字(e.g.,en_US) 可以通過(guò)locale.name獲得, 你可以翻譯字符串通過(guò) Locale.translate 方法. 模板也有一個(gè)叫做_()全局函數(shù)用來(lái)進(jìn)行字符串翻譯. 翻譯函數(shù)有兩種形式:

_("Translate this string")

是直接根據(jù)當(dāng)前的區(qū)域設(shè)置進(jìn)行翻譯, 還有:

_("A person liked this", "%(num)d people liked this",
  len(people)) % {"num": len(people)}

是可以根據(jù)第三個(gè)參數(shù)的值來(lái)翻譯字符串單復(fù)數(shù)的. 在上面的例子中,如果len(people)是1, 那么第一句翻譯將被返回, 其他情況第二句的翻譯將會(huì)返回.

翻譯最通用的模式四使用Python命名占位符變量(上面例子中的%(num)d) 因?yàn)檎嘉环梢栽诜g時(shí)變化.

這是一個(gè)正確的國(guó)際化模板:

    
       
          
       
       
         

           
{{ _("Username") }} 
           
{{ _("Password") }} 
           

           {% module xsrf_form_html() %}
         
       
     

默認(rèn)情況下, 我們通過(guò)用戶的瀏覽器發(fā)送的Accept-Language頭來(lái)發(fā)現(xiàn)用戶的區(qū)域設(shè)置. 如果我們沒(méi)有發(fā)現(xiàn)恰當(dāng)?shù)?b>Accept-Language值, 我們會(huì)使用en_US. 如果你讓用戶進(jìn)行自己偏愛(ài)的區(qū)域設(shè)置, 你可以通過(guò)復(fù)寫(xiě) RequestHandler.get_user_locale 來(lái)覆蓋默認(rèn)選擇的區(qū)域:

    class BaseHandler(tornado.web.RequestHandler):
        def get_current_user(self):
            user_id = self.get_secure_cookie("user")
            if not user_id: return None
            return self.backend.get_user_by_id(user_id)

        def get_user_locale(self):
            if "locale" not in self.current_user.prefs:
                # Use the Accept-Language header
                return None
            return self.current_user.prefs["locale"]

如果get_user_locale返回None,那我們(繼續(xù))依靠Accept-Language頭(進(jìn)行判斷).

tornado.locale 模塊支持兩種形式加載翻譯: 一種是用gettext和相關(guān)的工具的.mo格式, 還有一種是簡(jiǎn)單的.csv格式.應(yīng)用程序在啟動(dòng)時(shí)通常會(huì)調(diào)用一次 tornado.locale.load_translations或者 tornado.locale.load_gettext_translations 其中之一; 查看這些方法來(lái)獲取更多有關(guān)支持格式的詳細(xì)信息..

你可以使用 tornado.locale.get_supported_locales() 得到你的應(yīng)用所支持的區(qū)域(設(shè)置)列表. 用戶的區(qū)域是從被支持的區(qū)域中選擇距離最近的匹配得到的.例如, 如果用戶的區(qū)域是es_GT, 同時(shí)es區(qū)域是被支持的, 請(qǐng)求中的self.locale將會(huì)設(shè)置為es. 如果找不到距離最近的匹配項(xiàng), 我們將會(huì)使用en_US.

Tornado支持UI modules使它易于支持標(biāo)準(zhǔn), 在你的應(yīng)用程序中復(fù)用UI組件. UI模塊像是特殊的函數(shù)調(diào)用來(lái)渲染你的頁(yè)面上的組件并且它們可以包裝自己的CSS和JavaScript.

例如, 如果你實(shí)現(xiàn)一個(gè)博客, 并且你想要有博客入口出現(xiàn)在首頁(yè)和每篇博客頁(yè), 你可以實(shí)現(xiàn)一個(gè)Entry模塊來(lái)在這些頁(yè)面上渲染它們. 首先,為你的UI模塊新建一個(gè)Python模塊, e.g.,uimodules.py:

    class Entry(tornado.web.UIModule):
        def render(self, entry, show_comments=False):
            return self.render_string(
                "module-entry.html", entry=entry, show_comments=show_comments)

在你的應(yīng)用設(shè)置中, 使用ui_modules配置, 告訴Tornado使用uimodules.py:

    from . import uimodules

    class HomeHandler(tornado.web.RequestHandler):
        def get(self):
            entries = self.db.query("SELECT * FROM entries ORDER BY date DESC")
            self.render("home.html", entries=entries)

    class EntryHandler(tornado.web.RequestHandler):
        def get(self, entry_id):
            entry = self.db.get("SELECT * FROM entries WHERE id = %s", entry_id)
            if not entry: raise tornado.web.HTTPError(404)
            self.render("entry.html", entry=entry)

    settings = {
        "ui_modules": uimodules,
    }
    application = tornado.web.Application([
        (r"/", HomeHandler),
        (r"/entry/([0-9]+)", EntryHandler),
    ], **settings)

在一個(gè)模板中, 你可以使用{% module %}語(yǔ)法調(diào)用一個(gè)模塊. 例如,你可以調(diào)用Entry模塊從home.html:

    {% for entry in entries %}
      {% module Entry(entry) %}
    {% end %}

和entry.html:

    {% module Entry(entry, show_comments=True) %}

模塊可以包含自定義的CSS和JavaScript函數(shù), 通過(guò)復(fù)寫(xiě)embedded_css,embedded_javascript,javascript_files, 或css_files方法:

    class Entry(tornado.web.UIModule):
        def embedded_css(self):
            return ".entry { margin-bottom: 1em; }"

        def render(self, entry, show_comments=False):
            return self.render_string(
                "module-entry.html", show_comments=show_comments)

模塊CSS和JavaScript將被加載(或包含)一次, 無(wú)論模塊在一個(gè)頁(yè)面上被使用多少次. CSS總是包含在頁(yè)面的標(biāo)簽中, JavaScript 總是被包含在頁(yè)面最底部的標(biāo)簽之前.

當(dāng)不需要額外的Python代碼時(shí), 一個(gè)模板文件本身可以作為一個(gè)模塊. 例如,先前的例子可以重寫(xiě)到下面的module-entry.html:

    {{ set_resources(embedded_css=".entry { margin-bottom: 1em; }") }}
    

這個(gè)被修改過(guò)的模塊模塊可以被引用:

    {% module Template("module-entry.html", show_comments=True) %}

set_resources函數(shù)只能在模板中通過(guò){% module Template(...) %}才可用. 不像{% include ... %}指令, 模板模塊有一個(gè)明確的命名空間它們的包含模板-它們只能看到全局模板命名空間和它們自己的關(guān)鍵字參數(shù).