Backend dos Temas
O objetivo deste capítulo é fazer um overview da estrutura dos temas do Mapas Culturais no nível do PHP.
Last updated
O objetivo deste capítulo é fazer um overview da estrutura dos temas do Mapas Culturais no nível do PHP.
Last updated
Quando o controlador chama a renderização de uma visão, o HTML resultante é enviado para o arquivo de layout.
Os layouts são arquivos de template PHP e implementam a moldura das páginas. São os arquivos .php que ficam diretamente na pasta layouts. Normalmente, implementam (ou incluem) pelo menos um header e um footer e recebem numa variável $TEMPLATE_CONTENT o HTML da visão já renderizado.
layouts/default.php: É o layout padrão utilizado pelo tema quando não é informado outro no controller ou template.
A implementação do BaseV1 é a seguinte:
layouts/panel.php: É o layout utilizado pelas páginas do painel.
A implementação do BaseV1 é a seguinte:
As visões são arquivos de template PHP relacionados aos controladores e ficam na pasta views/{controller_slug}. Cada controlador tem seu conjunto de arquivos de visão. São renderizados pelo controlador quando invocado o método Controller::render e podem receber variáveis vindas do controlador.
O exemplo abaixo renderiza o arquivo views/controlador/visao.php, que recebe uma variável $variavel com valor "valor":
Os template parts, como o nome diz, são partes de template que podem ser incluídas pelos arquivos de layout, de visão ou mesmo por outros template parts. Ficam na pasta layouts/parts e são compartilhados por todas as visões e controladores. São renderizados pela visão quando invocado o método Theme::part e podem receber variáveis.
No exemplo abaixo, uma visão inclui o template layouts/parts/parte.php, que recebe a variável $titulo.
Há algumas funções auxiliares para a utilização nos arquivos de layout, visão e template parts.
head;
printDocumentMetaImprime as tags <meta > configuradas na propriedade $documentMeta do tema, como no exemplo a seguir:
O trecho acima resultará no HTML abaixo:
getTitleGera um título para a rota atual, de acordo com a seguinte regra:
Se for uma rota de entidade (single ou edição de agentes, espaços, projeto etc), o título retornado será "{$entity->name} - {siteName}", por exemplo "Fulano de Tal - Mapa da Cultura";
Se a rota for a home do mapas (controller site, action index), o título retornado será "{siteName}", por exemplo "Mapa da Cultura";
Se a rota dor a home do painel, o título retornado será "Painel";
Nome configurado na aplicação em $app->config['routes']['readbleNames'].
bodyPropertiesImprime as propriedades da tag <body >, baseado no que foi configurado nas propriedades $bodyProperties e $bodyClasses, como no exemplo a seguir:
O trecho acima resultará no HTML abaixo:
headAplica o hook mapasculturais.head e invoca o método printDocumentMeta. Deve ser utilizado no final da tag <head>.
bodyBeginEsta função deve ser invocada logo após a abertura da tag <body> e a única coisa que faz é aplicar o hook mapasculturais.body:before.
bodyEndEsta função deve ser invocada antes do fechamento da tag <body> e a única coisa que faz é aplicar o hook mapasculturais.body:after.
isEditableEsta função indica se a aplicação está em uma página onde os campos devem ser editáveis (create ou edit).
printScriptsImprime a(s) tag(s) <script > dos scripts enfileirados do grupo informado.
O trecho acima resultará no HTML abaixo:
printStylesImprime a(s) tag(s) <link rel="stylesheet" > dos scripts enfileirados do grupo informado.
O trecho acima resultará no HTML abaixo:
As modais de criação de entidade implementadas na versão v5.0.0 do Mapas Culturais são renderizados utilizando a função BaseV1\Theme::renderModalFor, que renderiza o botão que abre a modal.
Os arquivos de layout, visão, template parts e assets podem estar nas pastas do tema pai (BaseV1), do tema filho implementado, de um módulo ou de um plugin. Os temas, plugins e módulos incluem/registram seu caminho no tema ativo chamando a função addPath que cria um pilha de caminhos, dessa maneira quando um tema precisa utilizar um arquivo ele chama a função resolveFilename que passa pela pilha de caminhos procurando o arquivo. É importante observar que é uma pilha e não uma fila, ou seja o último caminho que foi incluído será o primeiro a ser pesquisado.
addPath: Adiciona um caminho à pilha de caminhos de resolução de nome de arquivos;
resolveFilename: Busca o arquivo na pilha de caminhos.
Por exemplo, vamos supor que o tema precisa incluir o arquivo layouts/parts/teste.php. Ele será procurado primeiro nos plugins ativos, depois nos módulos, depois no tema filho e, por último, no tema pai.
Para incluir os estilos e scripts necessários para a visão, deve-se utilizar os métodos Theme::enqueueScript e Theme::enqueueStyle. Deve-se, também, informar as dependências do script/estilo. Assim, o asset manager saberá ordenar os mesmos.
Ainda, deve-se informar o grupo ao qual pertence o script/estilo, sendo que o BaseV1 utiliza o grupo app para os scripts e estilos desenvolvidos para a aplicação, e o grupo vendor para as bibliotecas incluídas.
O AssetManager gerencia a publicação de assets dos temas, plugins ou módulos, se encarregando de minificar os JS e CSS. Quando configurado deste jeito, ou para modo de desenvolvimento, ele faz uma cópia do arquivo para a pasta /assets, sem processá-lo.
Quando configurado para fazer merge dos scripts/estilos, será criado um arquivo para cada grupo de enfileiramento, contendo o código de todos os estilos/scripts enfileirados.
As funções includeAssets são funções que enfileiram e/ou publicam conjuntos de assets de determinadas funcionalidades ou contextos. Costumam ser chamadas via hook ou pelos arquivos de visão e partes de template:
includeVendorAssets: Inclui os assets das bibliotecas utilizadas pelo frontend;
includeCommonAssets: Inclui os assets utilizados por todas as páginas;
includeIbgeJS: Enfileira JavaScript utilizado nos selects de estados/cidades brasileiras;
includeChatAssets: Inclui os assets dos chat threads;
includeEditableEntityAssets: Inclui os assets das páginas de edição das entidades;
includeSearchAssets: Inclui os assets da página de busca;
includeMapAssets: Inclui os assets necessários para;
includeAngularEntityAssets: Inclui os assets necessários para os componentes/módulos angular.
A propriedade $jsObject, do tipo ArrayObject, é a maneira que o tema do Mapas Culturais oferece para o desenvolvedor enviar dados do PHP para o JavaScript.
O que quer que seja colocado dentro deste objeto, será codificado como JSON dentro do objeto MapasCulturais no JavaScript.
O código abaixo pode ser executado em método do tema ou nos arquivos de layout, visões ou template:
No JavaScript chegará:
As funções addToJs adicionam ao jsObject dados que os scripts precisam para funcionar.
addEntityToJs: Cria a chave entity com a seguinte estrutura para a entidade passada como parâmetro:
addEntityTypesToJs: Cria a chave entityTypes com a lista de tipos da entidade passada como parâmetro;
addOccurrenceFrequenciesToJs: Cria a chave frequencies com as opções de frequência para as ocorrências de evento;
addTaxonoyTermsToJs: Adiciona uma lista com os termos da taxonomia informada dentro da chave taxonomyTerms;
addRelatedAgentsToJs: Adiciona a lista de agentes relacionados à chave agentRelations dentro da chave entity;
addRelatedAdminAgentsToJs: Adiciona a lista dos agentes relacionados com controle sobre a entidade à chave agentAdminRelations dentro da chave entity;
addSubsiteAdminsToJs: Adiciona os administradores e super administradores às chaves admins e superAdmins dentro da chave entity.
Para localizar os textos dos templates, utiliza-se as funções da classe MapasCulturais\i:
Já para localizar strings utilizadas por componentes JavaScript, utiliza-se o método localizeScript, da maneira demonstrada abaixo:
O trecho acima criará a seguinte estrutura no JavaScript e dessa maneira os scripts do JavaScript podem utilizar os textos traduzidos:
@todo