HTL 運算式語言

HTML範本語言使用運算式語言來存取提供HTML輸出動態元素的資料結構。 這些運算式以字元${}分隔。 為避免格式錯誤的HTML,運算式只能用於屬性值、元素內容或注釋中。

<!-- ${component.path} -->
<h1 class="${component.name}">
    ${properties.jcr:title}
</h1>

運算式可透過預先標示\字元來逸出,例如\${test}將會演算${test}

注意

要試用本頁上提供的示例,可以使用名為讀取評估打印循環的即時執行環境。

運算式語法包括變數literals運算子選項:

變數

變數是儲存資料值或物件的容器。 變數的名稱稱為識別碼。

HTL不需指定任何項目,就可讓您在包含global.jsp後,存取JSP中常用的所有物件。 全域物件頁面提供HTL可存取的所有物件清單。

屬性訪問

存取變數屬性的方法有兩種:點記號或方括弧記號:

${currentPage.title}  
${currentPage['title']} or ${currentPage["title"]}

大多數情況下,最好使用更簡單的點標籤法,並且應使用括弧標籤法來訪問包含無效標識符字元的屬性,或動態訪問屬性。 以下兩章將提供這兩個案例的詳細資訊。

訪問的屬性可以是函式,但不支援傳遞參數,因此只能訪問不期望參數的函式,如getter。 這是一個需要的限制,其目的是減少內嵌在運算式中的邏輯量。 如果需要,可使用data-sly-use陳述式將參數傳遞至邏輯。

上例中還顯示了Java getter函式,如getTitle(),可以存取,而不預先標示get,並降低後面的字元大小寫。

有效識別碼字元

變數的名稱(稱為識別碼)符合特定規則。 這些字元必須以字母(A-Za-z)或底線(_)開頭,後續字元也可以是數字(0-9)或冒號(:)。 標識符中不能使用Unicode字母,如åü

由於冒號(:)字元在AEM屬性名稱中很常見,因此應強調它是有效的識別碼字元:

${properties.jcr:title}

括弧符號可用於訪問包含無效標識符字元的屬性,如以下示例中的空格字元:

${properties['my property']}

動態訪問成員

${properties[myVar]}

Null值的權限處理

${currentPage.lastModified.time.toString}

文字

常值是表示固定值的符號。

布林值 (Boolean)

布爾值表示邏輯實體,可以有兩個值:truefalse

${true} ${false}

數字

只有一種數字類型:正整數。 其他數字格式(如浮點)在變數中受支援,但不能表示為文字。

${42}

字串

字串代表文字資料,可以是單引號或雙引號:

${'foo'} ${"bar"}

除了普通字元外,還可使用下列特殊字元:

  • \\ 反斜線字元

  • \' 單引號(或撇號)

  • \" 雙引號

  • \t 頁籤

  • \n 新行

  • \r 歸位

  • \f 表單摘要

  • \b 回空格

  • \uXXXX 由四個十六進位數字XXXX指定的Unicode字元。
    一些有用的Unicode轉義序列包括:

    • \u0022"
    • \u0027'

對於上方未列出的字元,反斜線字元前面會顯示錯誤。

以下是如何使用字串逸出的一些範例:

<p>${'it\'s great, she said "yes!"'}</p>
<p title="${'it\'s great, she said \u0022yes!\u0022'}">...</p>

這會導致下列輸出,因為HTL會套用內容特定逸出:

<p>it&#39;s great, she said &#34;yes!&#34;</p>
<p title="it&#39;s great, she said &#34;yes!&#34;">...</p>

陣列

陣列是一組有序值,可以用名稱和索引引用。 其元素類型可混合。

${[1,2,3,4]}
${myArray[2]}

陣列在提供模板值清單時很有用。

<ul data-sly-list="${[1,2,3,4]}">
  <li>${item}</li>
</ul>

運算子

邏輯運算子

這些運算子通常與布林值搭配使用,但是,就像在JavaScript中一樣,它們實際上會傳回其中一個指定運算元的值,因此當與非布林值搭配使用時,可能會傳回非布林值。

如果值可轉換為true,則該值稱為truthy。 如果值可轉換為false,則該值稱為falsy。 可轉換為false的值為未定義的變數、空值、數字零和空字串。

邏輯NOT

${!myVar} 如果 false 其單個操作數可轉換為 true;否則,返回 true

例如,這可用於反轉測試條件,例如只有在沒有子頁面時才顯示元素:

