--- title: Layouts source: https://tdn.totvs.com/display/fluig/Layouts path: \Plataforma Documentação técnica\Recurso de Páginas e Widgets (WCM)\Construção de Widgets e Layouts\Layouts.md --- ## Índice - 1 [Sobre Layouts](#Layouts-SobreLayouts) - 2 [Slot](#Layouts-Slot) - 3 [Estrutura de Arquivos](#Layouts-EstruturadeArquivos) - 3.1 [Arquivo application.info](#Layouts-Arquivoapplication.info) - 3.2 [Variáveis Disponíveis no FTL](#Layouts-VariáveisDisponíveisnoFTL) - 3.3 [Macros para o uso no FTL dos layouts:](#Layouts-MacrosparaousonoFTLdoslayouts:) - 4 [Fluxograma de Renderização](#Layouts-FluxogramadeRenderização) - 5 [Criando um Layout](#Layouts-CriandoumLayout) - 6 [Código do Layout](#Layouts-CódigodoLayout) - 7 [Código do Slot](#Layouts-CódigodoSlot) - 8 [Posicionamento do Slot](#Layouts-PosicionamentodoSlot) - 9 [Sobre Slots não editáveis](#Layouts-SobreSlotsnãoeditáveis) - 10 [Como exibir/ocultar títulos das widgets no slot](#Layouts-Comoexibir/ocultartítulosdaswidgetsnoslot) # 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. ![](..\..\..\images\layout3.png) # 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. ![](..\..\..\images\layout1.png) # 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: | ``` +-- src +-- main +-- java (não utilizado, padrão de widgets) +-- resources +-- application.info +-- layout.ftl +-- .properties +-- _en_US.properties +-- _es.properties +-- _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 | | --- | --- | | **** | 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/.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 servidor de aplicação. 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. | 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 = ** | O valor layout define que o componente é do tipo layout, existem outras opções como widget e theme. | | **application.code = ** | Iidentificador do layout. | | **application.title = ** | Título do layout. | | **application.description = ** | Descrição do layout. | | **application.category = ** | Categoria do layout. Propriedade utilizada para filtro em determinados funções do sistema, esta propriedade é para uso futuro, atualmente não é utilizada. | | **application.renderer = ** | Indica o tipo de renderizador exigido (atualmente somente o Freemarker é suportado). | | **application.icon = ** | Í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 = ** | Código do desenvolvedor do layout. | | **developer.name = ** | Nome do desenvolvedor. | | **developer.url = <[http://www.totvs.com](http://www.totvs.com/)****>** | URL do desenvolvedor. | | **layout.file=layout.ftl = ** | Nome do arquivo a ser renderização. Se não informado, será assumido “layout.ftl”. | | **locale.file.base.name = ** | 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 = .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 nome da propriedade indica a ordem de carga. | | **application.resource.js.2 = .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. | | **slot.SlotMenu = ** | Opcional. Entretanto, quando o arquivo .ftl possuir slot de Menu (SlotMenu), é necessário informar qual widget de menu deve ser utilizada. *"menu"* deve ser informado nesse caso. Entenda melhor [aqui](http://tdn.totvs.com/display/fluig/Layouts#Layouts-SobreSlotsNãoEditáveis). | | **slot.SlotLogin = ** | Opcional. Entretanto, quando o arquivo .ftl possuir slot de Login (SlotLogin), é necessário informar qual widget de login deve ser usada. Apesar de haver mais de um opção para menu, recomendamos a utilização do valor *"sociallogin"* nesse caso. Entenda melhor [aqui](http://tdn.totvs.com/display/fluig/Layouts#Layouts-SobreSlotsNãoEditáveis). | | **application.resource.css.1=/portal/resources/css/wcm\_responsive\_layout.css** | Arquivo CSS com configurações globais para a padronização de escrita dos layouts. Sempre necessário incluir. A propriedade estará disponível a partir da **release 1.8.1** do TOTVS Fluig Plataforma. | | **application.resource.css.2=/resources/css/responsive\_layout.css** | Arquivo CSS padrão para o desenvolvimento da responsividade do layout. A propriedade estará disponível a partir da **release 1.8.1** do TOTVS Fluig Plataforma. | | **application.responsiveLayout=true** | Caso o valor seja true, ilustrará que o layout é responsivo no momento do cadastro de páginas. A propriedade estará disponível a partir da **release 1.8.1** do TOTVS Fluig Plataforma. | | **application.newBuilder=true** | Se true significa que a página será carregada no novo construtor. Se false significa que a página será carregada no antigo construtor. Entenda melhor **[aqui](https://tdn.totvs.com/x/fYP5DQ)**. A propriedade estará disponível a partir da **release 1.8.1** do TOTVS Fluig Plataforma. | ## 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. | | wcm | Objeto com os serviços disponibilizados pelo SDK do WCM. | | pageRender | Objeto que também disponibiliza serviços do SDK. | | fluigVersion | Versão do TOTVS Fluig Plataforma. | O objeto “**pageRender**” 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 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. As informações de grupos e papéis do usuário não são apresentadas neste objeto e o uso deste tipo de informação para validações no desenvolvimento de widgets não é recomendado, pois afeta o desempenho do carregamento das páginas. | | **List getInstancesIds(Slog slot)** | Retorna uma lista com ID de todas os widgets contidas no “slot” informado. | | **List 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 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. | | **pageRender.isPreviewMode()** | Diz se a página está em modo preview ou não true|false. | | **pageRender.isEditMode()** | Diz se a página está em modo edição ou não true|false. | ## Macros para o uso no FTL dos layouts: Arquivo que disponibiliza as macros para o layout: "**<#import "/wcm.ftl" as wcm />**". | Método | Descrição | | --- | --- | | **<@wcm.previewPageAlert />** | Alerta no topo da página informando que a página está em modo de pré-visualização. | | **<@wcm.header />** | Widget de cabeçalho da página (independente do tema). | | **<@wcm.menu />** | Widget de menu da página  (independente do tema). | | **<@wcm.editHeader />** | Widget de cabeçalho da página no modo de edição. | | **<@wcm.widgetsList />** | Widget que faz a listagem de widgets disponíveis para serem adicionadas em uma página. | | **<@wcm.renderSlot id="SlotA" editableSlot="true" isResponsiveSlot="true" />** | Macro padrão para renderização de um slot. (se o parâmetro isResponsiveSlot for true, implementa o visual novo com as ações novas em uma widget). | | **<@wcm.footer layoutuserlabel="wcm.layoutdefaultecmdashboard.user" />** | Widget padrão para o rodapé da página. | # 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: ![](..\..\..\images\layout2.png) # Criando um Layout É possível criar um layout a partir do Fluig Studio. O tutorial com o passo-a-passo encontra-se [aqui](http://tdn.totvs.com/pages/viewpage.action?pageId=113803693#ConstruçãodecomponentesWCMnoFluigStudio-CriaçãodeLayout) - Uma vez finalizando o tutorial, o Studio preparará um ambiente semelhante a esse: ![](..\..\..\images\im1.png) - Ou, no caso de ter-se optado por um layout vazio, aparecerá o seguinte conteúdo: ![](..\..\..\images\empty1.png) - Para criar um slot, nesse caso, pode-se usar o Snippet "Slot de um Layout" disponível nos exemplos de código do Studio. - Entenda o impacto na forma como você cria o layout na sessão sobre [mudança no layout de uma página](http://tdn.totvs.com/pages/viewpage.action?pageId=185745580) # Código do Layout Apesar de a estrutura fornecida pelos templates do Studio não serem obrigatórios, é aconselhável o uso de alguns elementos essenciais quando do desenvolvimento de um layout a partir da estaca zero, como por exemplo: ``` <#import "/wcm.ftl" as wcm/> <#-- Variaveis globais para os layouts --> <#import "/layout-globals.ftl" as globals /> <#if pageRender.isPreviewMode() = true> <@wcm.previewPageAlert /> <@wcm.deviceTogglePreview />
<#if pageRender.isEditMode() = false> <@wcm.header authenticated=pageRender.isUserLogged()?c /> <@wcm.menu />
<#if pageRender.isEditMode()=true> <@wcm.editHeader /> <@wcm.widgetsList />
<@wcm.renderSlot id="SlotC" editableSlot="true" decorator="false" isResponsiveSlot="true" />
<#if fluigThemeCode != "responsive_theme"> <@wcm.footer layoutuserlabel="wcm.layoutdefault.user" />
``` ``` <#import "/wcm.ftl" as wcm/> <@wcm.header public="true"/>
<@wcm.menu />
<@wcm.footer layoutuserlabel="wcm.layoutdefault.user" />
``` # Código do Slot O código de um slot é composto dos seguintes elementos: ```
<@wcm.renderSlot id="Slot001" decorator="false" editableSlot="false" isResponsiveSlot="true" />
``` **Sobre o  primeiro elemento "div":** ```
...
``` | Propriedade | Função | | --- | --- | | **id**="slotContainer001" | **slotContainer001**: Identificação única do *container*. Não pode haver outro elemento com esse mesmo código. O tamanho máximo para um ID de slot é 50 caracteres. | | **class**="editable-slot slotfull layout-1-1" | **editable-slot** e **slotfull**: Usado pelo renderizador para montar o editor individual de slot. **layout-1-1**: Usado para posicionar o slot em um determinado ponto da tela. Será detalhado [adiante](http://tdn.totvs.com/display/fluig/Layouts#Layouts-PosicionamentodoSlot). | **Sobre o segundo elemento "div"**: ``` ...<@wcm.renderSlot id="Slot001" decorator="false" editableSlot="false" isResponsiveSlot="true" />... ``` | Propriedade | Função | | --- | --- | | **id**="Slot001" | **Slot001**: Identificação única do slot. Não pode haver outro elemento com esse mesmo código | | **decorator**="false" | **true**: As widgets posicionadas neste slot **exibem** seus títulos **false**: As widgets posicionadas neste slot **não exibem** seus títulos | | **editableSlot**="false" | **true**: Torna possível inserir e retirar widgets dentro do slot bem como mudar o posicionamento delas **false**: Não permite qualquer edição no conteúdo do Slot. Slots de cabeçalho, rodapé e login geralmente estão com esse valor | | **isResponsiveSlot**="true" | **true**: implementa o novo visual com ações novas em uma widget. **false**: Renderiza o visual antigo. | # Posicionamento do Slot Na primeira "div" do conjunto de elementos de um slot, podemos encontrar o seguinte código: ```
``` O valor **"layout-1-1"** refere-se ao posicionamento daquele layout dentro da página. Segue abaixo a lista dos posicionamentos de slot disponíveis dentro do TOTVS Fluig Plataforma: | Valor | Posição | Largura | | --- | --- | --- | | ``` layout-1-3 ``` | Esquerda | 32% | | ``` layout-2-3 ``` | Esquerda | 65% | | ``` layout-1-2left ``` | Esquerda | 50% | | ``` layout-1-1 ``` | --- | 100% | | ``` layout-1-2right ``` | Direita | 50% | | ``` layout-1-3right ``` | Direita | 32% | Não se esqueça Leia a sobre [mudança no layout de uma página](http://tdn.totvs.com/pages/viewpage.action?pageId=185745580) # Sobre Slots não editáveis Um layout pode, ou não, conter slots não editáveis. Naqueles fornecidos pelo Fluig Plataforma como templates, há 5 slots que não são editáveis por padrão. Para cada slot não-editável, é necessário criar uma propriedade no [application.info](http://tdn.totvs.com/display/fluig/Layouts#Layouts-Arquivoapplication.info) relacionado o id do slot ao código da widget que estará contida nele, pois essa é a forma de inserir conteúdo em um slot não-editável. **Slot de Busca:** ```
<#list (pageRender.getInstancesIds("SlotInstantSearch"))! as id> ${pageRender.renderInstanceNoDecorator(id)}
``` Propriedade do [application.info](http://tdn.totvs.com/display/fluig/Layouts#Layouts-Arquivoapplication.info): ``` slot.SlotInstantSearch=widget_search ``` **Slot de Alertas Globais:** ```
<#list (pageRender.getInstancesIds("SlotGlobalAlert"))! as id> ${pageRender.renderInstanceNoDecorator(id)}
``` Propriedade do [application.info](http://tdn.totvs.com/display/fluig/Layouts#Layouts-Arquivoapplication.info): ``` slot.SlotGlobalAlert=alertpopover ``` **Slot de Login:** ```
<#list (pageRender.getInstancesIds("SlotLogin"))! as id> ${pageRender.renderInstanceNoDecorator(id)}
``` Propriedade do [application.info](http://tdn.totvs.com/display/fluig/Layouts#Layouts-Arquivoapplication.info): ``` slot.SlotLogin=sociallogin ``` **Slot de Menu:** ``` <@wcm.menu /> ``` Propriedade do [application.info](http://tdn.totvs.com/display/fluig/Layouts#Layouts-Arquivoapplication.info): ``` slot.SlotMenu=menu ``` **Slot de Rodapé:** ``` <@wcm.footer layoutuserlabel="wcm.layoutdefault.user" /> ``` Propriedade do [application.info](http://tdn.totvs.com/display/fluig/Layouts#Layouts-Arquivoapplication.info): ``` slot.SlotUsePolicy=usepolicy ``` Importante o valor do parâmetro "layoutuserlabel" deve ser uma chave existente em um dos arquivos .properties do seu projeto # Como exibir/ocultar títulos das widgets no slot Para exibir o título das widgets no slot é possível utilizar a propriedade decorator na macro renderSlot. Por padrão os títulos das widgets não são exibidos na utilização da macro renderSlot. Porém é possível exibir os títulos alterando a propriedade *decorator="true"* no código do slot conforme exibido abaixo. Assim, todas as widgets posicionadas neste slot terão um título visível no topo. ```
<@wcm.renderSlot id="SlotA" decorator="true" editableSlot="true" />
``` **Resultado**: ![](..\..\..\images\tituloWidget.png)