Bibliotecas de tags

As bibliotecas de tags Granite, CQ e Sling fornecem acesso a funções específicas para uso no script JSP de seus modelos e componentes.

Biblioteca de tags do Granite

A biblioteca de tags do Granite contém funções úteis.

Ao desenvolver o script jsp de um componente da interface do usuário do Granite, é recomendável incluir o seguinte código na parte superior do script:

<%@include file="/libs/granite/ui/global.jsp"%>

O global também declara o Sling library.

<%@taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling" %>

<ui:includeclientlib>

A tag <ui:includeClientLib> Inclui uma biblioteca cliente html AEM, que pode ser uma biblioteca js, css ou de temas. Para várias inclusões de tipos diferentes, por exemplo js e css, essa tag precisa ser usada várias vezes no jsp. Esta tag é um invólucro de conveniência em torno da interface de serviço [com.adobe.granite.ui.clientlibs.HtmlLibraryManager](https://helpx.adobe.com/experience-manager/6-4/sites/developing/using/reference-materials/javadoc/com/adobe/granite/ui/clientlibs/HtmlLibraryManager.html).

Ela tem os seguintes atributos:

categorias - uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas Javascript e CSS para as categorias fornecidas. O nome do tema é extraído da solicitação.

Equivalente a: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeIncludes

theme — Uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas relacionadas ao tema (tanto CSS quanto JS) para as categorias fornecidas. O nome do tema é extraído da solicitação.

Equivalente a: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeThemeInclude

js - Uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas JavaScript para as categorias fornecidas.

Equivalente a: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeJsInclude

css - uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas CSS para as categorias fornecidas.

Equivalente a: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeCssInclude

tema - Um sinalizador que indica apenas bibliotecas temáticas ou não deve ser incluído. Se omitido, ambos os conjuntos serão incluídos. Aplica-se somente a JS ou CSS puro (não para categorias ou inclui temas).

A tag <ui:includeClientLib> pode ser usada da seguinte maneira em um jsp:

<%-- all: js + theme (theme-js + css) --%>
<ui:includeClientLib categories="cq.wcm.edit" />

<%-- only js libs --%>
<ui:includeClientLib js="cq.collab.calendar, cq.security" />

<%-- theme only (theme-js + css) --%>
<ui:includeClientLib theme="cq.collab.calendar, cq.security" />

<%-- css only --%>
<ui:includeClientLib css="cq.collab.calendar, cq.security" />

Biblioteca de tags CQ

A biblioteca de tags CQ contém funções úteis.

Para usar a Biblioteca de tags do CQ no script, o script deve começar com o seguinte código:

<%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %>

Ao desenvolver o script jsp de um componente AEM, é recomendável incluir o seguinte código na parte superior do script:

<%@include file="/libs/foundation/global.jsp"%>

Ele declara os taglibs de sling, CQ e jstl e expõe os objetos de script usados regularmente definidos pela tag <cq:defineObjects /> . Isso reduz e simplifica o código jsp do seu componente.

<cq:text>

A tag <cq:text> é uma tag de conveniência que gera o texto do componente em um JSP.

Ela tem os seguintes atributos opcionais:

propriedade - Nome da propriedade a ser usada. O nome é relativo ao recurso atual.

value - Valor a ser usado para saída. Se esse atributo estiver presente, ele substituirá o uso do atributo da propriedade.

oldValue - Valor a ser usado para saída diff. Se esse atributo estiver presente, ele substituirá o uso do atributo da propriedade.

escapeXml - Define se os caracteres <>, &, ' e " na sequência de caracteres resultante devem ser convertidos para seus códigos de entidade de caractere correspondentes. O valor padrão é false. Observe que o escape é aplicado após a formatação opcional.

format - java.text.Format opcional para usar na formatação do texto.

noDiff - Suprime o cálculo de uma saída diff, mesmo se uma informação diff estiver presente.

tagClass - Nome de classe CSS de um elemento que rodeará uma saída não vazia. Se estiver vazio, nenhum elemento será adicionado.

tagName - Nome do elemento que rodeará uma saída não vazia. O padrão é DIV.

espaço reservado - Valor padrão para usar em texto nulo ou vazio no modo de edição, ou seja, o espaço reservado. Observe que a verificação padrão é executada após a formatação opcional e o escape, ou seja, é gravado como está na saída. O padrão é:

<div><span class="cq-text-placeholder">&para;</span></div>

padrão - Valor padrão a ser usado para texto nulo ou vazio. Observe que a verificação padrão é executada após a formatação opcional e o escape, ou seja, é gravado como está na saída.

Alguns exemplos de como a tag <cq:text> pode ser usada em um JSP:

<cq:text property="jcr:title" tagName="h2"/>
<cq:text property="jcr:description" tagName="p"/>

<cq:text value="<%= listItem.getTitle() %>" tagName="h4" placeholder="" />
<cq:text value="<%= listItem.getDescription() %>" tagName="p" placeholder=""/>

<cq:text property="jcr:title" value="<%= title %>" tagName="h3"/><%
    } else if (type.equals("link")) {
        %><cq:text property="jcr:title" value="<%= "\u00bb " + title %>" tagName="p" tagClass="link"/><%
    } else if (type.equals("extralarge")) {
        %><cq:text property="jcr:title" value="<%= title %>" tagName="h1"/><%
    } else {
        %><cq:text property="jcr:title" value="<%= title %>" tagName="h2"/><%

<cq:text property="jcr:description" placeholder="" tagName="small"/>

<cq:text property="tableData"
               escapeXml="false"
               placeholder="<img src=\"/libs/cq/ui/resources/0.gif\" class=\"cq-table-placeholder\" alt=\"\">"
    />

<cq:text property="text"/>

<cq:text property="image/jcr:description" placeholder="" tagName="small"/>
<cq:text property="text" tagClass="text"/>

<cq:setcontentbundle>

A tag <cq:setContentBundle> cria um contexto de localização do i18n e o armazena na variável de configuração javax.servlet.jsp.jstl.fmt.localizationContext.

Ela tem os seguintes atributos:

language - O idioma do local para o qual recuperar o pacote de recursos.

source - a fonte da qual a localidade deve ser obtida. Ele pode ser definido como um dos seguintes valores:

• estático - a localidade é retirada do language atributo, se disponível, caso contrário, da localidade padrão do servidor.

• página - a localidade é retirada do idioma da página ou recurso atual, se disponível, caso contrário, do language atributo, se disponível, caso contrário, da localidade padrão do servidor.

• solicitação - a localidade é retirada do local da solicitação ( request.getLocale()).

• auto - a localidade é retirada do language atributo, se disponível, caso contrário, do idioma da página ou recurso atual, se disponível, caso contrário, da solicitação.

Se o atributo source não estiver definido:

• Se o atributo language for definido, o atributo source assumirá como padrão "static.

• Se o atributo language não estiver definido, o atributo source assumirá auto como padrão.

O "pacote de conteúdo" pode ser simplesmente usado pelas tags JSTL <fmt:message> padrão. A pesquisa de mensagens por chaves é de duas vezes:

1. Primeiro, as propriedades do JCR do recurso subjacente que está renderizado no momento são pesquisadas por traduções. Isso permite definir uma caixa de diálogo de componente simples para editar esses valores.
2. Se o nó não contiver uma propriedade chamada exatamente como a chave, o fallback será carregar um pacote de recursos da solicitação de sling ( SlingHttpServletRequest.getResourceBundle(Locale)). O idioma ou a localidade desse pacote é definida pelo idioma e pelos atributos de origem da tag <cq:setContentBundle>.

A tag <cq:setContentBundle> pode ser usada da seguinte maneira em um jsp.

Para páginas que definem seu idioma:

... %><cq:setContentBundle source="page"/><%  %>
<div class="error"><fmt:message key="Hello"/>
</div> ...

Para páginas personalizadas do usuário:

... %><cq:setContentBundle scope="request"/><% %>
<div class="error"><fmt:message key="Hello"/>
</div> ...

<cq:include>

A tag <cq:include> inclui um recurso na página atual.

Ela tem os seguintes atributos:

liberação

• Um booleano que define se libera a saída antes de incluir o target.

path

• O caminho para o objeto de recurso a ser incluído no processamento de solicitação atual. Se esse caminho for relativo, ele será anexado ao caminho do recurso atual cujo script está incluindo o recurso em questão. O caminho e o resourceType ou o script devem ser especificados.

resourceType

• O tipo de recurso do recurso a ser incluído. Se o tipo de recurso estiver definido, o caminho deverá ser o caminho exato para um objeto de recurso: nesse caso, não há suporte para adicionar parâmetros, seletores e extensões ao caminho.
• Se o recurso a ser incluído for especificado com o atributo de caminho que não pode ser resolvido para um recurso, a tag poderá criar um objeto de recurso sintético fora do caminho e desse tipo de recurso.
• O caminho e o resourceType ou o script devem ser especificados.

script

• O script jsp a ser incluído. O caminho e o resourceType ou o script devem ser especificados.

ignoreComponentHierarchy

• Um booleano que controla se a hierarquia do componente deve ser ignorada para a resolução do script. Se true, somente os caminhos de pesquisa serão respeitados.

Exemplo:

<%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %><%
%><div class="center">
    <cq:include path="trail" resourceType="foundation/components/breadcrumb" />
    <cq:include path="title" resourceType="foundation/components/title" />
    <cq:include script="redirect.jsp"/>
    <cq:include path="par" resourceType="foundation/components/parsys" />
</div>

Você deve usar <%@ include file="myScript.jsp" %> ou <cq:include script="myScript.jsp" %> para incluir um script?

• A diretiva <%@ include file="myScript.jsp" %> informa o compilador JSP para incluir um arquivo completo no arquivo atual. É como se o conteúdo do arquivo incluído tivesse sido colado diretamente no arquivo original.
• Com a tag <cq:include script="myScript.jsp"> , o arquivo é incluído no tempo de execução.

Você deve usar <cq:include> ou <sling:include>?

• Ao desenvolver componentes AEM, o Adobe recomenda usar <cq:include>.
• <cq:include> permite incluir diretamente os arquivos de script pelo nome ao usar o atributo de script. Isso leva em conta a herança do tipo de componente e recurso e geralmente é mais simples do que a adesão estrita à resolução do script do Sling usando seletores e extensões.

<cq:includeclientlib>

A tag <cq:includeClientLib> Inclui uma biblioteca cliente html AEM, que pode ser uma biblioteca js, css ou de tema. Para várias inclusões de tipos diferentes, por exemplo js e css, essa tag precisa ser usada várias vezes no jsp. Esta tag é um invólucro de conveniência em torno da interface de serviço com.day.cq.widget.HtmlLibraryManager.

Ela tem os seguintes atributos:

categorias - uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas Javascript e CSS para as categorias fornecidas. O nome do tema é extraído da solicitação.

Equivalente a: com.day.cq.widget.HtmlLibraryManager#writeIncludes

theme — Uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas relacionadas ao tema (tanto CSS quanto JS) para as categorias fornecidas. O nome do tema é extraído da solicitação.

Equivalente a: com.day.cq.widget.HtmlLibraryManager#writeThemeInclude

js - Uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas JavaScript para as categorias fornecidas.

Equivalente a: com.day.cq.widget.HtmlLibraryManager#writeJsInclude

css - uma lista de categorias de bibliotecas de clientes separadas por vírgulas. Isso incluirá todas as bibliotecas CSS para as categorias fornecidas.

Equivalente a: com.day.cq.widget.HtmlLibraryManager#writeCssInclude

tema - Um sinalizador que indica apenas bibliotecas temáticas ou não deve ser incluído. Se omitido, ambos os conjuntos serão incluídos. Aplica-se somente a JS ou CSS puro (não para categorias ou inclui temas).

A tag <cq:includeClientLib> pode ser usada da seguinte maneira em um jsp:

<%-- all: js + theme (theme-js + css) --%>
<cq:includeClientLib categories="cq.wcm.edit" />

<%-- only js libs --%>
<cq:includeClientLib js="cq.collab.calendar, cq.security" />

<%-- theme only (theme-js + css) --%>
<cq:includeClientLib theme="cq.collab.calendar, cq.security" />

<%-- css only --%>
<cq:includeClientLib css="cq.collab.calendar, cq.security" />

<cq:defineobjects>

A tag <cq:defineObjects> expõe os seguintes objetos de script, usados regularmente, que podem ser referenciados pelo desenvolvedor. Também expõe os objetos definidos pela tag <sling:defineObjects> .

componentContext

• o objeto de contexto do componente atual da solicitação (com.day.cq.wcm.api.components.ComponentContext interface).

componente

• o objeto do componente de AEM atual do recurso atual (com.day.cq.wcm.api.components.Component interface).

currentDesign

• o objeto de design atual da página atual (com.day.cq.wcm.api.designer.Design interface).

currentPage

• o objeto de página WCM AEM atual (com.day.cq.wcm.api.Page interface).

currentStyle

• o objeto de estilo atual da célula atual (com.day.cq.wcm.api.designer.Style interface).

designer

• o objeto do designer usado para acessar informações de design (com.day.cq.wcm.api.designer.Designer interface).

editContext

• o objeto edit context do componente AEM (com.day.cq.wcm.api.components.EditContext interface).

pageManager

• o objeto do gerenciador de página para operações no nível da página (com.day.cq.wcm.api.PageManager interface).

pageProperties

• o objeto de propriedades de página da página atual (org.apache.sling.api.resource.ValueMap).

propriedades

• o objeto properties do recurso atual (org.apache.sling.api.resource.ValueMap).

resourceDesign

• o objeto de design da página de recursos (com.day.cq.wcm.api.designer.Design interface).

resourcePage

• o objeto da página de recursos (com.day.cq.wcm.api.Page interface).
• Ela tem os seguintes atributos:

requestName

• herdado do sling

responseName

• herdado do sling

resourceName

• herdado do sling

nodeName

• herdado do sling

logName

• herdado do sling

resourceResolverName

• herdado do sling

slingName

• herdado do sling

componentContextName

• específico do wcm

editContextName

• específico do wcm

propertiesName

• específico do wcm

pageManagerName

• específico do wcm

currentPageName

• específico do wcm

resourcePageName

• específico do wcm

pagePropertiesName

• específico do wcm

componentName

• específico do wcm

designerName

• específico do wcm

currentDesignName

• específico do wcm

resourceDesignName

• específico do wcm

currentStyleName

• específico do wcm

Exemplo

<%@page session="false" contentType="text/html; charset=utf-8" %><%
%><%@ page import="com.day.cq.wcm.api.WCMMode" %><%
%><%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %><%
%><cq:defineObjects/>

<cq:requesturl>

A tag <cq:requestURL> grava o URL da solicitação atual no JspWriter. As duas tags <cq:addParam> e <cq:removeParam> e podem ser usadas dentro do corpo desta tag para modificar o URL da solicitação atual antes que seja gravada.

Ela permite criar links para a página atual com parâmetros variáveis. Por exemplo, permite transformar a solicitação:

mypage.html?mode=view&query=something em mypage.html?query=something.

O uso de addParam ou removeParam altera apenas a ocorrência do parâmetro especificado, todos os outros parâmetros não são afetados.

<cq:requestURL> não tem nenhum atributo.

Exemplos:

<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</a>

<a title="filter results" href="<cq:requestURL><cq:addParam name="language" value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>

<cq:addparam>

A tag <cq:addParam> adiciona um parâmetro de solicitação com o nome e o valor fornecidos à tag <cq:requestURL> de inclusão.

Ela tem os seguintes atributos:

name

• nome do parâmetro a ser adicionado

valor

• valor do parâmetro a ser adicionado

Exemplo:

<a title="filter results" href="<cq:requestURL><cq:addParam name="language" value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>

<cq:removeparam>

A tag <cq:removeParam> remove um parâmetro de solicitação com o nome e o valor fornecidos da tag <cq:requestURL> anexada. Se nenhum valor for fornecido, todos os parâmetros com o nome especificado serão removidos.

Ela tem os seguintes atributos:

name

• nome do parâmetro a ser removido

Exemplo:

<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</a>

Biblioteca de tags Sling

A biblioteca de tags do Sling contém funções úteis do Sling.

Ao usar a Biblioteca de tags do Sling em seu script, o script deve começar com o seguinte código:

<%@ taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling/1.0" %>

<sling:include>

A tag <sling:include> inclui um recurso na página atual.

Ela tem os seguintes atributos:

liberação

• Um booleano que define se libera a saída antes de incluir o target.

recurso

• O objeto de recurso a ser incluído no processamento de solicitação atual. É necessário especificar o recurso ou o caminho. Se ambos forem especificados, o recurso terá prioridade.

caminho

• O caminho para o objeto de recurso a ser incluído no processamento de solicitação atual. Se esse caminho for relativo, ele será anexado ao caminho do recurso atual cujo script está incluindo o recurso em questão. É necessário especificar o recurso ou o caminho. Se ambos forem especificados, o recurso terá prioridade.

resourceType

• O tipo de recurso do recurso a ser incluído. Se o tipo de recurso estiver definido, o caminho deverá ser o caminho exato para um objeto de recurso: nesse caso, não há suporte para adicionar parâmetros, seletores e extensões ao caminho.
• Se o recurso a ser incluído for especificado com o atributo de caminho que não pode ser resolvido para um recurso, a tag poderá criar um objeto de recurso sintético fora do caminho e desse tipo de recurso.

replaceSelectors

• Ao despachar, os seletores são substituídos pelo valor desse atributo.

addSelectors

• Ao despachar, o valor desse atributo é adicionado aos seletores.

replaceSuffix

• Ao despachar, o sufixo é substituído pelo valor desse atributo.

Exemplos:

<div class="item"><sling:include path="<%= pathtoinclude %>"/></div>

<sling:include resource="<%= par %>"/>

<sling:include addSelectors="spool"/>

<sling:include resource="<%= par %>" resourceType="<%= newType %>"/>

<sling:include resource="<%= par %>" resourceType="<%= newType %>"/>

<sling:include replaceSelectors="content" />

<sling:defineobjects>

A tag <sling:defineObjects> expõe os seguintes objetos de script, usados regularmente, que podem ser referenciados pelo desenvolvedor:

slingRequest

• O objeto SlingHttpServletRequest , que fornece acesso às informações do cabeçalho da solicitação HTTP - estende o HttpServletRequest padrão - e fornece acesso a itens específicos do Sling, como recursos, informações de caminho, seletor, etc.

slingResponse

• Objeto SlingHttpServletResponse, que fornece acesso à resposta HTTP criada pelo servidor. Atualmente, é o mesmo que HttpServletResponse, a partir do qual se estende.solicitação
• O objeto de solicitação JSP padrão que é um HttpServletRequest puro.response
• O objeto de resposta JSP padrão que é um HttpServletResponse puro.

resourceResolver

• O objeto ResourceResolver atual. É igual a slingRequest.getResourceResolver()

.sling

• Um objeto SlingScriptHelper, contendo métodos de conveniência para scripts, principalmente sling.include('/some/other/resource') para incluir as respostas de outros recursos dentro dessa resposta (por exemplo, incorporar os snippets html do cabeçalho (embutido) e sling.getService (foo.bar.Service.class) para recuperar os serviços OSGi disponíveis no Sling (notação de classe dependendo da linguagem de script).

recurso

• o objeto de Recurso atual a ser tratado, dependendo do URL da solicitação. É igual a slingRequest.getResource().

currentNode

• Se o recurso atual apontar para um nó JCR (o que normalmente é o caso no Sling), isso dará acesso direto ao objeto Node . Caso contrário, esse objeto não será definido.

log

• Fornece um Logger SLF4J para fazer logon no sistema de log do Sling a partir de scripts, por exemplo. log.info("Executando meu script").

• Ela tem os seguintes atributos:

requestName

responseName

nodeName

l ogName resourceResolverName

slingName

Exemplo:

<%@page session="false" %><%
%><%@page import="com.day.cq.wcm.foundation.forms.ValidationHelper"%><%
%><%@taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling/1.0" %><%
%><sling:defineObjects/>

Biblioteca de tags JSTL

A Biblioteca de tags padrão de páginas do JavaServer contém muitas tags úteis e padrão. Os taglibs de núcleo, formatação e função são definidos pelo /libs/foundation/global.jsp, conforme mostrado no trecho a seguir.

Extrato de /libs/foundation/global.jsp

<%@taglib prefix="c" uri="https://java.sun.com/jsp/jstl/core" %>
<%@taglib prefix="fmt" uri="https://java.sun.com/jsp/jstl/fmt" %>
<%@taglib prefix="fn" uri="https://java.sun.com/jsp/jstl/functions" %>

Depois de importar o arquivo /libs/foundation/global.jsp conforme descrito anteriormente, você pode usar os prefixos c, fmt e fn para acessar esses taglibs. A documentação oficial do JSTL está disponível em The Java EE 5 Tutorial - JavaServer Pages Standard Tag Library.