Histórico da Página
Í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.
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 layout. Sendo assim, o layout é o esqueleto de uma página (sua estrutura), definindo a distribuição dos widgets que a compõem através dos slots.
Estrutura 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> |
---|
Onde:
Arquivo / Pasta | Descrição |
---|---|
<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 um widget comum é a definição da propriedade “application.type = layout” no arquivo descritor “application.info”. Este arquivo é um descritor detalhado dos 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.
Arquivo application.info
Abaixo o detalhamento de todas as propriedades do arquivo application.info:Propriedade | Descrição |
---|---|
application.type = <layout> | O valor layout define que o componente é do tipo layout, existem outras opções como widget e theme. |
application.code = <código-do-layout> | Iidentificador 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.xml é um arquivo fundamental do Maven. Deve ficar na raiz da estrutura 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. Sua estrutura mínima para um layout é a que segue:
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" 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 layout]</name> <description>[Descrição do layout]</description> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.7</source> <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:
Variável | Descrição |
---|---|
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 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:
Método | Descrição |
---|---|
PageVO getPage() | Retorna um objeto do tipo VO com todas as informações da página corrente, como sua página pai (caso exista), 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 um widget utilizando o FTL “decoration.ftl”, ou seja, irá renderizar o 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 um widget utilizando o FTL “nodecoration.ftl”, ou seja, irá renderizar o 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 todas os widgets contidas no “slot” informado. |
List<Long> getInstancesByCode(String code) | Retorna o ID de instância de todas os widgets com o código informado “code” contidas na página. |
boolean hasPermission(long instanceId, String permission) | Verifica se o 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 do 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 os 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
Há duas formas de criar um novo layout:
- Utilizando um template Archetype Maven.
- Utilizando o plug-in do Fluig disponível no TOTVS Studio.
Utilizando um template Archetype Maven
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>-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>”
-DartifactIdDdeveloperName=<Artifact ID do Layout> -Dversion=<Versao do Layout> -DparentArtifactId=”<ID do artefato pai>” -DapplicationTitle=”<Titulo do Layout>””<Nome do desenvolvedor>”
-DapplicationDescription=”<Descricao to Layout>” -DdeveloperCode=”<Codigo de desenvolvedor>” -DdeveloperName=”<Nome DdeveloperURL=”<URL do desenvolvedor>”
-DdeveloperURL=”<URL do desenvolvedor>” -DlayoutFile=”<Nome do arquivo layout>” SEM a extensão “.ftl”
-DapplicationCategory=”<Categoria>” -DapplicationCategory=”<Categoria>”
Onde:
Parâmetro | Descrição |
---|---|
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.
//TODO: VERIFICAR ALTERAÇÕES NO PROCESSO DE CONSTRUÇÃO DE LAYOUTS, PARÂMETROS QUE FORAM MODIFICADOS, MÉTODOS ETC. (INSERIDOS OU REMOVIDOS).
Utilizando o plug-in do Fluig disponível no TOTVS Studio
//TODO: VERIFICAR SE JÁ EXISTE (PLUG-IN STUDIO TOTVS)