Show Menu
主題×

HTL 區塊陳述式

HTML範本語言(HTL)區塊陳述式是直接新
data
增至現有HTML的自訂屬性。 這可讓原型靜態HTML頁面的註解更簡單且不顯眼,並將它轉換為可運作的動態範本,而不會中斷HTML程式碼的有效性。

區塊概述

HTL區塊外掛程式是由HTML元素
data-sly-*
上設定的屬性所定義。 元素可以有結束標籤或是自行結束。 屬性可以有值(可以是靜態字串或運算式),或只是布林屬性(不含值)。
<tag data-sly-BLOCK></tag> <!--/* A block is simply consists in a data-sly attribute set on an element. */--> <tag data-sly-BLOCK/> <!--/* Empty elements (without a closing tag) should have the trailing slash. */--> <tag data-sly-BLOCK="string value"/> <!--/* A block statement usually has a value passed, but not necessarily. */--> <tag data-sly-BLOCK="${expression}"/> <!--/* The passed value can be an expression as well. */--> <tag data-sly-BLOCK="${@ myArg='foo'}"/> <!--/* Or a parametric expression with arguments. */--> <tag data-sly-BLOCKONE="value" data-sly-BLOCKTWO="value"/> <!--/* Several block statements can be set on a same element. */-->
所有評估的
data-sly-*
屬性都將從生成的標籤中刪除。

識別碼

塊語句後面還可以有標識符:
<tag data-sly-BLOCK.IDENTIFIER="value"></tag>
此標識符可由block語句以各種方式使用,以下是一些示例:
<!--/* Example of statements that use the identifier to set a variable with their result: */--> <div data-sly-use.navigation="MyNavigation">${navigation.title}</div> <div data-sly-test.isEditMode="${wcmmode.edit}">${isEditMode}</div> <div data-sly-list.child="${currentPage.listChildren}">${child.properties.jcr:title}</div> <div data-sly-template.nav>Hello World</div> <!--/* The attribute statement uses the identifier to know to which attribute it should apply it's value: */--> <div data-sly-attribute.title="${properties.jcr:title}"></div> <!--/* This will create a title attribute */-->
頂層識別碼不區分大小寫(因為它們可以透過不區分大小寫的HTML屬性來設定),但是其所有屬性都區分大小寫。

可用塊語句

有許多可用的塊語句。 在同一元素上使用時,以下優先順序清單定義了塊語句的評估方式:
  1. data-sly-template
  2. data-sly-set
    ,
    data-sly-test
    ,
    data-sly-use
  3. data-sly-call
  4. data-sly-text
  5. data-sly-element
    ,
    data-sly-include
    ,
    data-sly-resource
  6. data-sly-unwrap
  7. data-sly-list
    ,
    data-sly-repeat
  8. data-sly-attribute
當兩個塊語句具有相同的優先順序時,其評估順序從左到右。

use

data-sly-use
初始化幫助程式對象(在JavaScript或Java中定義),並通過變數將其公開。
初始化JavaScript物件,其中來源檔案位於與範本相同的目錄中。 請注意,必須使用檔案名稱:
<div data-sly-use.nav="navigation.js">${nav.foo}</div>
初始化Java類,其中源檔案與模板位於同一目錄中。 請注意,必須使用類名,而不是檔案名:
<div data-sly-use.nav="Navigation">${nav.foo}</div>
初始化Java類,該類作為OSGi包的一部分安裝。 請注意,必須使用其全限定類名:
<div data-sly-use.nav="org.example.Navigation">${nav.foo}</div>
參數可以使用選項傳遞至初始化。 通常,此功能僅應用於位於區塊內的HTL程
data-sly-template
式碼:
<div data-sly-use.nav="${'navigation.js' @parentPage=currentPage}">${nav.foo}</div>
初始化另一個HTL範本,然後可使用
data-sly-call
:
<div data-sly-use.nav="navTemplate.html" data-sly-call="${nav.foo}"></div>
如需Use-API的詳細資訊,請參閱:

資源的資料密集使用

這可讓您直接在HTL中取得資源,
data-sly-use
而不需要編寫程式碼即可取得。
例如:
<div data-sly-use.product=“/etc/commerce/product/12345”> ${ product.title } </div>
另請參閱「路徑 並非一律必要」一節。

