Extensão de um componente do AEM Screens

O tutorial a seguir apresenta as etapas e práticas recomendadas para a extensão dos componentes prontos para uso do AEM Screens. O componente Imagem é estendido para adicionar uma sobreposição de texto autorável.

Visão geral

Este tutorial é destinado a desenvolvedores novos no AEM Screens. Neste tutorial, o componente Imagem do Screens é estendido para criar um componente de Pôster. Um título, descrição e logotipo são sobrepostos sobre uma imagem para criar uma experiência atraente em um Canal de sequência.

OBSERVAÇÃO

Antes de iniciar este tutorial, é recomendável concluir o tutorial: Desenvolvimento de um componente personalizado para AEM Screens.

Componente Pôster Personalizado

O componente Pôster personalizado é criado estendendo o componente Imagem .

Pré-requisitos

Para concluir este tutorial, é necessário o seguinte:

  1. AEM 6.4 ou AEM 6.3 + Pacote de recursos do Screens mais recente
  2. Player do AEM Screens
  3. Ambiente de desenvolvimento local

As etapas tutoriais e capturas de tela são executadas usando o CRXDE-Lite. O Eclipseor IntelliJIDEs também pode ser usado para concluir o tutorial. Mais informações sobre como usar um IDE para desenvolver com AEM podem ser encontradas aqui.

Configuração do projeto

O código-fonte de um projeto do Screens geralmente é gerenciado como um projeto Maven de vários módulos. Para acelerar o tutorial, um projeto foi pré-gerado usando o AEM Arquétipo de projeto 13. Mais detalhes sobre a criação de um projeto com o Maven AEM Project Archetype podem ser encontrados aqui.

  1. Baixe e instale os seguintes pacotes usando o pacote CRX manage http://localhost:4502/crx/packmgr/index.jsp)r:

    Obter arquivo

    Obter arquivo
    Como opção, se estiver trabalhando com o Eclipse ou outro IDE, baixe o pacote de origem abaixo. Implante o projeto em uma instância de AEM local usando o comando Maven:

    mvn -PautoInstallPackage clean install

    Projeto de execução We.Retail do SRC Start Screens

    Obter arquivo

  2. Em Gerenciador de Pacotes CRX http://localhost:4502/crx/packmgr/index.jsp os dois pacotes a seguir estão instalados:

    1. screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip
    2. screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip

    O Screens Executará os pacotes Ui.Apps e Ui.Content instalados pelo Gerenciador de Pacotes do CRX

    O Screens Executará os pacotes Ui.Apps e Ui.Content instalados pelo Gerenciador de Pacotes do CRX

Crie o componente cartaz

O componente Pôster estende o componente Imagem das telas prontas para uso. Um mecanismo do Sling, sling:resourceSuperType, é usado para herdar a funcionalidade principal do componente de Imagem sem precisar copiar e colar. Mais informações sobre as noções básicas de Processamento de Solicitação do Sling podem ser encontradas aqui.

