Extensão de um componente do AEM Screens

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

Visão geral

Este tutorial destina-se a desenvolvedores novos no AEM Screens. Neste tutorial, o componente de 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 o AEM Screens.

Componente de cartaz personalizado

O componente de Poster personalizado é criado estendendo o componente de Imagem.

Pré-requisitos

Para concluir este tutorial, você precisa do seguinte:

AEM 6.5 + Pacote de recursos do Screens mais recente
Player do AEM Screens
Ambiente de desenvolvimento local

As etapas e capturas de tela do tutorial são executadas usando o CRXDE-Lite. Eclipse ou IntelliJ IDEs também podem ser usados para concluir o tutorial. Mais informações sobre o uso de um IDE para desenvolvimento com AEM pode ser encontrado 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 Arquétipo de projeto 13 do AEM. Mais detalhes sobre a criação de um projeto com o Arquétipo de projeto Maven AEM pode ser encontrada aqui.

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

Obter arquivo

Obter arquivo
Opcionalmente, se estiver trabalhando com o Eclipse ou outro IDE, baixe o pacote de código-fonte abaixo. Implante o projeto em uma instância AEM local usando o comando Maven:

mvn -PautoInstallPackage clean install

SRC Start Screens We.Retail Executar projeto

Obter arquivo

Entrada 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
Screens We.Retail Executar pacotes Ui.Apps e Ui.Content instalados via Gerenciador de pacotes do CRX

Criar o componente de cartaz

O componente de Pôster estende o componente de Imagem das telas prontas para uso. Um mecanismo de 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 do O processamento de solicitações do Sling pode ser encontrado aqui.

O componente de Pôster é 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.

Entrada CRXDE-Lite http://localhost:4502/crx/de/index.jsp (ou IDE de escolha) abaixo de para /apps/weretail-run/components/contentcriar um cq:Component nomeado poster.

Adicione as seguintes propriedades à poster componente:
```
<?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 de /apps/weretail-run/components/content/poster

Ao definir a variável sling:resourceSuperTypepropriedade igual a screens/core/components/content/image o componente de Pôster herda efetivamente toda a funcionalidade do componente de Imagem. Nós e arquivos equivalentes encontrados abaixo de screens/core/components/content/image pode ser adicionado abaixo de poster para substituir e estender a funcionalidade.

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

No cq:editConfig/cq:dropTargets/image/parameters atualização de nó do sling:resourceType propriedade igual a weretail-run/components/content/poster.

edit-config

Representação XML do cq:editConfig representado 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>

Copiar WCM Foundation image a ser usada para a poster componente.

É mais fácil começar com uma caixa de diálogo existente e, em seguida, fazer modificações.
1. Copiar a caixa de diálogo de: /libs/wcm/foundation/components/image/cq:dialog
2. Colar a caixa de diálogo abaixo /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 Screens image é sobrestipado para o WCM Foundation image componente. Por conseguinte, a poster O componente 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 do Screens e do Foundation. Recursos do Fusão de recursos do Sling são usados para ocultar campos de caixas de diálogo e guias irrelevantes herdados dos componentes sobrestipados.

Atualize o cq:dialog abaixo 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]" é usado no items nó para garantir que o linkURL e tamanho os campos estão ocultos na caixa de diálogo. Não basta remover estes nós da caixa de diálogo do pôster. 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 conceder aos autores controle sobre a posição e a cor do texto do Título e da Descrição.

Pôster - Estrutura final da caixa de diálogo

Neste ponto, uma instância da poster componente pode ser adicionado à variável Canal ocioso no projeto We.Retail Run: http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html.

Campos da caixa de diálogo do cartaz

Criar um arquivo abaixo de /apps/weretail-run/components/content/poster nomeado production.html.

Preencha o arquivo com o seguinte:
```

