Criação de um Tema

Este documento trata da criação e customização simples do tema base do Mapas Culturais para novas instalações, e se restringe a customização das cores, imagens, textos e configuração do posicionamento. Para aprofundamento, ver as páginas Backend dos Temas, Frontend dos Temase Adicionando campos adicionais ao seu tema.

Neste documento será feito um tema de exemplo para uma Secretaria Municipal de Cultura cuja sigla é SECONDO, de uma cidade fictícia chamada Macondo. O nome do site será Macondo Cultural.

Estrutura do Tema

O tema padrão que do mapas é o tema BaseV1, localizado na pasta src/protected/application/themes, e esse tema contém todos os templates, imagens, estilos e scripts que são usados para renderizar as páginas (Ex: Mapa, Painel, Home..).

É possível estender o tema criando uma pasta, de modo que todos os arquivos que forem adicionados no tema "filho" irão sobrescrever os arquivos originais do tema BaseV1, isso inclui os templates, imagens, estilos e scripts.

IMPORTANTE: É necessário tomar cuidado ao sobrescrever os arquivos, já que posteriormente os arquivos do tema BaseV1 podem ser alterados (incluindo uma nova funcionalidade, por exemplo) e isso não afetará o tema estendido.

Antes de decidir sobrescrever um arquivo, é indicado que verificar se não é possível efetuar a alteração desejada utilizando hooks, que pode ser consultado na documentação Guia de Hooks

Criando o tema

O primeiro passo é copiar o template de tema, disponível na pasta src/protected/application/themes/TemplateV1, para a pasta do novo tema: src/protected/application/themes/Macondo ¹.

Feito isto renomeie o namespace TemplateV1, na primeira linha do arquivo Theme.php, para o namespace do Tema (de preferência o mesmo nome da pasta)

<?php
namespace Macondo;
...

¹ A princípio o tema pode estar em qualquer pasta acessível pelo usuário que roda a aplicação, porém por limitações do SASS é necessário colocar hardcoded o caminho para o tema BaseV1. Por esta razão colocamos o tema dentro da pasta src/protected/application/themes/ e importamos os arquivos SASS do tema BaseV1 utilizando a linha abaixo:

@import "../../../../BaseV1/assets/css/sass/main";

Estilos

O tema BaseV1 do Mapas Culturais utiliza uma extensão da linguagem CSS chamada SASS, e é através desta que são feitas as personalizações dos estilos do tema.

A personalização das cores, fontes e estilos é feita de duas maneiras: definindo os valores das variáveis utilizadas nos diversos arquivos sass (.scss) e, nos casos em que a definição das variáveis não é suficiente, sobrescrevendo as classes/estilos CSS.

Definição das variáveis SASS

A definição de novos valores para as variáveis deve ser feita no arquivo assets/css/sass/_variables.scss do tema filho, e uma lista completa das variáveis, assim como seus valores padrão, pode ser encontrada no arquivo _variables.scss do tema BaseV1.

No exemplo abaixo são definidas as variáveis das cores principais² que são utilizadas em diversos lugares do tema¹.

$brand-primary: #5064A5 !default;
$brand-event:   #F7931D !default;
$brand-agent:   #5FB643 !default;
$brand-space:   #AB1F24 !default;
$brand-project: #795099 !default;
$brand-seal:    #795099 !default;
$brand-devs:    #CE5AA1 !default;

¹ Para saber com mais precisão aonde uma variável é utilizada e, por consequência, o que será afetado e aonde estarão os efeitos de uma modificação, a melhor maneira é fazer uma busca pelo nome da variável (por exemplo $brand-primary) dentro da pasta sass do tema BaseV1.

² Alterar as cores dos eventos, agentes e/ou espaços implica em recriar os arquivos dos pins (ver os arquivos de imagens que começam com pin- e agrupador-) utilizados nos mapas para estas entidades.

Sobrescrevendo estilos

Quando a modificação que se deseja fazer é mais complexa e não é possível de fazê-la com uma simples mudança de valor de uma variável, ou a propriedade que se quer alterar não é definida por uma variável, ou ainda se a alteração deve ser num caso muito específico, como exemplo o tamanho da caixinha de edição do nome de agentes, o caminho a ser adotado é sobrescrever a classe/estilo.

Este nível de personalização deve ser feito no arquivo assets/css/sass/_overrides.scss do tema filho.

No exemplo abaixo mudamos a altura da imagem de verificado para 100px;

.widget-verified {
    height: 100px;
}

Se for utilizar imagens nos estilos, como por exemplo imagens de fundo, ver a seção Utilizando imagens nos estilos.

Compilando os arquivos SASS

Durante o processo de desenvolvimento do tema, a melhor maneira de se compilar o sass é utilizando o comando sass --watch (ver documentação do sass) que este recompilará o .css sempre que houver modificações nos arquivos .css.

Entre pela linha de comando na pasta assets/css do tema filho e execute o seguinte comando:

sass --watch sass/main.scss:main.css

Imagens

Substituindo imagens

Qualquer imagem utilizada pelo tema BaseV1 pode ser substituída facilmente bastando, para isto, colocar uma imagem de mesmo nome na pasta assets/img do tema filho.

Por exemplo, para personalizar as imagens utilizadas como selo de que o conteúdo é verificado/oficial, basca colocar os arquivos com o brasão da instituição na pasta assets/img, obviamente respeitando os tamanhos e proporções (largura e altura).

assets/img/unverified-seal.png
assets/img/verified-icon.png
assets/img/verified-seal.png
assets/img/verified-seal-small.png

Utilizando imagens nos templates

