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 樣,請盡量減少此功能的使用。