odoo官方文檔第十章 QWEB

QWEB

QWeb是Odoo2使用的主要模板引擎。 它是一個XML模板引擎1，主要用於生成HTML片斷和頁面。

模板指令被指定爲前綴爲t-的XML屬性，例如t-if for conditionals，其中元素和其餘屬性直接呈現。

爲了不元素呈現，佔位符元素<t>也可用，它執行其指令但不會生成任何輸出：

<t t-if="condition">
    <p>Test</p>
</t>

將致使：

<p>Test</p>

若是condition爲真，可是：

<div t-if="condition">
    <p>Test</p>
</div>

將致使:

<div>
    <p>Test</p>
</div>

data output

QWeb有一個主輸出指令，當顯示用戶提供的內容時，它會自動HTML轉義其限制XSS風險的內容：esc。

esc接受表達式，對其進行評估並打印內容：

<p><t t-esc="value"/></p>

使用設置爲42的值value進行渲染：

<p>42</p>

還有另外一個輸出指令raw，其行爲與esc相同，但不對其輸出進行HTML轉義。 顯示單獨構造的標記（例如，來自功能）或已經消毒的用戶提供的標記多是有用的。

conditionals

QWeb有一個條件指令if，它用於計算做爲屬性值給出的表達式：

<div>
    <t t-if="condition">
        <p>ok</p>
    </t>
</div>

若是條件爲真，則呈現元素：

<div>
    <p>ok</p>
</div>

但若是條件爲false，則從結果中刪除：

<div>
</div>

條件呈現適用於指令的承載，沒必要是<t>：

<div>
    <p t-if="condition">ok</p>
</div>

將給出與前一個示例相同的結果。

額外的條件分支指令t-elif和t-else也可用：

<div>
    <p t-if="user.birthday == today()">Happy bithday!</p>
    <p t-elif="user.login == 'root'">Welcome master!</p>
    <p t-else="">Welcome!</p>
</div>

loops

QWeb有一個迭代指令foreach，它接受一個返回集合的表達式迭代，第二個參數t-提供用於迭代「當前項」的名稱：

<t t-foreach="[1, 2, 3]" t-as="i">
    <p><t t-esc="i"/></p>
</t>

將呈現爲：

<p>1</p>
<p>2</p>
<p>3</p>

與條件相似，foreach適用於帶有指令屬性的元素，和

<p t-foreach="[1, 2, 3]" t-as="i">
    <t t-esc="i"/>
</p>

等同於前面的例子。

foreach能夠迭代一個數組（當前項將是當前值），一個映射（當前項將是當前鍵）或一個整數（至關於在0和0之間的數組上迭代和提供的整數不包括）。

除了經過t-as傳遞的名稱以外，foreach還爲各類數據點提供了一些其餘變量：

警告
$as將被傳遞給t-as的名稱替換

$as_all

迭代的對象

$as_value

當前迭代值，與$as和列表和整數相同，但對於映射，它提供值（其中$ as提供鍵）

$as_index

當前迭代索引（迭代的第一項索引爲0）

$as_size

集合的大小（若是可用）

$as_first

當前項是不是迭代的第一個（至關於$as_index==0）

$as_last

當前項是不是迭代的最後一項（至關於$as_index + 1 == $as_size），要求iteratee的大小可用

$as_parity

「偶數」或「奇數」，當前迭代輪次的奇偶校驗

$as_even

一個布爾標誌，指示當前迭代輪次在偶數索引上

$as_odd

一個布爾標誌，指示當前迭代輪次在奇數索引上

提供的這些額外變量和建立到foreach中的全部新變量僅在foreach的範圍內可用。 若是變量存在於foreach的上下文以外，則該值將在foreach的末尾複製到全局上下文中。

<t t-set="existing_variable" t-value="False"/>
<!-- existing_variable now False -->

<p t-foreach="[1, 2, 3]" t-as="i">
    <t t-set="existing_variable" t-value="True"/>
    <t t-set="new_variable" t-value="True"/>
    <!-- existing_variable and new_variable now True -->
</p>

<!-- existing_variable always True -->
<!-- new_variable undefined -->

attributes

QWeb能夠即時計算屬性並在輸出節點上設置計算結果。 這是經過t-att（屬性）指令完成的，該指令以3種不一樣的形式存在：

t-att-$name

建立名爲$name的屬性，計算屬性值並將結果設置爲屬性的值：

<div t-att-a="42"/>

將呈現爲：

<div a="42"></div>

t-attf-$name

與以前相同，但參數是格式字符串而不只僅是表達式，一般用於混合文字和非文字字符串（例如類）：

<t t-foreach="[1, 2, 3]" t-as="item">
    <li t-attf-class="row {{ item_parity }}"><t t-esc="item"/></li>
</t>

將呈現爲：