<p data-sly-test="${!currentPage.hasChild}">current page has no children</p>

邏輯AND

${varOne && varTwo} 如果 varOne 是假的,則返回;否則,返回 varTwo

此運算子可用來一次測試兩個條件,例如驗證是否存在兩個屬性:

<div data-sly-test="${properties.jcr:title && properties.jcr:description}">
    <h1>${properties.jcr:title}</h1>
    <p>${properties.jcr:description}</p>
</div>

邏輯AND運算子也可用來有條件地顯示HTML屬性,因為HTL會移除值動態設定為false或空字串的屬性。 因此,在以下範例中,class屬性僅在logic.showClass為真且logic.className存在且不為空時顯示:

<div class="${logic.showClass && logic.className}">...</div>

邏輯OR

${varOne || varTwo} 如果 varOne 真實,則返回;否則,返回 varTwo

此運算子可用來測試是否適用下列兩種條件之一,例如驗證是否存在至少一個屬性:

<div data-sly-test="${properties.jcr:title || properties.jcr:description}">...</div>

由於邏輯OR運算子會傳回第一個真實的變數,因此也可非常方便地用來提供備援值。

它也可用來有條件地顯示HTML屬性,因為HTL會移除由運算式設定的值,以評估為false或空字串的屬性。 因此,以下範例將顯示​properties.jcr:​標題(如果存在且不為空),否則它會返回顯示​properties.jcr:description(如果存在且不為空),否則它將顯示消息「未提供標題或說明」:

<p>${properties.jcr:title || properties.jcr:description || "no title or description provided"}</p>

條件(三元)運算子

${varCondition ? varOne : varTwo} 如果 varOnevarCondition 實,則返回;否則,它將返回 varTwo

此運算子通常可用來定義運算式中的條件,例如根據頁面狀態顯示不同的訊息:

<p>${currentPage.isLocked ? "page is locked" : "page can be edited"}</p>
秘訣

由於識別碼中也允許冒號字元,因此最好將三元運算子與空白區分開,以清楚說明剖析器:

<p>${properties.showDescription ? properties.jcr:description : properties.jcr:title}</p>

比較運算子

等式和不等式運算子僅支援相同類型的操作數。 當類型不符合時,會顯示錯誤。

  • 如果字串具有相同的字元順序,則字串是相等的。
  • 數值相同時,數值相等
  • 如果兩者均為true或兩者均為false,則兩者均相等。
  • Null或未定義的變數彼此相等。

${varOne == varTwo}truevarOnevarTwo 等則傳回。

${varOne != varTwo}truevarOnevarTwo 相等則傳回。

關係運算子僅支援數字操作數。 對於所有其他類型,都會顯示錯誤。

${varOne > varTwo}true 大於 varOne 則傳回 varTwo

${varOne < varTwo}truevarOne 於則傳回 varTwo

${varOne >= varTwo}true 大於或等於 varOne 則傳回 varTwo

${varOne <= varTwo}truevarOne 於或等於,則傳回 varTwo

將括弧分組

分組運算子()控制運算式中評估的優先順序。

${varOne && (varTwo || varThree)}

選項

運算式選項可對運算式執行並加以修改,或與區塊陳述式搭配使用時,可當成參數。

@之後的一切都是選項:

${myVar @ optOne}

選項可以有值,該值可以是變數或常值:

${myVar @ optOne=someVar}
${myVar @ optOne='bar'}
${myVar @ optOne=10}
${myVar @ optOne=true}

多個選項以逗號分隔:

${myVar @ optOne, optTwo=bar}

也可以使用只包含選項的參數表達式:

${@ optOne, optTwo=bar}

字串格式

將列舉的預留位置{n}取代為對應變數的選項:

${'Page {0} of {1}' @ format=[current, total]}

URL操縱

有新的URL操縱集可供使用。

請參閱下列使用範例:

將html副檔名新增至路徑。

<a href="${item.path @ extension = 'html'}">${item.name}</a>

將html副檔名和選擇器新增至路徑。

<a href="${item.path @ extension = 'html', selectors='products'}">${item.name}</a>