O componente Poster é renderizado em tela cheia no modo de visualização/produção. No modo de edição, é importante renderizar o componente de forma diferente para facilitar a criação do canal de sequência.

  1. Em CRXDE-Lite http://localhost:4502/crx/de/index.jsp (ou IDE de escolha) abaixo de /apps/weretail-run/components/contentcrie um novo cq:Component chamado poster.

    Adicione as seguintes propriedades ao componente poster:

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
        jcr:primaryType="cq:Component"
        jcr:title="Poster"
        sling:resourceSuperType="screens/core/components/content/image"
        componentGroup="We.Retail Run - Content"/>
    

    Propriedades para /apps/weretail-run/components/content/poster

    Propriedades para /apps/weretail-run/components/content/poster

    Ao definir a propriedade sling:resourceSuperTypeigual a screens/core/components/content/image, o componente Pôster herda efetivamente toda a funcionalidade do componente Imagem. Nós e arquivos equivalentes encontrados abaixo de screens/core/components/content/image podem ser adicionados abaixo do componente poster para substituir e estender a funcionalidade.

  2. Copie o nó cq:editConfig abaixo de /libs/screens/core/components/content/image.Cole o cq:editConfig abaixo do componente /apps/weretail-run/components/content/poster.

    No nó cq:editConfig/cq:dropTargets/image/parameters, atualize a propriedade sling:resourceType para igual a weretail-run/components/content/poster.

    edit-config

    Representação XML da cq:editConfig representada abaixo:

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
        jcr:primaryType="cq:EditConfig">
        <cq:dropTargets jcr:primaryType="nt:unstructured">
            <image
                jcr:primaryType="cq:DropTargetConfig"
                accept="[image/.*]"
                groups="[media]"
                propertyName="./fileReference">
                <parameters
                    jcr:primaryType="nt:unstructured"
                    sling:resourceType="weretail-run/components/content/poster"
                    imageCrop=""
                    imageMap=""
                    imageRotate=""/>
            </image>
        </cq:dropTargets>
    </jcr:root>
    
  3. Copie a caixa de diálogo image do WCM Foundation a ser usada para o componente poster.

    É mais fácil começar com uma caixa de diálogo existente e depois fazer modificações.

    1. Copie a caixa de diálogo de: /libs/wcm/foundation/components/image/cq:dialog
    2. Cole a caixa de diálogo abaixo de /apps/weretail-run/components/content/poster

    Caixa de diálogo copiada de /libs/wcm/foundation/components/image/cq:dialog para /apps/weretail-run/components/content/poster

    Caixa de diálogo copiada de /libs/wcm/foundation/components/image/cq:dialog para /apps/weretail-run/components/content/poster

    O componente image do Screens é sobreposto ao componente Base do WCM image. Portanto, o componente poster herda a funcionalidade de ambos. A caixa de diálogo do componente de pôster é composta por uma combinação das caixas de diálogo Screens e Foundation. Os recursos do Sling Resource Merger são usados para ocultar campos de diálogo irrelevantes e guias herdadas dos componentes superdigitados.

  4. Atualize a caixa de diálogo cq:debaixo de /apps/weretail-run/components/content/poster com as seguintes alterações representadas em XML:

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
        jcr:primaryType="nt:unstructured"
        jcr:title="Poster"
        sling:resourceType="cq/gui/components/authoring/dialog">
        <content
            jcr:primaryType="nt:unstructured"
            sling:resourceType="granite/ui/components/foundation/container">
            <layout
                jcr:primaryType="nt:unstructured"
                sling:resourceType="granite/ui/components/foundation/layouts/tabs"
                type="nav"/>
            <items jcr:primaryType="nt:unstructured">
                <image
                    jcr:primaryType="nt:unstructured"
                    jcr:title="Elements"
                    sling:resourceType="granite/ui/components/foundation/section">
                    <layout
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="granite/ui/components/foundation/layouts/fixedcolumns"
                        margin="{Boolean}false"/>
                    <items jcr:primaryType="nt:unstructured">
                        <column
                            jcr:primaryType="nt:unstructured"
                            sling:resourceType="granite/ui/components/foundation/container">
                            <items
                                jcr:primaryType="nt:unstructured"
                                sling:hideChildren="[linkURL,size]">
                                <file
                                    jcr:primaryType="nt:unstructured"
                                    sling:resourceType="cq/gui/components/authoring/dialog/fileupload"
                                    autoStart="{Boolean}false"
                                    class="cq-droptarget"
                                    fieldLabel="Image asset"
                                    fileNameParameter="./fileName"
                                    fileReferenceParameter="./fileReference"
                                    mimeTypes="[image]"
                                    multiple="{Boolean}false"
                                    name="./file"
                                    title="Upload Image Asset"
                                    uploadUrl="${suffix.path}"
                                    useHTML5="{Boolean}true"/>
                                <title
                                    jcr:primaryType="nt:unstructured"
                                    sling:resourceType="granite/ui/components/foundation/form/textfield"
                                    fieldLabel="Title"
                                    name="./jcr:title"/>
                                <description
                                    jcr:primaryType="nt:unstructured"
                                    sling:resourceType="granite/ui/components/foundation/form/textarea"
                                    fieldLabel="Description"
                                    name="./jcr:description"/>
                                <position
                                    jcr:primaryType="nt:unstructured"
                                    sling:resourceType="granite/ui/components/coral/foundation/form/select"
                                    fieldLabel="Text Position"
                                    name="./textPosition">
                                    <items jcr:primaryType="nt:unstructured">
                                        <left
                                            jcr:primaryType="nt:unstructured"
                                            text="Left"
                                            value="left"/>
                                        <center
                                            jcr:primaryType="nt:unstructured"
                                            text="Center"
                                            value="center"/>
                                        <right
                                            jcr:primaryType="nt:unstructured"
                                            text="Right"
                                            value="right"/>
                                    </items>
                                </position>
                                <color
                                    jcr:primaryType="nt:unstructured"
                                    sling:resourceType="granite/ui/components/coral/foundation/form/select"
                                    fieldLabel="Text Color"
                                    name="./textColor">
                                    <items jcr:primaryType="nt:unstructured">
                                        <light
                                            jcr:primaryType="nt:unstructured"
                                            text="Light"
                                            value="light"/>
                                        <dark
                                            jcr:primaryType="nt:unstructured"
                                            text="Dark"
                                            value="dark"/>
                                    </items>
                                </color>
                            </items>
                        </column>
                    </items>
                </image>
                <accessibility
                    jcr:primaryType="nt:unstructured"
                    sling:hideResource="{Boolean}true"/>
            </items>
        </content>
    </jcr:root>
    

    A propriedade sling:hideChildren= "[linkURL,size]" é usada no nó items para garantir que os campos linkURL e size fiquem ocultos na caixa de diálogo. Remover esses nós da caixa de diálogo do pôster não é suficiente. A propriedade sling:hideResource="{Boolean}true" na guia acessibilidade é usada para ocultar a guia inteira.

    Dois campos selecionados são adicionados à caixa de diálogo para fornecer aos autores controle sobre a posição do texto e a cor do Título e da Descrição.

    Cartaz - Estrutura de Diálogo Final

    Cartaz - Estrutura de Diálogo Final

    Neste ponto, uma instância do componente poster pode ser adicionada à página Canal ocioso no projeto Execução We.Retail: http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html.

    Campos da caixa de diálogo de pôster

    Campos da caixa de diálogo de pôster

  5. Crie um arquivo sob /apps/weretail-run/components/content/poster chamado production.html.

    Preencha o arquivo com o seguinte:

    <!--/*
    
        /apps/weretail-run/components/content/poster/production.html
    
    */-->
    <div data-sly-use.image="image.js"
         data-duration="${properties.duration}"
         class="cmp-poster"
         style="background-image: url(${request.contextPath @ context='uri'}${image.src @ context='uri'});">
        <div class="cmp-poster__text
                    cmp-poster__text--${properties.textPosition @ context='attribute'}
                    cmp-poster__text--${properties.textColor @ context='attribute'}">
            <h1 class="cmp-poster__title">${properties.jcr:title}</h1>
             <h2 class="cmp-poster__description">${properties.jcr:description}</h2>
        </div>
     <img class="cmp-poster__logo" src="/content/dam/we-retail-run/logos/we-retail-run_dark.png?lang=pt-BR" alt="we-retail-logo" />
    </div>
    

    Acima está a marcação de produção do Componente de cartaz. O script HTL substitui screens/core/components/content/image/production.html. O image.js é um script do lado do servidor que cria um objeto de imagem semelhante a POJO. O objeto Image pode ser chamado para renderizar o src como uma imagem de fundo de estilo embutido.

    The h1 As tags h2 e exibem o Título e a Descrição com base nas propriedades do componente: ${properties.jcr:title} e ${properties.jcr:description}.

    Ao redor das tags h1 e h2 há um invólucro div com três classes CSS com variações de " cmp-poster__text". O valor das propriedades textPosition e textColor é usado para alterar a classe CSS renderizada com base na seleção da caixa de diálogo do autor. Na próxima seção, o CSS das bibliotecas de clientes é gravado para ativar essas alterações na exibição.

    Um logotipo também é incluído como uma sobreposição no componente. Neste exemplo, o caminho para o logotipo We.Retail é codificado no DAM. Dependendo do caso de uso, pode fazer mais sentido criar um novo campo de diálogo para tornar o caminho do logotipo um valor preenchido dinamicamente.

    Observe também que a notação BEM (Bloquear modificador de elemento) é usada com o componente. O BEM é uma convenção de codificação de CSS que facilita a criação de componentes reutilizáveis. BEM é a notação usada por AEM Componentes principais. Mais informações podem ser encontradas em: https://getbem.com/

  6. Crie um arquivo sob /apps/weretail-run/components/content/poster chamado edit.html.

    Preencha o arquivo com o seguinte:

    <!--/*
    
        /apps/weretail-run/components/content/poster/edit.html
    
    */-->
    
    <div class="aem-Screens-editWrapper ${image.cssClass} cmp-poster" data-sly-use.image="image.js" data-emptytext="${'Poster' @ i18n, locale=request.locale}">
        <img class="cmp-poster__image" src="${request.contextPath}${image.src @ context='uri'}" width="100%" />
        <div class="cmp-poster__text
               cmp-poster__text--${properties.textPosition @ context='attribute'}
           cmp-poster__text--${properties.textColor @ context='attribute'}">
          <p class="cmp-poster__title">${properties.jcr:title}</p>
          <p class="cmp-poster__description">${properties.jcr:description}</p>
        </div>
    </div>
    

    Acima está a marcação edit para o Componente de Pôster. O script HTL substitui /libs/screens/core/components/content/image/edit.html. A marcação é semelhante à marcação production.html e exibirá o título e a descrição na parte superior da imagem.

    O aem-Screens-editWrapperé adicionado para que o componente não renderize a tela cheia no editor. O atributo data-emptytext garante que o espaço reservado seja exibido quando nenhuma imagem ou conteúdo for preenchido.

