# 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](https://mapasculturais.gitbook.io/documentacao-para-desenvolvedores/formacao-para-desenvolvedores/backend-dos-temas "mention"), [frontend-dos-temas](https://mapasculturais.gitbook.io/documentacao-para-desenvolvedores/formacao-para-desenvolvedores/frontend-dos-temas "mention")e [adicionando-campos-adicionais-ao-seu-tema](https://mapasculturais.gitbook.io/documentacao-para-desenvolvedores/livro-de-receitas/adicionando-campos-adicionais-ao-seu-tema "mention").

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 <a href="#estrutura-do-tema" id="estrutura-do-tema"></a>

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.&#x20;

> **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](https://mapasculturais.gitbook.io/documentacao-para-desenvolvedores/apis/guia-de-hooks "mention")

## Criando o tema <a href="#criando-o-tema" id="criando-o-tema"></a>

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
<?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](http://stackoverflow.com/questions/5589067/sass-set-variable-at-compile-time) é 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:

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

### Estilos <a href="#estilos" id="estilos"></a>

O tema *BaseV1* do Mapas Culturais utiliza uma *extensão da linguagem CSS* chamada [SASS](http://sass-lang.com/), 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¹.

```scss
$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;

```scss
.widget-verified {
    height: 100px;
}
```

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

#### **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](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#using_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:

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

### Imagens <a href="#imagens" id="imagens"></a>

#### **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:

```php
<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:

```php
    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 <a href="#substituindo-partes-dos-templates" id="substituindo-partes-dos-templates"></a>

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 <a href="#textos" id="textos"></a>

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:

```php
            '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" <a href="#paginas-sobre-e-como-usar" id="paginas-sobre-e-como-usar"></a>

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 <a href="#criando-um-repositorio-do-tema-no-github" id="criando-um-repositorio-do-tema-no-github"></a>

É 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 <a href="#criando-o-repositorio" id="criando-o-repositorio"></a>

Para criar o repositório é necessário seguir os seguintes passos: - Criar uma conta no [Github](http://docs.mapasculturais.org/github.com) - 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 <a href="#publicando-alteracoes" id="publicando-alteracoes"></a>

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 <a href="#clonando-e-atualizando-a-partir-do-repositorio" id="clonando-e-atualizando-a-partir-do-repositorio"></a>

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