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.
head;
printDocumentMeta
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
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
, actionindex
), 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
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
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
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
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
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
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
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 chaveentity
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 chaveentityTypes
com a lista de tipos da entidade passada como parâmetro;addOccurrenceFrequenciesToJs
: Cria a chavefrequencies
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 chavetaxonomyTerms
;addRelatedAgentsToJs
: Adiciona a lista de agentes relacionados à chaveagentRelations
dentro da chaveentity
;addRelatedAdminAgentsToJs
: Adiciona a lista dos agentes relacionados com controle sobre a entidade à chaveagentAdminRelations
dentro da chaveentity
;addSubsiteAdminsToJs
: Adiciona os administradores e super administradores às chavesadmins
esuperAdmins
dentro da chaveentity
.
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
Last updated
Was this helpful?