Índice

Sobre Layouts

O layout define a composição de uma página e é composto por múltiplos slots. A quantidade, posição e dimensão desses slots é o que define o corpo de um layout. Dessa forma, o layout é a estrutura de uma página, definindo a distribuição dos Widgets que a compõe por meio dos slots.

Slot

Slots são contêineres definidos que são aptos a comportarem Widgets. A quantidade, posição e dimensão desses slots é o que define o corpo de um template. Sendo assim, o template é o esqueleto de uma página, definindo a distribuição das Widgets que a compõem através do slots.

Estrutura de Arquivos

Layouts possuem a estrutura de arquivos semelhante à de uma Widget um widget comum, e também são empacotados em formato “war”. A estrutura de pastas-fonte de um layout é a que segue:

<codigo-do-layout>
 +-- pom.xml (packaging: war)
 +-- src
   +-- main
     +-- java (não utilizado, padrão das Widgets)
     +-- resources
       +-- application.info
       +-- layout.ftl
       +-- <codigo-do-layout>.properties
       +-- <codigo-do-layout>_en_US.properties
       +-- <codigo-do-layout>_es.properties
       +-- <codigo-do-layout>_pt_BR.properties
     +-- webapp
       +-- META-INF
       +-- resources
         +-- images
           +-- icon.png
         +-- css
         +-- js
       +-- WEB-INF
         +-- web.xml
         +-- jboss-web.xml
   +-- test
     +-- java

Onde:

<código-do-layout>: nome/Identificador do layout;
 src/main/resources/application.info: arquivo de configuração do layout,
onde é persistida, entre outras informações, o código do layout, título e
desenvolvedor. Este arquivo será mais detalhado nas próximas páginas deste
documento;
 src/main/resources/layout.ftl: arquivo do freemarker que será interpretado
durante a renderização do layout, contém a configuração dos Slots;
 src/main/resources/<código-do-layout>.properties: arquivo de strings
traduzíveis utilizadas pelo layout. Deve possuir derivações de acordo com o
idioma suportado pelo layout;
 src/main/webapp/WEB-INF/web.xml: Descritor padrão de uma aplicação
Java para web;
 src/main/webapp/WEB-INF/jboss-web.xml: Descritor específico para o
JBoss. Deve conter pelo menos a propriedade “context-root”. O context-root
representa o contexto Web do layout e é recomendado que seja o próprio
código do layout;
 src/main/webapp/WEB-INF/glassfish-web.xml: Descritor específico para o
Glassfish. Deve conter pelo menos a propriedade “context-root”. O context-
root representa o contexto Web do layout e é recomendado que seja o próprio
código do layout;

src/main/webapp/resources/css: folhas de estilo do layout (caso seja
necessário);
 src/main/webapp/resources/js: arquivos Javascript do layout (caso seja
necessário);
 src/main/webapp/resources/images/icon.png: ícone que representa o
layout, é exibido, por exemplo, durante a criação de páginas para que o
usuário possa pré-visualizar a distribuição de slots do layout.;
 pom.xml: descritor Maven do layout. Este arquivo será mais detalhado nas
próximas páginas deste documento;

Para o sistema, o que diferencia um layout de uma Widget comum é a definição da
propriedade “application.type = layout” no arquivo descritor “application.info”. Este
arquivo é um descritor detalhado das Widgets e também dos layouts, é através deste
que a aplicação tem conhecimento das propriedades do layout, identificação do
desenvolvedor, arquivos necessários para sua renderização, arquivos de linguagem e
outras propriedades. Abaixo o detalhamento de todas as propriedades do arquivo:

Arquivo application.info
 application.type = <layout> : o valor layout define que o componente é do
tipo layout, existem outras opções como Widget e Theme, que não serão
detalhadas neste documento;
 application.code = <código-do-layout> : identificador do layout;
 application.title = <título-do-layout> : título do layout;
 application.description = <descrição-do layout> : descrição do layout;
 application.category = <SYSTEM> : categoria do layout. Propriedade
utilizada para filtro em determinados funções do sistema, esta propriedade é
para uso futuro, atualmente não é utilizada;
 application,renderer = <freemarker> : indica o tipo de renderizador exigido
(atualmente somente o freemarker é suportado);
 application.icon = <icon.png> : ícone para representação visual do layout,
