Índice
- Sobre Layouts
- Slot
- Estrutura de Arquivos
- Variáveis Disponíveis no FTL
- Fluxograma de Renderização
- Criando um Layout
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.
Image RemovedImage Added
Slot
Slots são contêineres definidos que são aptos a comportarem Widgetswidgets. A quantidade, posição e dimensão desses slots é o que define o corpo de um templatelayout. Sendo assim, o template layout é o esqueleto de uma página (sua estrutura), definindo a distribuição das Widgets dos widgets que a compõem através do dos slots.
Image AddedEstrutura de Arquivos
Layouts possuem a estrutura de arquivos semelhante à de 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 dasde Widgetswidgets) +-- 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:
Arquivo / Pasta | Descrição |
---|
<código-do-layout> |
: nome | Nome/Identificador do layout |
; src/main/resources/application.info |
: arquivo | 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 |
; src/main/resources/layout.ftl |
: arquivo freemarker Freemarker que será interpretado |
durante a renderização do layout |
, contém . Contém a configuração dos |
Slots; src/main/resources/<código-do-layout>.properties |
: arquivo 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 |
; 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 |
; 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 |
;. |
src/main/webapp/resources/css |
: folhas | Folhas de estilo do layout (caso seja |
; src/main/webapp/resources/js |
: arquivos | Arquivos Javascript do layout (caso seja |
; src/main/webapp/resources/images/icon.png |
: ícone 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. |
; : descritor | 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 um widget comum é a definição da
propriedade da propriedade “application.type = layout” no arquivo descritor “application.info”. Este
arquivo Este arquivo é um descritor detalhado das Widgets dos widgets e também dos layouts, é através deste
que . É através deste que a aplicação tem conhecimento das propriedades do layout, identificação do
desenvolvedordo desenvolvedor, arquivos necessários para sua renderização, arquivos de linguagem e
outras propriedades. e outras propriedades.
Arquivo application.info
Abaixo o detalhamento de todas as propriedades do arquivo application.info:
Arquivo application.info Propriedade | Descrição |
---|
application.type = |
<layout> : o <layout> | O valor layout define que o componente é do |
tipo layout, existem outras opções como |
Widget e Theme, que não serãodetalhadas neste documento; widget e theme. |
application.code = <código-do-layout> |
: identificador ; application.title = <título-do-layout> |
: título ; application.description = <descrição-do layout> |
: descrição ; application.category = <SYSTEM> |
: categoria | Categoria do layout. Propriedade |
utilizada para filtro em determinados funções do sistema, esta propriedade é para uso futuro, atualmente não é utilizada |
; , : indica | Indica o tipo de renderizador exigido |
freemarker ; application.icon = <icon.png> |
: ícone | Ícone para representação visual do layout |
,caso . Caso não informado o sistema assumirá um ícone padrão para sua representação visual |
; developer.code = <developer- |
code> : código code> | Código do desenvolvedor do layout |
; name : nome | Nome do desenvolvedor (uso futuro) |
; > : > | URL do desenvolvedor (uso futuro) |
; layout.file=layout.ftl = <layout.ftl> |
: nome renderização. Se não informado, será assumido “layout.ftl” |
; name: nome | Nome base do arquivo de tradução |
, Locale 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> |
:opcionalOpcional. 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> |
:opcionalOpcional. 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.xml é um arquivo fundamental do Maven, deve . Deve ficar na raiz da estrutura de
arquivos de arquivos do layout. Consiste em um XML com informações do projeto e detalhes das
configurações das configurações utilizadas pelo Maven para construir o projeto. É neste descritor que
são que são inseridas informações como a dependência de outros projetos, plugins, profiles e
versãoe versão, entre outras.
A Sua estrutura mínima do pom de um para um layout é a que segue:
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>[grupID]</ groupId> <artifactId>[grupID]</artifactId> <packaging>war</packaging> <name>[Nome do <name>[Nome do layout]</name> <description>[Descrição do layout]</description> <properties> <project.build. sourceEncoding> UTF-8 <sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <build> <plugins> <plugin>
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId> maven <artifactId>maven-compiler- plugin <plugin</artifactId> <configuration> <source>1.7</source> <target>1.7</target> </configuration> </plugin> </plugins> </build> </project> |
---|
<target>1.7</target> </configuration> </plugin> </plugins> </build> </project> |
---|
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 “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:
mvn archetype:generate -DarchetypeGroupId=com.totvs.technology -DarchetypeArtifactId=layout-wcm -DarchetypeVersion=4.0.3-SNAPSHOT -DgroupId=<Group ID do Layout> -DartifactId=<Artifact ID do Layout> -Dversion=<Versao do Layout> -DparentArtifactId=”<ID do artefato pai>” -DapplicationTitle=”<Titulo do Layout>” -DapplicationDescription=”<Descricao to Layout>” -DdeveloperCode=”<Codigo de desenvolvedor>” -DdeveloperName=”<Nome do desenvolvedor>” -DdeveloperURL=”<URL do desenvolvedor>” -DlayoutFile=”<Nome do arquivo layout>” SEM a extensão “.ftl” -DapplicationCategory=”<Categoria>” -DapplicationCategory=”<Categoria>” |
---|
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.