Criar bibliotecas do lado do cliente

As bibliotecas do lado do cliente fornecem um mecanismo para organizar e gerenciar arquivos CSS e JavaScript necessários para uma implementação de AEM. Mais informações sobre o uso de Bibliotecas do lado do cliente podem ser encontradas aqui.

Os componentes do AEM Screens são renderizados de forma diferente no modo de Edição e no modo de Visualização/Produção. Dois conjuntos de bibliotecas de clientes são criados, um para o modo de Edição e um segundo para Visualização/Produção.

  1. Crie uma pasta para bibliotecas do lado do cliente para o componente Pôster.

    Abaixo de /apps/weretail-run/components/content/poster,crie uma nova pasta chamada clientlibs.

    2018-05-03_at_1008pm

  2. Abaixo da pasta clientlibs crie um novo nó chamado shared do tipo cq:ClientLibraryFolder.

    2018-05-03_at_1011pm

  3. Adicione as seguintes propriedades à biblioteca do cliente compartilhada:

    • allowProxy | Booleano | true
    • categories | String[] | cq.screens.components

    Propriedades para /apps/weretail-run/components/content/poster/clientlibs/shared

    Propriedades para /apps/weretail-run/components/content/poster/clientlibs/shared

    A propriedade categories é uma string que identifica a biblioteca do cliente. A categoria cq.screens.components é usada no modo Editar e Visualizar/Produção. Portanto, qualquer CSS/JS definido na clientlib shared é carregado em todos os modos.

    É uma prática recomendada nunca expor nenhum caminho diretamente para /apps em um ambiente de produção. A propriedade allowProxy garante que o CSS e o JS da biblioteca do cliente sejam referenciados por meio de um prefixo /etc.clientlibs. Mais informações sobre a propriedade allowProxy podem ser encontradas aqui.

  4. Crie o arquivo com o nome css.txt abaixo da pasta compartilhada.

    Preencha o arquivo com o seguinte:

    #base=css
    
    styles.less
    
  5. Crie uma pasta chamada css abaixo da pasta shared. Adicione um arquivo com o nome style.less abaixo da pasta css. A estrutura das bibliotecas de clientes agora deve ser semelhante a esta:

    2018-05-03_at_1057pm

    Em vez de escrever CSS diretamente, este tutorial usa MENOS. O LESS é um popular pré-compilador de CSS compatível com variáveis, mixins e funções de CSS. AEM bibliotecas de clientes oferecem suporte nativo a menos compilação. É possível utilizar software ou outros pré-compiladores, mas é necessário compilá-los fora do AEM.

  6. Preencha /apps/weretail-run/components/content/poster/clientlibs/shared/css/styles.less com o seguinte:

    /*
     /apps/weretail-run/components/content/poster/clientlibs/shared/css/styles.less
     Poster Component - Shared Style
    */
    
    @import url('https://fonts.googleapis.com/css?family=Fjalla+One|Open+Sans:400i');
    
    @text-light-color: #fff;
    @text-dark-color: #000;
    @title-font-family: 'Fjalla One', sans-serif;
    @description-font-family: 'Open Sans', sans-serif;
    
    .cmp-poster {
    
          &__text {
          position: absolute;
          color: @text-light-color;
          top: 0;
          text-align:center;
          width: 100%;
    
          &--left {
           text-align: left;
                 margin-left: 1em;
          }
    
          &--right {
           text-align: right;
                 margin-right: 1em;
          }
    
          &--dark {
           color: @text-dark-color;
          }
        }
    
        &__title {
          font-weight: bold;
             font-family: @title-font-family;
             font-size: 1.2em;
        }
    
        &__description {
      font-style: italic;
            font-family: @description-font-family;
     }
    
    }
    
    OBSERVAÇÃO

    As fontes da Web do Google são usadas para as famílias de fontes. As fontes da Web exigem conectividade com a Internet e nem todas as implementações de telas terão uma conexão confiável. O planejamento para o modo offline é uma consideração importante para as implantações do Screens.

  7. Copie a pasta shared da biblioteca do cliente. Cole-o como um irmão e renomeie-o para production.

    2018-05-03_at_1114

  8. Atualize a propriedade categories da biblioteca de clientes de produção para ser cq.screens.components.production.

    A categoria cq.screens.components.production garante que os estilos só sejam carregados no modo Visualização/Produção.

    Propriedades para /apps/weretail-run/components/content/poster/clientlibs/production

    Propriedades para /apps/weretail-run/components/content/poster/clientlibs/production

  9. Preencha /apps/weretail-run/components/content/poster/clientlibs/production/css/styles.less com o seguinte:

    /*
     /apps/weretail-run/components/content/poster/clientlibs/production/css/styles.less
     Poster Component - Production Style
    */
    
    .cmp-poster {
    
        background-size: cover;
     height: 100%;
     width: 100%;
     position:absolute;
    
         &__text {
    
            top: 2em;
    
            &--left {
                width: 40%;
                top: 5em;
            }
    
            &--right {
                width: 40%;
                right: 1em;
            }
        }
    
        &__title {
      font-size: 5rem;
      font-weight: 900;
      margin: 0.1rem;
     }
    
     &__description {
      font-size: 2rem;
      margin: 0.1rem;
      font-weight: 400;
    
     }
    
        &__logo {
      position: absolute;
      max-width: 200px;
      top: 1em;
      left: 0;
     }
    
    }
    

    Os estilos acima exibem o Título e a Descrição em uma posição absoluta na tela. O título será exibido significativamente maior que a descrição. A notação BEM do componente facilita o escopo cuidadoso dos estilos dentro da classe cmp-poster.

