SCF Handlebars協助程式 scf-handlebars-helpers

Handlebars Helpers (協助程式)是可從Handlebars指令碼呼叫的方法,以方便使用SCF元件。

實施包含使用者端和伺服器端定義。 開發人員也可以建立自訂協助程式。

透過AEM Communities傳送的自訂SCF協助程式定義於使用者端資料庫

  • /etc/clientlibs/social/commons/scf/helpers.js
NOTE
請務必安裝最新Communities Feature Pack

縮寫 abbreviate

協助程式傳回符合maxWords和maxLength屬性的縮寫字串。

提供要縮寫的字串作為內容。 如果未提供任何內容,則會傳回空字串。

首先,將前後關聯裁剪為maxLength,然後將前後關聯分割為單字並縮小為maxWords。

如果safeString設為true,則傳回的字串為SafeString。

參數 parameters

  • 內容:字串

    (選用)預設為空字串

  • maxLength:數字

    (選用)預設值是前後關聯的長度。

  • maxWords:數字

    (選用)預設值是裁剪字串中的字數。

  • safeString:布林值

    (選用)如果為true,則傳回Handlebars.SafeString()。 預設值為false。

範例 examples

{{abbreviate subject maxWords=2}}

/*
If subject =
    "AEM Communities - Site Creation Wizard"

Then abbreviate would return
    "AEM Communities".
*/
{{{abbreviate message safeString=true maxLength=30}}}

/*
If message =
    "The goal of AEM Communities is to quickly create a community engagement site."

Then abbreviate would return
    "The goal of AEM Communities is"
*/

Content-loadmore content-loadmore

協助程式可在div下新增兩個跨頁,一個用於全文,另一個用於較少文字,並能在兩個檢視之間切換。

參數 parameters-1

  • 內容:字串

    (選用)預設為空字串。

  • numChars:數字

    (選用)不顯示全文時顯示的字元數。 預設值為100。

  • moreText:字串

    (選用)要顯示的文字,表示還有更多文字要顯示。 預設值為「更多」。

  • 省略文字:字串

    (選用)要顯示的文字,表示有隱藏的文字。 預設值為「……」。

  • safeString:布林值

    (選用)布林值,指出在傳回結果之前是否要套用Handlebars.SafeString()。 預設值為false。

範例 example

{{content-loadmore  context numChars=32  moreText="go on"  ellipsesText="..." }}

/*
If context =
    "Here is the initial less content and this is more content."

Then content-loadmore would return
    "Here is the initial less content<span class="moreelipses">...</span> <span class="scf-morecontent"><span>and this is more content.</span>  <a href="" class="scf-morelink" evt="click=toggleContent">go on</a></span>"
*/

DateUtil dateutil

協助程式可傳回格式化的日期字串。

參數 parameters-2

  • 內容:數字

    (選用)從1970年1月1日起位移的毫秒值(紀元)。 預設值為目前日期。

  • 格式:字串

    (選用)要套用的日期格式。 預設值為"YYYY-MM-DDTHH:mm:ss.sssZ",結果顯示為"2015-03-18T18:17:13-07:00"

範例 examples-1

{{dateUtil this.memberSince format="dd MMM yyyy, hh:mm"}}

// returns "18 Mar 2015, 18:17"
{{dateUtil this.birthday format="MM-DD-YYYY"}}

// returns "03-18-2015"

等於 equals

根據等式條件傳回內容的協助程式。

參數 parameters-3

  • lvalue:字串

    要比較的左側值。

  • rvalue:字串

    要比較的右側值。

範例 example-1