取消包裝

data-sly-unwrap
從生成的標籤中移除主機元素,同時保留其內容。 這可排除HTL呈現邏輯中需要但實際輸出中不需要的元素。
不過,應謹慎使用此陳述。 一般而言,最好將HTL標籤盡量靠近預期的輸出標籤。 換言之,新增HTL區塊陳述式時,請盡量試著只註解現有的HTML,而不要引入新元素。
例如,
<p data-sly-use.nav="navigation.js">Hello World</p>
將生產
<p>Hello World</p>
然而,
<p data-sly-use.nav="navigation.js" data-sly-unwrap>Hello World</p>
將生產
Hello World
您也可以有條件地解除包覆元素:
<div class="popup" data-sly-unwrap="${isPopup}">content</div>

設定

data-sly-set
定義具有預先定義值的新標識符。
<span data-sly-set.profile="${user.profile}">Hello, ${profile.firstName} ${profile.lastName}!</span> <a class="profile-link" href="${profile.url}">Edit your profile</a>

文字

data-sly-text
將其主機元素的內容替換為指定的文本。
例如,
<p>${properties.jcr:description}</p>
等於
<p data-sly-text="${properties.jcr:description}">Lorem ipsum</p>
兩者都會將值顯示為
jcr:description
段落文字。 第二種方法的優點是,允許HTML的不顯眼註解,同時保留原始設計人員的靜態預留位置內容。

屬性

data-sly-attribute
將屬性添加到主機元素。
例如,
<div title="${properties.jcr:title}"></div>
等於
<div title="Lorem Ipsum" data-sly-attribute.title="${properties.jcr:title}"></div>
兩者都會將屬
title
性設為的值
jcr:title
。 第二種方法的優點是,允許HTML的不顯眼註解,同時保留原始設計人員的靜態預留位置內容。
屬性會由左至右解析,最右側的屬性例項(常值或定義透過
data-sly-attribute
)優先於左側定義的相同屬性例項(定義字面或透過
data-sly-attribute
)。
請注意,其值評估為空
literal
字串的屬性(
data-sly-attribute
或透過設定)將在最終標注中移除。 此規則的一個例外是,將常值屬性設為常值空字串時,將會保留。 例如,
<div class="${''}" data-sly-attribute.id="${''}"></div>
生產、
<div></div>
但是,
<div class="" data-sly-attribute.id=""></div>
生產、
<div class=""></div>
要設定多個屬性,請傳遞對應於屬性及其值的映射對象保持鍵值對。 例如,假設
attrMap = { title: "myTitle", class: "myClass", id: "myId" }
然後,
<div data-sly-attribute="${attrMap}"></div>
生產、
<div title="myTitle" class="myClass" id="myId"></div>

元素

data-sly-element
替換主機元素的元素名稱。
例如,
<h1 data-sly-element="${titleLevel}">text</h1>
h1
值替換
titleLevel
出於安全原因,
data-sly-element
僅接受以下元素名稱:
a abbr address article aside b bdi bdo blockquote br caption cite code col colgroup data dd del dfn div dl dt em figcaption figure footer h1 h2 h3 h4 h5 h6 header i ins kbd li main mark nav ol p pre q rp rt ruby s samp section small span strong sub sup table tbody td tfoot th thead time tr u var wbr
若要設定其他元素,XSS安全性必須關閉(
@context='unsafe'
)。

測試

data-sly-test
有條件地移除主機元素及其內容。 的值會
false
移除元素; 值保留
true
元素。
例如,元素
p
及其內容只會在下列情況下轉
isShown
true
:
<p data-sly-test="${isShown}">text</p>
測試結果可指派給變數,以供稍後使用。 這通常用於構造"if else"邏輯,因為沒有明確的else語句:
<p data-sly-test.abc="${a || b || c}">is true</p> <p data-sly-test="${!abc}">or not</p>
變數一旦設定,就會在HTL檔案中具有全域範圍。
以下是比較值的一些範例:
<div data-sly-test="${properties.jcr:title == 'test'}">TEST</div> <div data-sly-test="${properties.jcr:title != 'test'}">NOT TEST</div> <div data-sly-test="${properties['jcr:title'].length > 3}">Title is longer than 3</div> <div data-sly-test="${properties['jcr:title'].length >= 0}">Title is longer or equal to zero </div> <div data-sly-test="${properties['jcr:title'].length > aemComponent.MAX_LENGTH}"> Title is longer than the limit of ${aemComponent.MAX_LENGTH} </div>

