SCF Handlebars Helpers

‹功能基本工具 服务器端自定义
客户端自定义

Handlebars Helpers(帮助器)是从Handlebars脚本调用的方法,用于方便与SCF组件一起使用。

该实现包括客户端和服务器端定义。 开发者也可以创建定制帮助器。

随AEM Communities提供的自定义SCF帮助器在客户端库中定义:

  • /etc/clientlibs/social/commons/scf/helpers.js
注意

请务必安装最新的Communities功能包

缩写

返回符合maxWords和maxLength属性的缩写字符串的帮助程序。

要缩写的字符串作为上下文提供。 如果未提供上下文,则返回空字符串。

首先,将上下文裁切为maxLength,然后将上下文切片为单词并缩小为maxWords。

如果safeString设置为true,则返回的字符串为SafeString。

参数

  • 上下文:字符串

    (可选)默认值是空字符串

  • maxLength:数字

    (可选)默认值是上下文的长度。

  • maxWords:数字

    (可选)默认值是修剪字符串中的字数。

  • safeString:布尔值

    (可选)如果为true,则返回Handlebars.SafeString()。 默认值为false。

示例

{{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

一个帮助程序,用于在div下添加两个跨距,一个用于全文,另一个用于较少的文本,能够在两个视图之间切换。

参数

  • 上下文:字符串

    (可选)默认值是空字符串。

  • numChars:数字

    (可选)不显示全文时显示的字符数。 默认值为100。

  • moreText:字符串

    (可选)要显示的文本,表示要显示的文本更多。 默认为“更多”。

  • 椭圆文本:字符串

    (可选)要显示的文本,指示存在隐藏文本。 默认值为“…”。

  • safeString:布尔值

    (可选)布尔值,指示是否在返回结果之前应用Handlebars.SafeString()。 默认值为false。

示例

{{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

返回格式化日期字符串的助手。

参数

  • 上下文:数字

    (可选)1970年1月1日(新纪元)以后毫秒值的偏移量。 默认为当前日期。

  • 格式:字符串

    (可选)要应用的日期格式。 默认值为“YYYY-MM-DDTHH:mm:ss.sssZ”,结果显示为“2015-03-18T18:17:13-07:00”

示例

{{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"

等于

帮助者根据等式条件返回内容。

参数

  • lvalue:字符串

    要比较的左手值。

  • rvalue:字符串

    要比较的右边值。

示例

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

If-wcm-mode

一个块辅助器,它根据字符串分隔的模式列表测试WCM模式的当前值。

参数

  • 上下文:字符串

    (可选)要翻译的字符串。 如果未提供默认值,则此为必需字段。

  • 模式:字符串

    (可选)要测试是否已设置的逗号分隔列表WCM模式

示例

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

i18n

该助手会覆盖Handlebars助手'i18n'。

另请参阅在JavaScript代码中国际化字符串

参数

  • 上下文:字符串

    (可选)要翻译的字符串。 如果未提供默认值,则此为必需字段。

  • 默认:字符串

    (可选)要翻译的默认字符串。 如果未提供上下文,则此为必需字段。

  • 注释:字符串

    (可选)翻译提示

示例

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

包括

帮助程序,用于将组件作为非现有资源包含在模板中。

这允许以编程方式对资源进行自定义,比作为JCR节点添加的资源更容易。 请参阅添加或包括社区组件

只包含少数几个社区组件。 对于AEM 6.1,可包含的是注释评级评论投票

此帮助程序仅适用于服务器端,它为JSP脚本提供类似于cq:include的功能。

参数

  • 上下文:字符串或对象

    (可选,除非提供相对路径)

    使用this传递当前上下文。

    使用this.id获取位于id的资源,以呈现所请求的resourceType。

  • resourceType:字符串

    (可选)资源类型将默认为上下文中的资源类型。

  • 模板:字符串

    组件脚本的路径。

  • 路径:字符串

    (必需)资源的路径。 如果路径是相对的,则必须提供上下文,否则返回空字符串。

  • authoringDisabled:布尔值

    (可选)默认值为false。 仅供内部使用。

示例

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

这将包括位于this.id + /comments的新注释组件。

IncludeClientLib

包含AEM html客户端库的帮助程序,它可以是js、css或主题库。 对于多个不同类型的包含项,例如js和css,此标记需要在Handlebars脚本中多次使用。

此帮助程序仅适用于服务器端,它为JSP脚本提供类似于ui:includeClientLib的功能。

参数

  • 类别:字符串

    (可选)以逗号分隔的列表客户端库类别。 这将包括给定类别的所有Javascript和CSS库。 主题名称会从请求中提取。

  • 主题:字符串

    (可选)以逗号分隔的列表客户端库类别。 这将包括给定类别的所有与主题相关的库(CSS和JS)。 主题名称会从请求中提取。

  • js:字符串

    (可选)以逗号分隔的列表客户端库类别。 这将包括给定类别的所有Javascript库。

  • css:字符串

    (可选)以逗号分隔的列表客户端库类别。 这将包括给定类别的所有CSS库。

示例

// 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?lang=zh-Hans" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css?lang=zh-Hans" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=zh-Hans" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js?lang=zh-Hans" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js?lang=zh-Hans" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=zh-Hans" 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?lang=zh-Hans" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js?lang=zh-Hans" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=zh-Hans" 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?lang=zh-Hans" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=zh-Hans" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js?lang=zh-Hans" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=zh-Hans" 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?lang=zh-Hans" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css?lang=zh-Hans" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=zh-Hans" rel="stylesheet" type="text/css">

Pretty-time

一个帮助程序,用于显示已经过多少时间到截止点,之后显示常规日期格式。

例如:

  • 12小时前
  • 7天前

参数

  • 上下文:数字

    过去与“现在”比较的时间。 时间表示为从1970年1月1日(纪元)起抵消的毫秒值。

  • daysCustofm:数字

    切换到实际日期前的天数。 默认值为60。

示例

{{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

帮助程序,它对HTML元素内容的源字符串进行编码,以帮助防止XSS。

注意:它不是validator,不用于写入属性值。

参数

  • 上下文:对象

    要编码的HTML。

示例

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

Xss-htmlAttr

一种帮助程序,它对源字符串进行编码以写入HTML属性值,以帮助防止XSS。

注意:它不是validator,不用于编写actionalable属性(href、src、事件处理函数)。

参数

  • 上下文:对象

    要编码的HTML。

示例

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

Xss-jsString

一种帮助程序,它对源字符串进行编码以写入JavaScript字符串内容,以帮助防止XSS。

注意:它不是validator,不用于写入任意JavaScript。

参数

  • 上下文:对象

    要编码的HTML。

示例

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

Xss-validHref

帮助程序,它清理URL以编写为HTML href或srce属性值以帮助防止XSS。

注意:这可能返回空字符串

参数

  • 上下文:对象

    要清理的URL。

示例

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

Handlebars.js基本概述

Handlebars.js文档中帮助程序函数的快速概述:

  • Handlebars帮助程序调用是简单标识符(帮助程序的​名称),后跟零个或多个空分参数。

  • 参数可以是简单的字符串、数字、布尔或JSON对象,也可以是键值对(散列参数)的可选序列作为最后一个参数。

  • 哈希参数中的键必须是简单标识符。

  • 哈希参数中的值是Handlebars表达式:简单标识符、路径或字符串。

  • 当前上下文this始终适用于Handlebars帮助器。

  • 上下文可以是字符串、数字、布尔值或JSON数据对象。

  • 可以将嵌套在当前上下文中的对象作为上下文进行传递,如this.urlthis.id(请参见以下简单和块帮助器示例)。

  • 块帮助程序是可以从模板中的任何位置调用的功能。 他们每次都可以调用模板块零次或多次,并具有不同的上下文。 它们包含{{#name}}和{{/name}}之间的上下文。

  • Handlebars为名为“options”的助手提供最终参数。 特殊对象“选项”包括

    • 可选专用数据(options.data)
    • 调用的可选键值属性(options.hash)
    • 能够调用自身(options.fn())
    • 能够调用其本身的反向(options.inverse())
  • 建议从帮助程序返回的HTML字符串内容是SafeString。

Handlebars.js文档中的简单帮助程序示例:

Handlebars.registerHelper('link_to', function(title, options) {
    return new Handlebars.SafeString('<a href="/posts'%20+%20this.url%20+%20'?lang=zh-Hans">' + 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">发布!</a></li>
</ul>

Handlebars.js文档中的块帮助程序示例:

Handlebars.registerHelper('link', function(options) {
    return new Handlebars.SafeString('<a href="/people/'%20+%20this.id%20+%20'?lang=zh-Hans">' + 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">Alan</a></li>
<li><a href="/people/2">耶胡达</a></li>
</ul>

自定义SCF Helpers

必须在服务器端和客户端上实现自定义帮助器,特别是在传递数据时。 对于SCF,当服务器在请求页面时为给定组件生成HTML时,大多数模板都在服务器端编译和呈现。

服务器端自定义帮助器

要在服务器端实现和注册自定义SCF帮助程序,只需实现Java接口TemplateHelper,使其成为OSGi服务并作为OSGi捆绑的一部分进行安装。

例如:

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;
    }
}
注意

还必须为客户端创建为服务器端创建的帮助程序。

在登录用户的客户端上重新呈现该组件,如果找不到客户端帮助程序,该组件将消失。

客户端自定义帮助器

客户端帮助程序是通过调用Handlebars.registerHelper()注册的Handlebars脚本。
例如:

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中定义。

‹功能基本工具 服务器端自定义
客户端自定义

在此页面上

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now