Uma terceira categoria de biblioteca de clientes: cq.screens.components.edit pode ser usado para adicionar Editar somente estilos específicos ao componente.

Categoria Clientlib Uso
cq.screens.components Estilos e scripts compartilhados entre os modos de edição e produção
cq.screens.components.edit Estilos e scripts que são usados apenas no modo de edição
cq.screens.components.production Estilos e scripts que são usados apenas no modo de produção

Adicionar componente de cartaz a um canal de sequência

O componente Pôster deve ser usado em um Canal de sequência. O pacote inicial deste tutorial incluía um Canal ocioso. O Canal ocioso é pré-configurado para permitir componentes do grupo Execução We.Retail - Content. O grupo do componente Pôster é definido como We.Retail Run - Content e está disponível para ser adicionado ao canal.

  1. Abra o Canal ocioso do projeto We.Retail Run : http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html

  2. Arraste e solte uma nova instância do componente Pôster da barra lateral na página.

    2018-05-07_at_3_23

  3. Edite a caixa de diálogo do componente Pôster para adicionar uma Imagem, Título, Descrição. Use as opções Posição do texto e Cor do texto para garantir que o Título/Descrição possa ser lido sobre a Imagem.

    2018-05-07_at_3_25

  4. Repita as etapas acima para adicionar alguns componentes Pôster. Adicione transições entre os componentes.

    2018-05-07_at_3_28

Colocando tudo junto

O vídeo abaixo mostra o componente finalizado e como ele pode ser adicionado a um canal de Sequência. O Canal é adicionado a uma exibição Local e, em última análise, atribuído a um player do Screens.

Código finalizado

Abaixo está o código concluído do tutorial. Os screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip e screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip são os pacotes AEM compilados. O SRC-screens-weretail-run-0.0.1.zip é o código-fonte não compilado que pode ser implantado usando o Maven.

Obter arquivo

Obter arquivo

Projeto de execução We.Retail do SRC Final Screens

Obter arquivo

Nesta página

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