{{#equals  value "some-value"}}
  <div>They are EQUAL!</div>
`{{else}}`
  <div>They are NOT equal!</div>
{{/equals}}

If-wcm-mode if-wcm-mode

區塊協助程式,可針對字串分隔的模式清單來測試WCM模式的目前值。

參數 parameters-4

  • 內容:字串

    (選用)要翻譯的字串。 若未提供預設值,則為必要。

  • 模式:字串

    (選擇性)要測試是否設定的WCM模式的逗號分隔清單。

範例 example-2

{{#if-wcm-mode mode="DESIGN, EDIT"}}
 ...
{else}}
 ...
`{{/if-wcm-mode}}`

i18n i-n

此協助程式會覆寫Handlebars協助程式'i18n'。

另請參閱在JavaScript程式碼中國際化字串

參數 parameters-5

  • 內容:字串

    (選用)要翻譯的字串。 若未提供預設值,則為必要。

  • 預設:字串

    (選用)要翻譯的預設字串。 如果未提供內容,則為必要。

  • 註解:字串

    (選用)翻譯提示

範例 example-3

{{i18n "hello"}}
{{i18n "hello" comment="greeting" default="bonjour"}}

包含 include

將元件加入為範本中不存在資源的協助程式。

與新增為JCR節點的資源相比,此方法讓資源更容易以程式設計方式自訂。 請參閱新增或包含Communities元件

只有少數幾個社群元件可供包含。

此協助程式僅適用於伺服器端,可提供類似於JSP指令碼的cq:include的功能。

參數 parameters-6

  • 內容:字串或物件

    (選擇性,除非提供相對路徑)

    使用this傳遞目前內容。

    使用this.id取得位於id的資源,以呈現要求的resourceType。

  • resourceType:字串

    (選擇性)資源型別預設為來自前後關聯的資源型別。

  • 範本:字串

    元件指令碼的路徑。

  • 路徑:字串

    (必要)資源的路徑。 如果路徑是相對路徑,則必須提供上下文,否則會傳回空字串。

  • authoringDisabled:布林值

    (選用)預設為false。 僅供內部使用。

範例 example-4

{{include this.id path="comments" resourceType="social/commons/components/hbs/comments"}}

this.id + /comments中包含新的comments元件。

IncludeClientLib includeclientlib

包含AEM html使用者端程式庫的協助程式,可以是js、css或主題程式庫。 對於不同型別的多個包含專案(例如js和css),此標籤必須在Handlebars指令碼中多次使用。

此協助程式僅適用於伺服器端,提供類似於JSP指令碼的ui:includeClientLib的功能。

參數 parameters-7

  • 類別:字串

    (選用)以逗號分隔的使用者端程式庫類別清單。 納入指定類別的所有JavaScript和CSS資料庫。 主題名稱會從請求中擷取。

  • 佈景主題:字串

    (選用)以逗號分隔的使用者端程式庫類別清單。 包含指定類別的所有主題相關資料庫(CSS和JS)。 主題名稱會從請求中擷取。

  • js:字串

    (選用)以逗號分隔的使用者端程式庫類別清單。 包含指定類別的所有JavaScript程式庫。

  • css:字串

    (選用)以逗號分隔的使用者端程式庫類別清單。 包含指定類別的所有CSS資料庫。

範例 examples-2

// all: js + theme (theme-js + css)
{{includeClientLib categories="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js" type="text/javascript"></script>

// only js libs
{{includeClientLib js="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js" type="text/javascript"></script>

// theme only (theme-js + css)
{{includeClientLib theme="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js" type="text/javascript"></script>

// css only
{{includeClientLib css="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">

美化時間 pretty-time

協助程式會顯示到達截止點之前經過的時間,之後會顯示一般日期格式。

例如:

  • 12小時前
  • 7天前

參數 parameters-8

  • 內容:數字

    與「現在」進行比較的過去時間。 時間以自1970年1月1日起位移的毫秒值表示(紀元)。

  • daysCutoff:數字

    切換到實際日期之前的天數。 預設值為60。

範例 example-5

{{pretty-time this.published daysCutoff=7}}

/*
Depending on how long in the past, may return

  "3 minutes ago"

  "3 hours ago"

  "3 days ago"
*/

Xss-html xss-html

協助程式會為HTML元素內容編碼來源字串,以協助抵禦XSS。

注意:此協助程式不是驗證器,且不可用於寫入屬性值。

參數 parameters-9

  • 內容:物件

    要編碼的HTML。

範例 example-6

<p>{{xss-html forum-ugc}}</p>

Xss-htmlAttr xss-htmlattr

協助程式會編碼來源字串,以寫入HTML屬性值,協助防範XSS。

注意:此協助程式不是驗證器,且不可用於撰寫可操作的屬性(href、src、事件處理常式)。

參數 parameters-10

  • 內容:物件

    要編碼的HTML。

範例 example-7

<div id={{xss-htmlAttr id}} />

Xss-jsString xss-jsstring

協助程式會針對要寫入JavaScript字串內容的來源字串進行編碼,以協助防範XSS。

注意:此協助程式不是驗證器,且不可用來寫入任意JavaScript。

參數 parameters-11

  • 內容:物件

    要編碼的HTML。

範例 example-8

var input = {{xss-jsString topic-title}}

Xss-validHref xss-validhref

協助程式會清理要當作HTMLhref或srce屬性值寫入的URL,以協助防範XSS。

注意:此協助程式可能會傳回空字串。

參數 parameters-12

  • 內容:物件

    要清理的URL。

範例 example-9

<a href="{{xss-validHref url}}">my link</a>

Handlebars.js基本概述 handlebars-js-basic-overview

  • Handlebars協助程式呼叫是簡單的識別碼(協助程式的​ 名稱),後面接著零個或多個以空格分隔的引數。

  • 引數可以是簡單字串、數字、布林值或JSON物件,以及作為最後一個引數的鍵值值配對(雜湊引數)選用序列。

  • 雜湊引數中的索引鍵必須是簡單識別碼。

  • 雜湊引數中的值是Handlebars運算式:簡單識別碼、路徑或字串。

  • Handlebars協助程式一律可以使用目前的內容this

  • 內容可以是字串、數字、布林值或JSON資料物件。

  • 您可以將巢狀內嵌在目前內容中的物件當作內容傳遞,例如this.urlthis.id (請參閱下列簡單和區塊協助程式的範例)。

  • 區塊協助程式是可從範本中任何位置呼叫的函式。 他們每次可使用不同的內容呼叫範本區塊零次或多次。 其中包含介於{{#*name*}}{{/*name*}}的內容。

  • Handlebars為名為'options'的協助程式提供最終引數。 特殊物件'options'包括

    • 選擇性私人資料(options.data)
    • 呼叫的選用機碼值屬性(options.hash)
    • 啟動本身的功能(options.fn())
    • 可叫用本身的反函式(options.inverse())
  • 建議從協助程式傳回的HTML字串內容為SafeString。

Handlebars.js檔案中的簡單協助程式範例: an-example-of-a-simple-helper-from-handlebars-js-documentation

Handlebars.registerHelper('link_to', function(title, options) {
    return new Handlebars.SafeString('<a href="/posts' + this.url + '">' + title + "!</a>");
});

var context = {posts: [
    {url: "/hello-world",
      body: "Hello World!"}
  ] };

// when link_to is called, posts is the current context
var source = '<ul>`{{#posts}}`<li>{{{link_to "Post"}}}</li>`{{/posts}}`</ul>'

var template = Handlebars.compile(source);

template(context);

會呈現:

<ul>
<li><a href="/posts/hello-world">Post!</a></li>
</ul>

Handlebars.js檔案中的區塊協助程式範例: an-example-of-a-block-helper-from-handlebars-js-documentation

Handlebars.registerHelper('link', function(options) {
    return new Handlebars.SafeString('<a href="/people/' + this.id + '">' + options.fn(this) + '</a>');
});

var data = { "people": [
  { "name": "Alan", "id": 1 },
  { "name": "Yehuda", "id": 2 }
]};

// when link is called, people is the current context
var source = "<ul>`{{#people}}`<li>`{{#link}}``{{name}}``{{/link}}`</li>`{{/people}}`</ul>";

var template = Handlebars.compile(source);

template(data);

會呈現:
<ul>
<li><a href="/people/1">艾倫</a></li>
<li><a href="/people/2">耶胡達</a></li>
</ul>

自訂SCF協助程式 custom-scf-helpers

必須在伺服器端和使用者端實作自訂協助程式,尤其是在傳遞資料時。 對於SCF,大多數範本會在伺服器端編譯並轉譯,因為伺服器會在要求頁面時產生指定元件的HTML。

伺服器端自訂協助程式 server-side-custom-helpers

若要在伺服器端實作並註冊自訂SCF Helper,只要實作Java™介面TemplateHelper,讓它成為OSGi服務,並將其安裝為OSGi套件組合的一部分。

例如:

FooTextHelper.java footexthelper-java

/** Custom Handlebars Helper */

package com.my.helpers;

import java.io.IOException;

import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;

import com.adobe.cq.social.handlebars.api.TemplateHelper;
import com.github.jknack.handlebars.Options;

@Service
@Component
public class FooTextHelper implements TemplateHelper<String>{

    @Override
    public CharSequence apply(String context, Options options) throws IOException {
        return "foo-" + context;
    }

    @Override
    public String getHelperName() {
        return "foo-text";
    }

    @Override
    public Class<String> getContextType() {
        return String.class;
    }
}
NOTE
也必須為使用者端建立為伺服器端建立的協助程式。
元件會在登入使用者的使用者端重新呈現,如果找不到使用者端協助程式,元件會消失。

使用者端自訂協助程式 client-side-custom-helpers

使用者端協助程式是透過叫用Handlebars.registerHelper()註冊的Handlebars指令碼。
例如:

custom-helpers.js custom-helpers-js

function(Handlebars, SCF, $CQ) {

    Handlebars.registerHelper('foo-text', function(context, options) {
        if (!context) {
            return "";
        }
        return "foo-" + context;
    });

})(Handlebars, SCF, $CQ);

自訂使用者端協助程式必須新增至自訂使用者端資料庫。
clientlib必須:

  • cq.social.scf上包含相依性。
  • 載入Handlebars之後載入。
  • 成為包含

注意: SCF協助程式定義於/etc/clientlibs/social/commons/scf/helpers.js

recommendation-more-help
81e2cd9d-0789-409d-b87c-2a8ce4f28791