<li class="row even">1</li>
<li class="row odd">2</li>
<li class="row even">3</li>

t-att=mapping

若是參數是映射，則每一個（鍵，值）對生成一個新屬性及其值：

<div t-att="{'a': 1, 'b': 2}"/>

將呈現爲：

<div a="1" b="2"></div>

t-att=pair

若是參數是一對（元組或2元素的數組），則該對的第一項是屬性的名稱，第二項是值：

<div t-att="['a', 'b']"/>

將呈現爲：

<div a="b"></div>

setting variables

QWeb容許在模板中建立變量，記憶計算（屢次使用它），爲一段數據提供更清晰的名稱，......
這是經過set指令完成的，該指令採用要建立的變量的名稱。 要設置的值能夠經過兩種方式提供：

• 包含表達式的t-value屬性，將設置其評估結果：

<t t-set="foo" t-value="2 + 1"/>
<t t-esc="foo"/>

將打印3

若是沒有t-value屬性，則呈現節點的主體並將其設置爲變量的值：

<t t-set="foo">
    <li>ok</li>
</t>
<t t-esc="foo"/>

將生成＆lt; li＆gt; ok＆lt; / li＆gt; （內容在咱們使用esc指令時被轉義）

使用此操做的結果是raw指令的重要用例。

calling sub-templates

QWeb模板可用於頂級渲染，但也可使用t-call指令從另外一個模板中使用它們（以免重複或爲模板的某些部分命名）：

<t t-call="other-template"/>

若是other_template定義爲：這將使用父項的執行上下文調用命名模板：

<p><t t-value="var"/></p>

上面的調用將呈現爲

（無內容），可是：

<t t-set="var" t-value="1"/>
<t t-call="other-template"/>

將呈現爲<p> 1 </p>。

然而，這具備從t-call外部可見的問題。 或者，將在調用子模板以前評估在call指令體中設置的內容，而且能夠更改本地上下文：

然而，這具備從t-call外部可見的問題。 或者，將在調用子模板以前評估在call指令體中設置的內容，而且能夠更改本地上下文：

<t t-call="other-template">
    <t t-set="var" t-value="1"/>
</t>
<!-- "var" does not exist here -->

call指令的主體能夠是任意複雜的（不只僅是set指令），它的渲染形式在被調用的模板中可用做一個神奇的0變量：

<div>
    This template was called with content:
    <t t-raw="0"/>
</div>

被稱爲：

<t t-call="other-template">
    <em>content</em>
</t>

將致使：

<div>
    This template was called with content:
    <em>content</em>
</div>

Python

Exclusive directives(獨家指令)

asset bundles（資產包）

"smart records" fields formatting

只有在「智能」記錄（browse方法的結果）上執行字段訪問（a.b）時，才能使用t-field指令。 它可以根據字段類型自動格式化，並集成在網站的富文本版本中。

t-options可用於自定義字段，最多見的選項是widget，其餘選項依賴於字段或窗口小部件。

debugging

t-debug

使用PDB的set_trace API調用調試器。 參數應該是模塊的名稱，在該模塊上調用set_trace方法：

至關於importlib.import_module（「pdb」）。set_trace()

Helpers

Request-based

QWeb的大多數Python端用途都在控制器中（以及在HTTP請求期間），在這種狀況下，經過調用odoo.http.HttpRequest.render()能夠輕鬆地呈現存儲在數據庫中的模板（做爲視圖）：

response = http.request.render('my-template', {
    'context_value': 42
})

這會自動建立一個Response對象，該對象能夠從控制器返回（或進一步自定義以適應）。

View-based

比前一個幫助器更深層次的是ir.ui.view上的render方法：