<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" alt="we-retail-logo" />
</div>
```
Acima está a marcação de produção para o componente de Pôster. O script HTL substitui screens/core/components/content/image/production.html. A variável image.js é um script do lado do servidor que cria um objeto de imagem do tipo POJO. O objeto Image pode ser chamado para renderizar o src como uma imagem de fundo de estilo inline.

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

Ao redor do h1 e h2 tags é um wrapper div com três classes CSS com variações de " cmp-poster__text". O valor para a variável textPosition e textColor As propriedades são usadas 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 é escrito 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 está codificado no DAM. Dependendo do caso de uso, pode fazer mais sentido criar um campo de diálogo para tornar o caminho do logotipo um valor preenchido dinamicamente.

Observe também que a notação BEM (Block Element Modifier) é usada com o componente. BEM é uma convenção de codificação CSS que facilita a criação de componentes reutilizáveis. BEM é a notação usada por Componentes principais do AEM.

Criar um arquivo abaixo de /apps/weretail-run/components/content/poster nomeado 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á o editar marcação para o componente de Pôster. O script HTL substitui /libs/screens/core/components/content/image/edit.html. A marcação é semelhante ao production.html e exibe o título e a descrição na parte superior da imagem.

A variável aem-Screens-editWrapperé adicionado para que o componente não seja renderizado em tela cheia no editor. A variável data-emptytext O atributo garante que um 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 do AEM. Mais informações sobre como usar o As bibliotecas do lado do cliente podem ser encontradas aqui.

Os componentes do AEM Screens são renderizados de forma diferente no modo Editar versus no modo Pré-visualização/Produção. Dois conjuntos de bibliotecas de clientes são criados, um para o modo Editar e um segundo para Pré-visualização/Produção.

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

Abaixo /apps/weretail-run/components/content/poster,criar uma pasta chamada clientlibs.
Abaixo de clientlibs pasta criar um nó chamado shared do tipo cq:ClientLibraryFolder.
Adicione as seguintes propriedades à biblioteca de cliente compartilhada:
- allowProxy | Booleano | true
- categories | String[] | cq.screens.components
Propriedades de /apps/weretail-run/components/content/poster/clientlibs/shared

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

É uma prática recomendada nunca expor nenhum caminho diretamente para /apps em um ambiente de produção. A variável 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 o A propriedade allowProxy pode ser encontrada aqui.
Criar arquivo chamado css.txt abaixo da pasta compartilhada.

Preencha o arquivo com o seguinte:
```
#base=css

styles.less
```
Crie uma pasta chamada css abaixo de shared pasta. Adicionar um arquivo chamado style.less abaixo de css pasta. A estrutura das bibliotecas de clientes agora deve ficar assim:

Em vez de escrever CSS diretamente, este tutorial usa MENOS. MENOS O é um pré-compilador de CSS popular que oferece suporte a variáveis, mixins e funções de CSS. Bibliotecas de clientes AEM nativamente oferecem suporte à compilação LESS. Sass ou outros pré-compiladores podem ser usados, mas devem ser compilados fora do AEM.

Preencher /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 Web Fonts do Google são usadas para as famílias de fontes. O Web Fonts exige conectividade com a Internet e nem todas as implementações de tela fornecem uma conexão confiável. O planejamento para o modo offline é uma consideração importante para implantações do Screens.

Copie o shared pasta da biblioteca do cliente. Colar como irmão e renomeá-lo como production.
Atualize o categories propriedade da biblioteca de cliente de produção a ser cq.screens.components.production.

A variável cq.screens.components.production A categoria garante que os estilos só sejam carregados quando estiverem no modo de Pré-visualização/Produção.

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

Preencher /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 é exibido 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 clientlibrary: cq.screens.components.edit pode ser usado para adicionar Editar somente estilos específicos ao componente.

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

Adicionar componente de cartaz a um canal de sequência

O componente de Pôster é 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 do We.Retail - Conteúdo. O grupo do componente Cartaz está definido como We.Retail Run - Content e está disponível para ser adicionado ao canal.

Abra o canal ocioso no projeto We.Retail Run: http://localhost:4502/editor.html/content/screens/we-retail-run/channels/idle-channel.edit.html
Arraste e solte uma nova instância do Pôster componente da barra lateral na página.
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 seja legível sobre a Imagem.
Repita as etapas acima para adicionar alguns componentes de Pôster. Adicione transições entre os componentes.

Tudo junto na prática

O vídeo abaixo mostra o componente concluído e como ele pode ser adicionado a um canal de sequência. O Canal é então adicionado a uma exibição de Localização e, por fim, atribuído a um reprodutor do Screens.

Código concluído

Abaixo está o código concluído do tutorial. A variável 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 de AEM compilados. O SRC-screens-weretail-run-0.0.1.zip  é o código-fonte não compilado que pode ser implantado usando Maven.

Obter arquivo

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

Obter arquivo