Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Índice

Table of Contents
maxLevel4
outlinetrue
exclude.*ndice
stylenone

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>
+-- src
+-- main
+-- java (não utilizado, padrão de 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:

Arquivo / PastaDescrição
<código-do-layout>Nome/Identificador do layout
src/main/resources/application.infoArquivo 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.ftlArquivo 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>.propertiesArquivo 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.xmlDescritor padrão de uma aplicação Java para web.
src/main/webapp/WEB-INF/jboss-web.xmlDescritor 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/cssFolhas de estilo do layout (caso seja necessário).
src/main/webapp/resources/jsArquivos 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:
PropriedadeDescriçã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.
developer.name = <TOTVS S.A.>Nome do desenvolvedor.
developer.url = <http://www.totvs.comURL do desenvolvedor.
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 nome 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.
slot.SlotMenu = <menu>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.
slot.SlotLogin = <sociallogin>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.


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ávelDescrição
serverBaseURLURL do servidor (sem nenhum contexto).
i18nObjeto com as strings internacionalizadas.
themeURIContexto do tema (por exemplo: /themedefault).
themeURLURL completa do tema (serverBaseURL + themeURI).
pageIdID da página.
layoutIdID do layout.
layoutURIContexto do layout (por exemplo: /layoutdefault).
layoutURLURL completa do layout (serverBaseURL + layoutURI).
serverContextURLContexto do sistema.
localeObjeto com a localização selecionada para o usuário.
userLogin do usuário (ou vazio se não está logado).
tenantIdID do Tenant do usuário logado (-1 se não está logado).
tenantCodeCódigo do Tenant do usuário logado (ou vazio se não está logado).
pageFriendlyURLURI da página (formado pelo contexto + código da empresa + código da página).
wcmEnumsVariável de acesso aos enum’s da aplicação.
wcmObjeto com os serviços disponibilizados pelo SDK do WCM.
pageRenderObjeto que também disponibiliza serviços do SDK.
fluigVersionVersão do fluig.


O objeto “pageRender” disponibiliza os seguintes métodos do SDK:

MétodoDescriçã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.

Info

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<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

É possível criar um layout a partir do fluig Studio. O tutorial com o passo-a-passo encontra-se aqui

  • Uma vez finalizando o tutorial, o Studio preparará um ambiente semelhante a esse:

  • Ou, no caso de ter-se optado por um layout vazio, aparecerá o seguinte conteúdo:

  • 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

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:

Code Block
languagexml
themeEclipse
<#import "/wcm.ftl" as wcm/>
<@wcm.header public="true"/>
<!-- WCM Wrapper content -->
<div class="wcm-wrapper-content">
    <@wcm.menu />
    <!-- Wrapper -->
    <div class="wcm-all-content">
        <div id="wcm-content" class="clearfix wcm-background">
            <!-- Your content here -->
            <@wcm.footer layoutuserlabel="wcm.layoutdefault.user" />
        </div>
    </div>
</div>

Código do Slot

O código de um slot é composto dos seguintes elementos:

Code Block
languagexml
<div class="editable-slot slotfull layout-1-1" id="slotContainer001">
	<@wcm.renderSlot id="Slot001" decorator="false" editableSlot="false" />
</div>

Sobre o  primeiro elemento "div":


Code Block
languagexml
<div class="editable-slot slotfull layout-1-1" id="slotContainer001"> ... </div>
PropriedadeFunção

id="slotContainer001"

slotContainer001:

Idendificação

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.


Sobre o segundo elemento "div"
:


Code Block
languagexml
...<@wcm.renderSlot id="Slot001" decorator="false" editableSlot="false" />...
PropriedadeFunçã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


Posicionamento do Slot

Na primeira "div" do conjunto de elementos de um slot, podemos encontrar o seguinte código:

Code Block
languagexml
<div id="slotContainer001" class="editable-slot slotfull layout-1-1">

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 fluig:

ValorPosiçãoLargura
layout-1-3
Esquerda32%
layout-2-3
Esquerda65%
layout-1-2left
Esquerda50%
layout-1-1
---100%
layout-1-2right
Direita50%
layout-1-3right
Direita32%
Info
titleNão se esqueça

Leia a sobre mudança no layout de uma página


Sobre Slots Não Editáveis

Um layout pode, ou não, conter slots não editáveis. Naqueles fornecidos pelo fluig 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 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:

Code Block
languagexml
	<div id="SlotInstantSearch" slot="true" class="slotint slot-header-actions">
		<#list (pageRender.getInstancesIds("SlotInstantSearch"))! as id>
			${pageRender.renderInstanceNoDecorator(id)}
		</#list>
	</div>

Propriedade do application.info:

slot.SlotInstantSearch=widget_search


Slot de Alertas Globais:

Code Block
languagexml
	<div id="SlotGlobalAlert" slot="true" class="slotint slot-header-actions">
		<#list (pageRender.getInstancesIds("SlotGlobalAlert"))! as id>
			${pageRender.renderInstanceNoDecorator(id)}
		</#list>
	</div>

Propriedade do application.info:

slot.SlotGlobalAlert=alertpopover


Slot de Login:

Code Block
languagexml
	<div class="header-grouper-right">
		<div id="SlotLogin" slot="true" class="slot-header-actions">
			<#list (pageRender.getInstancesIds("SlotLogin"))! as id>
				${pageRender.renderInstanceNoDecorator(id)}
			</#list>
		</div>
	</div>

Propriedade do application.info:

slot.SlotLogin=sociallogin


Slot de Menu:

Code Block
languagexml
<@wcm.menu />

opriedade do application.info:

slot.SlotMenu=menu


Slot de Rodapé:

Code Block
languagexml
<@wcm.footer layoutuserlabel="wcm.layoutdefault.user" />

opriedade do application.info:

slot.SlotUsePolicy=usepolicy
Info
titleImportante

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.

Code Block
languagexml
<div id="divSlot1" class="editable-slot">
    <@wcm.renderSlot id="SlotA" decorator="true" editableSlot="true" />
</div>

Resultado: