Skip to content

Latest commit

 

History

History
320 lines (280 loc) · 26.9 KB

themes.md

File metadata and controls

320 lines (280 loc) · 26.9 KB
Raw

Customização do tema do Mapas Culturais

Este documento trata de uma customização simples do tema base do Mapas Culturais para novas instações, e se restringe a customização das cores, imagens, textos e configuração do posicionamento inicial dos mapas. Este é o nível de customização utilizado nos diversos temas do repositório, como por exemplo os temas de Blumenau (blumenaumaiscultura.com.br), Ceará (mapa.cultura.ce.gov.br), Sobral (cultura.sobral.ce.gov.br) e SaoJose (lugaresdacultura.org.br).

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.

Índice

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

Estílos

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-devs:    #CE5AA1 !default;

¹ Para saber com mais precisão onde uma variável é utilizada e, por consequência, o que será afetado e onde estarão os efetitos 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 substituida 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âmtro, 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, quaquer arquivo .php das pastas views e layouts pode ser substituido 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.

Configurações fixas do tema

Configurando os mapas

O primeiro passo para configurar¹ o mapas da busca e das páginas de criação de agentes e espaços, é conseguir os valores exatos da latitude, longitude e zoom.

A maneira mais simples de se fazer isto é através da própria página de busca, posicionando e definindo o zoom do mapa exatamente como ele deve se encontrar quando um usuário entrar na busca, e copiando os valores que aparecem na URL como no exemplo abaixo:

/busca/##(global:(enabled:(agent:!t),filterEntity:agent,map:(center:(lat:10.590252550882942,lng:-74.18719768524169),zoom:15)))
latitude:  10.590252550882942
longitude: -74.18719768524169
zoom:      15

Após obter os valores, defina no arquivo conf-base.php do tema filho os valores das chaves 'maps.center' e 'maps.zoom.default' com os valores obtidos.

    // latitude,longitude do centro do mapa da busca e do mapa da criação de agentes e espaços
    'maps.center' => [10.590252550882942, -74.18719768524169],

    // zoom padrão do mapa da busca
    'maps.zoom.default' => 15,

¹ Há mais opções de configurações dos mapas que não serão abordadas neste documento mas que estão comentadas com os valores padrão no arquivo conf-base.php do TemplateV1.

Divisões geográficas

As divisões geográficas configuradas devem ser as mesmas que foram importadas pelos shapefiles. No nosso exemplo usaremos somente zona e bairro.

    'app.geoDivisionsHierarchy' => [
        'zona'          => 'Zona',
        'bairro'        => 'Bairro'
    ],

Estrutura de arquivos do tema BaseV1