repeat

data-sly-repeat
可以根據指定的清單重複多個元素。
<div data-sly-repeat="${currentPage.listChildren}">${item.name}</div>
其運作方式與之相同
data-sly-list
,但您不需要容器元素。
以下示例說明您也可以參考
屬性
:
<div data-sly-repeat="${currentPage.listChildren}" data-sly-attribute.class="${item.name}">${item.name}</div>

list

data-sly-list
為提供的對象中的每個可枚舉屬性重複主機元素的內容。
以下是一個簡單的循環:
<dl data-sly-list="${currentPage.listChildren}"> <dt>index: ${itemList.index}</dt> <dd>value: ${item.title}</dd> </dl>
下列預設變數可在清單範圍中使用:
  • item
    : 小版本中的當前項。
  • itemList
    : 保存以下屬性的對象:
  • index
    : 零計數器(
    0..length-1
    )。
  • count
    : 單一計數器(
    1..length
    )。
  • first
    :
    true
    如果當前項目是第一個項目。
  • middle
    :
    true
    如果當前項目既不是第一個項目,也不是最後一個項目。
  • last
    :
    true
    如果當前項目是最後一個項目。
  • odd
    :
    true
    如果
    index
    奇數。
  • even
    :
    true
    如果
    index
    是扯平的話。
在語句中定義標
data-sly-list
識符可以更名和
itemList
item
量。
item
會變
<variable>
itemList
也會變
<variable>List
<dl data-sly-list.child="${currentPage.listChildren}"> <dt>index: ${childList.index}</dt> <dd>value: ${child.title}</dd> </dl>
您也可以動態存取屬性:
<dl data-sly-list.child="${myObj}"> <dt>key: ${child}</dt> <dd>value: ${myObj[child]}</dd> </dl>

資源

data-sly-resource
包含透過吊索解析度和轉換程式轉換指示資源的結果。
簡單的資源包括:
<article data-sly-resource="path/to/resource"></article>

路徑不一律為必要

請注意,如果您已擁有
data-sly-resource
資源,則不需要使用具有的路徑。 如果您已擁有資源,則可直接使用。
例如,以下是正確的。
<sly data-sly-resource="${resource.path @ decorationTagName='div'}"></sly>
但是,以下也完全可以接受。
<sly data-sly-resource="${resource @ decorationTagName='div'}"></sly>
基於以下原因,建議盡可能直接使用資源。
  • 如果您已經擁有資源,則使用路徑重新解析是額外的不必要工作。
  • 當您已擁有資源時,使用路徑可能會引入非預期的結果,因為Sling資源可以包裝或是合成,而不是在指定路徑上提供。

選項

選項允許許多其他變體:
控制資源路徑:
<article data-sly-resource="${ @ path='path/to/resource'}"></article> <article data-sly-resource="${'resource' @ prependPath='my/path'}"></article> <article data-sly-resource="${'my/path' @ appendPath='resource'}"></article>
新增(或取代)選擇器:
<article data-sly-resource="${'path/to/resource' @ selectors='selector'}"></article>
添加、替換或刪除多個選擇器:
<article data-sly-resource="${'path/to/resource' @ selectors=['s1', 's2']}"></article>
將選取器新增至現有的選取器:
<article data-sly-resource="${'path/to/resource' @ addSelectors='selector'}"></article>
從現有選擇器中刪除一些選擇器:
<article data-sly-resource="${'path/to/resource' @ removeSelectors='selector1'}"></article>
移除所有選擇器:
<article data-sly-resource="${'path/to/resource' @ removeSelectors}"></article>
覆蓋資源的資源類型:
<article data-sly-resource="${'path/to/resource' @ resourceType='my/resource/type'}"></article>
更改WCM模式:
<article data-sly-resource="${'path/to/resource' @ wcmmode='disabled'}"></article>
依預設,AEM裝飾標籤會停用、centoringTagName選項可讓它們返回,而cssClassName則會將類別新增至該元素。
<article data-sly-resource="${'path/to/resource' @ decorationTagName='span', cssClassName='className'}"></article>
AEM提供清晰簡單的邏輯,可控制包住內含元素的裝飾標籤。 如需詳細資訊,請 參閱開發元件檔案中 「裝飾標籤」。

