Backend dos Temas

O objetivo deste capítulo é fazer um overview da estrutura dos temas do Mapas Culturais no nível do PHP.

Layouts, Visões e Template parts

Quando o controlador chama a renderização de uma visão, o HTML resultante é enviado para o arquivo de layout.

Layouts

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:

<?php
$this->part('header', $render_data);
echo $TEMPLATE_CONTENT;
$this->part('footer', $render_data);

layouts/panel.php: É o layout utilizado pelas páginas do painel.

A implementação do BaseV1 é a seguinte:

<?php
$this->part('header', $render_data);
$this->part('panel-nav', $render_data);
echo $TEMPLATE_CONTENT;
$this->part('panel-settings-nav', $render_data);

$this->part('footer', $render_data);

Visões

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

class Controlador extends \MapasCulturais\Controler {
   function GET_acao() {
      $this->render('exemplo', ['variavel' => 'valor']);
   }
}

Template parts

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.

$this->part('parte', ['titulo' => 'Título']);

Funções de template

Há algumas funções auxiliares para a utilização nos arquivos de layout, visão e template parts.

`printDocumentMeta`

Imprime as tags <meta > configuradas na propriedade $documentMeta do tema, como no exemplo a seguir:

   // $this é a instância do tema ativo
   $this->documentMeta[] = [
      'name' => 'viewport', 
      'content' => 'width=device-width, initial-scale=1, maximum-scale=1.0'
   ];
   $this->documentMeta[] = [
      "property" => 'og:title', 
      'content' => 'Mapa da Cultura'
   ];
   $this->documentMeta[] = [
      "property" => 'og:description', 
      'content' => 'Plataforma livre, gratuita e colaborativa de mapeamento'
   ];

   $this->printDocumentMeta();

O trecho acima resultará no HTML abaixo:

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1.0">
<meta property="og:title" content="Mapa da Cultura">
<meta property="og:description" content="Plataforma livre, gratuita e colaborativa de mapeamento">

`getTitle`

Gera 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'].

`bodyProperties`

Imprime as propriedades da tag <body >, baseado no que foi configurado nas propriedades $bodyProperties e $bodyClasses, como no exemplo a seguir:

   // $this é a instância do tema ativo
   $this->bodyProperties['ng-app'] = "entity.app";
   $this->bodyProperties['ng-controller'] = "EntityController";

   $this->bodyClasses[] = 'agent';
   $this->bodyClasses[] = 'single';
   ?>
   <body <?php $this->bodyProperties() ?> >

O trecho acima resultará no HTML abaixo:

<body ng-app="entity.app" ng-controller="EntityController" class="agent single">

`head`

Aplica o hook mapasculturais.head e invoca o método printDocumentMeta. Deve ser utilizado no final da tag <head>.

   <?php $this->head() ?>
</head>

`bodyBegin`

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

<body <?php $this->bodyProperties() ?> >
    <?php $this->bodyBegin() ?>

`bodyEnd`

Esta função deve ser invocada antes do fechamento da tag <body> e a única coisa que faz é aplicar o hook mapasculturais.body:after.

    <?php $this->bodyAfter() ?>
</body>

`isEditable`

Esta função indica se a aplicação está em uma página onde os campos devem ser editáveis (create ou edit).

<?php if ($this->isEditable()): ?>
   <button>save</button>
<?php endif; >

`printScripts`

Imprime a(s) tag(s) <script > dos scripts enfileirados do grupo informado.

$this->enqueueScript('meu-grupo', 'meu-script', 'js/meu-script.js');

$this->printScritps('meu-grupo');

O trecho acima resultará no HTML abaixo:

<script type="text/javascript" src="http://localhost/assets/js/meu-script-1629894851.js"></script>

`printStyles`

Imprime a(s) tag(s) <link rel="stylesheet" > dos scripts enfileirados do grupo informado.

$this->enqueueStyle('meu-grupo', 'meu-estilo', "css/meu-estilo.css");

$this->printStyles('meu-grupo');

O trecho acima resultará no HTML abaixo:

<link href="http://localhost/assets/css/meu-estilo-1629894851.css" media="all" rel="stylesheet" type="text/css">

Modais de Criação de Entidade (BaseV1)

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.

<div class="btn btn-default add"> 
   <?php $this->renderModalFor('agent', false, 'Novo agente'); ?> 
</div>

Resolução de Nome de Arquivo

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.

Assets

Enfileiramento de Scripts e Estilos

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.

AssetManager

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.

Funções includeAssets (BaseV1)

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.

jsObject

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:

$this->jsObject['meuArray'] = [1,2,3,4];
$this->jsObject['meuObjeto'] = [
   'id' => 13,
   'name' => 'Fulano de Tal'
];

No JavaScript chegará:

MapasCulturais.meuArray = [1,2,3,4];
MapasCulturais.meuObjeto = {"id": 13, "name": "Fulano de Tal"};

Funções addToJs (BaseV1)

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:

{ 
"id: 11, //id da entidade 
"ownerId": 11, // id do owner da entidade 
"ownerUserId": 5, // id do usuário proprietário pela entidade 
"definition": {}, // definição da entidade 
"userHasControl": true, // se o usuário autenticado tem controle sobre a entidade 
"canUserChangeOwner": false, // se o usuário autenticado pode mudar o proprietário da entidade 
"canUserCreateRelatedAgentsWithControl": true, // se o usuário autenticado pode definir administradores da entidade 
"status": 0, // status da entidade 
"object": {} // json_serialize da entidade 
}

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.

Localização

Para localizar os textos dos templates, utiliza-se as funções da classe MapasCulturais\i:

<?php use MapasCulturais\i; >
<p><?php i::_e("Um texto que pode ser traduzido")?></p>
<p><?php echo i::__("Outro texto que pode ser traduzido")?></p>

Já para localizar strings utilizadas por componentes JavaScript, utiliza-se o método localizeScript, da maneira demonstrada abaixo:

//$this é instância do tema ativo
$this->localizeScript('minhaFuncionalidade', [
               'correctErrors' => i::__('Corrija os erros indicados abaixo.'),
               'unexpectedError' => \MapasCulturais\i::__('Erro inesperado.'),
               'Erro'=> \MapasCulturais\i::__('Erro')
]);

O trecho acima criará a seguinte estrutura no JavaScript e dessa maneira os scripts do JavaScript podem utilizar os textos traduzidos:

MapasCulturais.gettext.minhaFuncionalidade = {
   "correctErrors": "Corrija os erros indicados abaixo.",
   "unexpectedError": "Erro inesperado.",
   'Erro': "Erro"
}

Herança - Estendendo um Tema

@todo

PreviousControladores NextFrontend dos Temas

Last updated 4 years ago

Was this helpful?