caso não informado o sistema assumirá um ícone padrão para sua
representação visual;
 developer.code = <developer-code> : código do desenvolvedor do layout
(uso futuro);
 developer.name = <TOTVS S.A.> : nome do desenvolvedor (uso futuro);
 developer.url = <http://www.totvs.com> : URL do desenvolvedor (uso futuro);
 layout.file=layout.ftl=<layout.ftl>: nome do arquivo a ser
renderização. Se não informado, será assumido “layout.ftl”;
 locale.file.base.name = <prefixo>: nome base do arquivo de tradução, que
será seguido pelo Locale (ex.: prefixo_PT_BR e prefixo_EN_US) . Se não
informado, será usado o código do layout;
 application.resource.css.1 = </resources/css/<codigo-do-layout>.css> :
opcional. Nome do arquivo CSS a ser carregado durante a renderização.
Podem ser informado vários arquivos, o número no final do dome da
propriedade indica a ordem de carga;

application.resource.js.2 = </resources/js/<código-do-javascript>.js> :
opcional. Nome do arquivo JS a ser carregado durante a renderização.
Podem ser informado vários arquivos, o número no final do nome da
propriedade indica a ordem de carga;
Arquivo pom.xml
O pom é um arquivo fundamental do Maven, deve ficar na raiz da estrutura de pastas fontes de
arquivos do layout. Consiste em um XML com informações do projeto e detalhes das
configurações utilizadas pelo Maven para construir o projeto. É neste descritor que
são inseridas informações como a dependência de outros projetos, plugins, profiles e
versão, entre outras.
A estrutura mínima do pom de um layout é a que segue:

Variáveis Disponíveis no FTL

Os principal arquivo de um projeto de layout é o “layout.ftl”. É neste arquivo que será
definido, via marcação HTML e Freemarker, a quantidade e disposição dos Slots.
Para facilitar o desenvolvimento, alguns métodos da camada de negócio são
ofertados pela infra-estrutura do WCM e podem ser acessados via freemarker.
As variáveis disponibilizadas são acessadas através da sintaxe ${nome-da-variável}
em qualquer local do FTL, a seguir uma lista das variáveis disponíveis:
 serverBaseURL: URL do servidor (sem nenhum contexto);
 i18n: objeto com as strings internacionalizadas;
 themeURI: contexto do tema (por exemplo: /themedefault);
 themeURL: URL completa do tema (serverBaseURL + themeURI);
 pageId: ID da página;
 layoutId: ID do layout;
 layoutURI: contexto do layout (por exemplo: /layoutdefault);
 layoutURL: URL completa do layout (serverBaseURL + layoutURI);
 serverContextURL: contexto do sistema;
 locale: objeto Locale com a localização selecionada para o usuário;
 user: login do usuário (ou vazio se não está logado);
 tenantId: ID do Tenant do usuário logado (-1 se não está logado);
 tenantCode: código do Tenant do usuário logado (ou vazio se não está
logado);
 pageFriendlyURL: URI da página (formado pelo contexto + código da
empresa + código da página);
 wcmEnums: variável de acesso aos enum’s da aplicação. Será detalhado
abaixo;
 wcm: objeto com os serviços disponibilizados pelo SDK do WCM. Será
detalhado abaixo;
 pageRender: objeto que também disponibiliza serviços do SDK. Será
detalhado abaixo;
O objeto “pagetRender” disponibiliza os seguintes métodos do SDK:

PageVO getPage(): retorna um objeto do tipo VO com todas as informações
da página corrente, como sua página pai(caso haja), páginas filhas, layout e
tema entre outras propriedades;
 List<PageVO> listPageBreadcrumb(): retorna uma lista de páginas
ordenadas em modo de navegação estrutural, possibilitando a localização da
página atual em meio estrutura de páginas do sistema;
 void renderInstance(long instanceId): método que inicia a renderização de
uma Widget utilizando o FTL “decoration.ftl”, ou seja, irá renderizar a Widget e
seu título no slot onde foi invocado o método;
 void renderInstanceNoDecorator(long instanceId): método que inicia a
renderização de uma Widget utilizando o FTL

Fluxograma de Renderização

Criando um Layout

“nodecoration.ftl”, ou seja, irá
renderizar a Widget sem a barra de título, no slot onde foi invocado o método;