加入

data-sly-include
以指示的HTML範本檔案(HTL、JSP、ESP等)產生的標籤取代主機元素的內容 當其對應的範本引擎處理時。 內含檔案的呈現內容將不包含目前的HTL內容(包含檔案的呈現內容); 因此,若要包含HTL檔案,必
data-sly-use
須在包含的檔案中重複目前檔案(在此情況下,通常最好使用
data-sly-template
data-sly-call
)
簡單的包括:
<section data-sly-include="path/to/template.html"></section>
JSP的加入方式相同:
<section data-sly-include="path/to/template.jsp"></section>
選項可讓您控制檔案的路徑:
<section data-sly-include="${ @ file='path/to/template.html'}"></section> <section data-sly-include="${'template.html' @ prependPath='my/path'}"></section> <section data-sly-include="${'my/path' @ appendPath='template.html'}"></section>
您也可以變更WCM模式:
<section data-sly-include="${'template.html' @ wcmmode='disabled'}"></section>

請求屬性

在和
data-sly-include
data-sly-resource
,您可
requestAttributes
以傳遞,以便在接收的HTL指令碼中使用。
這可讓您將參數正確傳入指令碼或元件。
<sly data-sly-use.settings="com.adobe.examples.htl.core.hashmap.Settings" data-sly-include="${ 'productdetails.html' @ requestAttributes=settings.settings}" />
Settings類別的Java程式碼,Map會用來傳入requestAttributes:
public class Settings extends WCMUsePojo { // used to pass is requestAttributes to data-sly-resource public Map<String, Object> settings = new HashMap<String, Object>(); @Override public void activate() throws Exception { settings.put("layout", "flex"); } }
例如,透過Sling-Model,您可以使用指定的值
requestAttributes
在此範例中,版面會透過Use-class的Map插入:
@Model(adaptables=SlingHttpServletRequest.class) public class ProductSettings { @Inject @Optional @Default(values="empty") public String layout; }

範本與呼叫

範本區塊可像函式呼叫一樣使用: 在其聲明中,它們可以得到參數,然後在調用參數時可以傳遞這些參數。 它們也允許遞回。
data-sly-template
定義範本。 HTL不會輸出主機元素及其內容
data-sly-call
調用使用資料漏洞模板定義的模板。 所呼叫範本的內容(可選地參數化)會取代呼叫的主機元素的內容。
定義靜態範本,然後呼叫它:
<template data-sly-template.one>blah</template> <div data-sly-call="${one}"></div>
定義動態範本,然後使用參數呼叫它:
<template data-sly-template.two="${ @ title}"><h1>${title}</h1></template> <div data-sly-call="${two @ title=properties.jcr:title}"></div>
位於不同檔案中的範本可以初始化為
data-sly-use
。 請注意,在此情
data-sly-use
況下
data-sly-call
,也可以放在相同元素上:
<div data-sly-use.lib="templateLib.html"> <div data-sly-call="${lib.one}"></div> <div data-sly-call="${lib.two @ title=properties.jcr:title}"></div> </div>
支援範本遞回:
<template data-sly-template.nav="${ @ page}"> <ul data-sly-list="${page.listChildren}"> <li> <div class="title">${item.title}</div> <div data-sly-call="${nav @ page=item}" data-sly-unwrap></div> </li> </ul> </template> <div data-sly-call="${nav @ page=currentPage}" data-sly-unwrap></div>

Sly元素

HTML
<sly>
標籤可用來移除目前的元素,只允許顯示其子項。 其功能與區塊元素
data-sly-unwrap
類似:
<!--/* This will display only the output of the 'header' resource, without the wrapping <sly> tag */--> <sly data-sly-resource="./header"></sly>
雖然不是有效的HTML 5標籤,
<sly>
但標籤仍可使用下列方式顯示在最終輸出中
data-sly-unwrap
:
<sly data-sly-unwrap="${false}"></sly> <!--/* outputs: <sly></sly> */-->
元素的目
<sly>
標是讓元素不輸出更明顯。 如果你想的話,還是可以用
data-sly-unwrap
與此同
data-sly-unwrap
樣,請盡量減少此功能的使用。