render(cr, uid, id[, values][, engine='ir.qweb][, context])

按數據庫ID或外部ID呈現QWeb視圖/模板。 模板從ir.ui.view記錄自動加載。

在渲染上下文中設置許多默認值：

request

當前的WebRequest對象，若是有的話

debug

當前請求（若是有）是否處於調試模式

quote_plus

url編碼實用程序功能

json

相應的標準庫模塊

time

相應的標準庫模塊

datetime

相應的標準庫模塊

relativedelta

參考模塊

keep_query

keep_query幫助函數

Parameters:values -- 要傳遞給QWeb進行渲染的上下文值

engine(str)-- 用於渲染的Odoo模型的名稱，可用於在本地擴展或自定義QWeb（經過建立基於帶有更改的ir.qweb的「新」qweb）

Javascript

Exclusive directives(獨家指令)

defining templates

t-name指令只能放在模板文件的頂層（將子項指向文檔根目錄）：

<templates>
    <t t-name="template-name">
        <!-- template code -->
    </t>
</templates>

它不須要其餘參數，但能夠與<t>元素或任何其餘元素一塊兒使用。 使用<t>元素，<t>應該只有一個子元素。

模板名稱是任意字符串，可是當多個模板相關時（例如，稱爲子模板），一般使用點分隔名稱來指示層次關係。

template inheritance

模板繼承用於就地改變現有模板，例如， 向其餘模塊建立的模板添加信息。

模板繼承經過t-extend指令執行，該指令將模板的名稱做爲參數進行更改。

而後使用任意數量的t-jquery子指令執行更改：

<t t-extend="base.template">
    <t t-jquery="ul" t-operation="append">
        <li>new element</li>
    </t>
</t>

t-jquery指令採用CSS選擇器。 此選擇器用於擴展模板，以選擇應用指定t-operation的上下文節點：

append

節點的主體附加在上下文節點的末尾（在上下文節點的最後一個子節點以後）

prepend

節點的主體被添加到上下文節點（在上下文節點的第一個子節點以前插入）

before

節點的主體插入到上下文節點以前

after

節點的主體緊接在上下文節點以後插入

inner

節點的主體替換上下文節點的子節點

replace

節點的主體用於替換上下文節點自己

No operation(無操做)

若是沒有指定t-operation，模板體將被解釋爲javascript代碼，並以上下文節點做爲this的形式執行

警告
雖然比其餘操做更強大，但這種模式也很難調試和維護，建議避免使用它

debugging

javascript QWeb實現提供了一些調試鉤子：

t-log

獲取表達式參數，在呈現期間計算表達式並使用console.log記錄其結果：

<t t-set="foo" t-value="42"/>
<t t-log="foo"/>

將打印42到控制檯

t-debug

在模板呈現期間觸發調試器斷點：

<t t-if="a_test">
    <t t-debug="">
</t>

若是調試處於活動狀態，則會中止執行（具體狀況取決於瀏覽器及其開發工具）

t-js

節點的主體是在模板渲染期間執行的javascript代碼。 採用context參數，該參數是t-js主體中渲染上下文可用的名稱

<t t-set="foo" t-value="42"/>
<t t-js="ctx">
    console.log("Foo is", ctx.foo);
</t>

Helpers

core.qweb

（core是web.core模塊）QWeb2.Engine（）的一個實例，其中加載了全部模塊定義的模板文件，並引用了標準輔助對象_（下劃線），_ t（轉換函數）和JSON。

core.qweb.render可用於輕鬆呈現基本模塊模板

API

class QWeb2.Engine()

QWeb「渲染器」處理QWeb的大部分邏輯（加載，解析，編譯和渲染模板）。

OpenERP Web爲核心模塊中的用戶實例化一個，並將其導出到core.qweb。 它還將各類模塊的全部模板文件加載到該QWeb實例中。

QWeb2.Engine()也可用做「模板命名空間」。

QWeb2.Engine.render(template[, context])

使用context（若是提供）將先前加載的模板呈現給String，以查找在模板呈現期間訪問的變量（例如，要顯示的字符串）。

Arguments:

template(String)-- 要呈現的模板的名稱

context (Object)-- 用於模板渲染的基本命名空間

Returns:String

引擎公開了另外一種在某些狀況下可能有用的方法（例如，若是你須要一個單獨的模板命名空間，在OpenERP Web中，看板視圖能夠獲得他們本身的QWeb2.Engine()實例，這樣他們的模板就不會與更通常的碰撞「 模塊「模板」：

QWeb2.Engine.add_template(templates)

在QWeb實例中加載模板文件（模板集合）。 模板能夠指定爲：

An XML string

QWeb將嘗試將其解析爲XML文檔，而後加載它。

A URL

QWeb將嘗試下載URL內容，而後加載生成的XML字符串。

A Document or Node

QWeb將遍歷文檔的第一級（提供的根的子節點）並加載任何命名的模板或模板覆蓋。

-----------------------------

---

QWeb2.Engine()還公開了行爲定製的各類屬性：

QWeb2.Engine.prefix

用於在解析期間識別指令的前綴。 一個字符串。 默認狀況下，t。

QWeb2.Engine.debug

將引擎置於「調試模式」的布爾標誌。 一般，QWeb會攔截模板執行期間引起的任何錯誤。 在調試模式下，它會在不攔截全部異常的狀況下經過。

QWeb2.Engine.jQuery

模板繼承處理期間使用的jQuery實例。 默認爲window.jQuery。

QWeb2.Engine.preprocess_node

一個功能。 若是存在，則在將每一個DOM節點編譯爲模板代碼以前調用。 在OpenERP Web中，這用於自動翻譯模板中的文本內容和一些屬性。 默認爲null。

• [1]它與Genshi相似，儘管它不使用（而且不支持）XML命名空間
• [2]雖然它使用了一些其餘的，不管是出於歷史緣由仍是由於它們更適合用例。 Odoo 9.0仍然依賴於Jinja和Mako。