boolean isUserLogged(): retorna se existe um usuário logado através do VO
da página;
 UserVO getUser(): retorna objeto VO do usuário corrente, contendo
informações como nome,
email e
código do Tenant entre outras
propriedades;
 List<Long> getInstancesIds(Slog slot): retorna uma lista com ID de toads
as Widgets contidas no “slot” informado;
 List<Long> getInstancesByCode(String code): retorna o ID de instância de
todas as widgets com o código informado “code” contidas na página;
 boolean hasPermission (long instanceId, String permission): verifica se a
widget com o “instanceId” informado, possui uma determinada permissão,
conforme a “permission” desejada;
 boolean hasViewPermission (long instanceId): verifica se o usuário logado
possui permissão de visualização da widget;
 boolean hasEditPermission (long instanceId): verifica se o usuário logado
possui permissão de edição para a instancia (“instanceId”) em questão;
 String getHomePage(): retorna a URL de acesso a página inicial (home);
 boolean isUserLoggedInOAuthWithConsumerKey (String consumerKey):
identifica se um usuário logado possui um token válido para o chave de
consumo (“consumerKey”) informada.
 List<WidgetVO> listAllowedWidgetsByUser(): retorna a lista de Widgets as
quais o usuário possuí permissão de visualização;
 Long getTenantId(): retorna o ID do Tenant do usuário corrente;

Fluxograma de Renderização

Toda página renderizada no WCM possui o mesmo fluxo para sua construção. O
primeiro arquivo chamado no processo de renderização é o “master.ftl”, onde são
informados os metadados da página. O arquivo master invoca o método
“pageRender.renderTheme()”, responsável pela renderização do tema, que por sua
vez irá chamar a renderização do layout, onde posteriormente serão renderizadas as
Widgets que compõem a tela, concluindo a construção da página.
O fluxograma a seguir exemplifica o processo de renderização de uma página:

Criando um Layout

Para facilitar a criação de projetos do tipo Layout, foi criado um Archetype Maven.
Um Archetype é um template de projeto Maven, previamente configurado e
estruturado.
O uso do Archetype permite criar um projeto com a estrutura de pastas fontes
idêntica à citada no tópico “Estrutura de Arquivos”, deixando para o desenvolvedor
apenas o trabalho de alterar/adicionar arquivos conforme sua necessidade específica.
A seguir, um passo a passo exemplificando a criação de um layout:

Pré-Requisitos
 JDK 1.7 instalado;
 Apache Maven 3.0.4 (ou superior) instalado;
 Acesso ao Nexus da TOTVS configurado.
Abra uma janela do terminal (ou prompt do DOS) e navegue até a pasta onde deseja
que o layout seja criado. Digite a seguinte linha de comando:

Onde:

Onde:
 DarchetypeVersion: versão do archetype para gerar o layout. Pode ser
omitido. Deve ser informado caso queira gerar para uma versão em
específico.
 DgroupId: groupId do Layout. Parâmetro obrigatório.
 DartifactId: artifactId do Layout. Parâmetro obrigatório.
 Dversion: versão do Layout. Parâmetro obrigatório.
 DparentArtifactId: ID do artefato pai. Parâmetro obrigatório, se não
informado, assumirá "wcm-architecture".
 DapplicationTitle: Título do Layout. Pode ser omitido, porém deverá ser
informado posteriormente.
 DapplicationDescription: Breve descrição do Layout. Pode ser omitido,
porém deverá ser informado posteriormente.
 DdeveloperCode: Código de desenvolvedor. Cada empresa ou grupo deve
padronizar um código. Esse código será usado para validações internas de
permissionamento. Se não informado, assumirá "TOTVS".
 DdeveloperName: Nome da empresa que desenvolveu o Layout. Se não
informado, assumirá "TOTVS S.A.".
 DdeveloperURL: URL da empresa que desenvolveu o Layout. Se não
informado, assumirá "http://www.totvs.com".

DlayoutFile: Nome do arquivo do Layout. Se não informado, assumirá
"layout".
 DapplicationCategory: Categoria do Layout. Se não informado, assumirá
"SYSTEM".
Após a execução do comando, deve ser criada a estrutura de pasta fonte padrão no
diretório escolhido.