# 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](/documentacao-para-desenvolvedores/formacao-para-desenvolvedores/backend-dos-temas.md), [Frontend dos Temas](/documentacao-para-desenvolvedores/formacao-para-desenvolvedores/frontend-dos-temas.md)e [Adicionando campos adicionais ao seu tema](/documentacao-para-desenvolvedores/livro-de-receitas/adicionando-campos-adicionais-ao-seu-tema.md).

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](/documentacao-para-desenvolvedores/apis/guia-de-hooks.md)

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mapasculturais.gitbook.io/documentacao-para-desenvolvedores/livro-de-receitas/criacao-de-um-tema.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.