將html副檔名和片段(#value)新增至路徑。

<a href="${item.path @ extension = 'html', fragment=item.name}">${item.name}</a>

@extension適用於所有藍本,檢查是否添加副檔名。

${ link @ extension = 'html' }

數字/日期格式

HTL允許數字和日期的原生格式化,毋需編寫自訂程式碼。 這也支援時區和地區設定。

下列範例顯示,先指定格式,再指定需要格式的值:

<h2>${ 'dd-MMMM-yyyy hh:mm:ss' @
           format=currentPage.lastModified,
           timezone='PST',
           locale='fr'}</h2>

<h2>${ '#.00' @ format=300}</h2>
注意

有關可使用格式的完整詳細資訊,請參閱HTL-specification

國際化

使用目前的字典將字串轉譯為目前​source​的語言(請參閱下文)。 如果找不到任何轉譯,則會使用原始字串。

${'Page' @ i18n}

提示選項可用於為翻譯者提供注釋,指定使用文本的上下文:

${'Page' @ i18n, hint='Translation Hint'}

語言的預設源為resource,這表示文本將被翻譯為與內容相同的語言。 這可以變更為user,這表示語言是從瀏覽器地區設定或登入使用者的地區設定取得:

${'Page' @ i18n, source='user'}

提供明確的語言環境會覆蓋源設定:

${'Page' @ i18n, locale='en-US'}

若要將變數內嵌至已翻譯的字串,可使用format選項:

${'Page {0} of {1}' @ i18n, format=[current, total]}

陣列連接

依預設,當將陣列顯示為文字時,HTL會顯示逗號分隔值(無間距)。

使用聯接選項指定不同的分隔符:

${['one', 'two'] @ join='; '}

顯示上下文

HTL運算式的顯示內容會參照其在HTML頁面結構中的位置。 例如,如果表達式出現在原地,在渲染後將生成文本節點,則它據稱位於text上下文中。 如果在屬性的值中找到,則表示它位於attribute上下文中,依此類推。

除了指令碼(JS)和樣式(CSS)上下文外,HTL會自動偵測運算式的上下文並適當地逸出它們,以防止XSS安全性問題。 在指令碼和CSS中,必須明確設定所要的上下文行為。 此外,在需要覆蓋自動行為的任何其他情況下,也可以顯式設定上下文行為。

在這裡,我們有三個變數:

  • properties.link (上 uri 下文)
  • properties.title (內attribute 容)
  • properties.text (內text 容)

HTL將根據其各自上下文的安全要求以不同方式逃離其中每一個。 一般情況下,如下情況,則不需要明確的上下文設定:

<a href="${properties.link}" title="${properties.title}">${properties.text}</a>

要安全輸出標籤(即,表達式本身評估為HTML),請使用html上下文:

<div>${properties.richText @ context='html'}</div>

必須為樣式上下文設定顯式上下文:

<span style="color: ${properties.color @ context='styleToken'};">...</span>

必須為指令碼上下文設定顯式上下文:

<span onclick="${properties.function @ context='scriptToken'}();">...</span>

逸出和XSS保護也可以關閉:

<div>${myScript @ context='unsafe'}</div>

內容設定

上下文 使用時機 它的功能
text 元素內容的預設值 對所有HTML特殊字元進行編碼。
html 要安全輸出標籤 篩選HTML以符合AntiSamy原則規則,移除不符合規則的項目。
attribute 屬性值的預設值 對所有HTML特殊字元進行編碼。
uri 要顯示連結和路徑,請預設href和src屬性值 驗證URI是否寫入為href或src屬性值,如果驗證失敗則不輸出任何內容。
number 要顯示數字 驗證包含整數的URI,如果驗證失敗,則輸出零。
attributeName 設定屬性名稱時的data-sly-attribute預設值 驗證屬性名稱,如果驗證失敗,則不輸出任何內容。
elementName 預設的資料密碼元素 驗證元素名稱,如果驗證失敗,則不輸出任何內容。
scriptToken 對於JS識別碼、常值數字或常值字串 驗證JavaScript Token,如果驗證失敗,則不會輸出任何內容。
scriptString 在JS字串中 編碼將從字串中分開的字元。
scriptComment 在JS注釋中 驗證JavaScript注釋,如果驗證失敗,則不會輸出任何內容。
styleToken 用於CSS識別碼、數字、尺寸、字串、十六進位色彩或函式。 驗證CSS Token,如果驗證失敗,則不會輸出任何內容。
styleString 在CSS字串中 編碼將從字串中分開的字元。
styleComment 在CSS注釋中 驗證CSS注釋,如果驗證失敗則不輸出任何內容。
unsafe 只有當上述任何一個 完全禁用轉義和XSS保護。

本頁內容