Para utilizar uma nova imagem no tema filho, primeiro coloque o arquivo da imagem na pasta assets/img e em seguida chame o arquivo da seguinte forma no template, utilizando a função asset do tema:

<img src="<?php $this->asset('img/nome-da-imagem.png'); ?>" >

Utilizando imagens nos estilos

Para utilizar uma imagem nos estilos é necessário pedir para a aplicação publicar esta imagem antes de utilizá-la. Para tal basta chamar, no método _publishAssets do arquivo Theme.php do tema filho, a função asset do tema passando false como segundo parâmetro, que indicando que não é para imprimir a url do asset publicado.

Exemplos:

    protected function _publishAssets() {
        // somente publica o asset
        $this->asset('img/imagem-de-fundo.png', false);

        // publica e coloca a url do asset publicado no objeto MapasCulturais.assets para o js
        $this->jsObject['assets']['logo-instituicao'] = $this->asset('img/logo-instituicao.png', false);
    }

Substituindo partes dos templates

Da mesma forma como acontece com as imagens, qualquer arquivo .php das pastas views e layouts pode ser substituído facilmente, bastando para isto, que seja criado um arquivo com o mesmo nome no tema filho.

Os três arquivos mais comumente substituídos, e que já são incluídos no template de tema TemplateV1, são os seguintes:

layouts/parts/editable-entity-logo.php  // logo que aparece na barrinha cinza da edição de entidades
layouts/parts/header-about-nav.php      // menu da direita do header
layouts/parts/header-logo.php           // logo do site, a esquerda do header

Textos

Os textos utilizados na home e em alguns outros lugares do site, como nos textos das páginas "Sobre" e "Como Usar", são definidos no método _getTexts arquivo Theme.php. O template de tema TemplateV1 contém todos os textos configuráveis comentados com os valores padrão.

Abaixo configuramos alguns textos de acordo com nossa instalação fictícia:

            'site: name' => 'Macondo Cultural',
            'site: in the region' => 'na cidade de Macondo',
            'site: of the region' => 'da cidade de Macondo',
            'site: owner' => 'Secretaria Municipal de Cultura de Macondo',
            'site: by the site owner' => 'pela Secretaria Municipal de Cultura de Macondo',

            'home: abbreviation' => "SECONDO",
            'home: colabore' => "Colabore com o Macondo Cultural",

            'search: verified results' => 'Resultados da SECONDO',
            'search: verified' => "SECONDO"

Páginas "Sobre" e "Como Usar"

Os textos das páginas Sobre e Como Usar são pensados para serem genéricos e utilizam dos textos definidos acima.

Caso os textos fornecidos pelo tema BaseV1 não supra as necessidades, basta criar os arquivos na pasta pages do tema filho e escrever, utilizando as linguagens Markdown ou HTML para formatação, os novos textos.

Criando um repositório do tema no Github

É recomendado que ao criar o tema ou efetuar alterações no tema, as alterações estejam em um repositório git para posteriormente seja possível clonar o tema de qualquer lugar, seja para utilizar em um servidor em produção ou para utilizar um ambiente de desenvolvimento.

Criando o repositório

Para criar o repositório é necessário seguir os seguintes passos: - Criar uma conta no Github - No menu superior direito apertar a opção New Repository - Preencher a caixa de texto Repository name com o nome do repositório (recomendável utilizar o mesmo nome escolhido na pasta do tema, para que ao clonar o repositório o nome fique correto) - Apertar o botão Create repository - Executar os seguintes comandos após criar o repositório (alterando Macondo para o nome do seu repositório/tema):

$ echo "# Macondo" >> README.md
$ git init
$ git add --all
$ git commit -m "first commit"
$ git remote add origin https://github.com/[endereco_github]/Macondo.git
$ git push -u origin master

Publicando alterações

Dentro da pasta do tema, se alguma alteração for feita em qualquer arquivo será possível ver os arquivos que foram alterados utilizando o comando git status, mostrando os arquivos modificados. Ao alterar arquivos o resultado deve ser parecido com isso:

On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   Theme.php
    modified:   conf-base.php

no changes added to commit (use "git add" and/or "git commit -a")

Neste exemplo, houveram alterações nos arquivos Theme.php e no arquivo conf-base.php. Para publicar esse arquivos é necessário utilizar os comandos - git add [nome_do_arquivo] - git commit -m "[mensagem_com_descricao_da_alteracao]" - git push

Como no exemplo, para publicar os arquivos Theme.php e conf-base.php os comando seriam assim:

$git add Theme.php
$git add conf-base.php
$git commit -m "Alterações de configurações do Tema"
$git push

Clonando e atualizando a partir do repositório

Após as alterações estarem publicadas em um repositório do Github, podemos obter o código publicado com o comando git clone https://github.com/[endereco_github]/Macondo, isso irá criar uma pasta chamada Macondo onde o comando foi executado. Preferencialmente executado da pasta themes da instalação do mapas:

$ cd src/protected/application/themes
$ git clone https://github.com/[endereco_github]/Macondo

Se alguma alteração for efetuada no repositório do Github e for necessário atualizar o tema localmente, pode se utilizar o comando git pull para atualizar o código localmente.

IMPORTANTE: Ao utilizar o comando git pull verificar se não existem arquivos locais que foram alterados e podem ser sobrescritar ou gerar algum conflito.

Para mais detalhes sobre como utilizar o git, é recomendável a leitura da documentação e artigos úteis: - https://git-scm.com/book/pt-br/v1/Primeiros-passos-No%C3%A7%C3%B5es-B%C3%A1sicas-de-Git - http://rogerdudler.github.io/git-guide/index.pt_BR.html