Skip to content

Latest commit

 

History

History
399 lines (344 loc) · 31.8 KB

mc_developer_theme.md

File metadata and controls

399 lines (344 loc) · 31.8 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 instalaçõ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.

Veja também como criar campos de informações adicionais no seu tema.

Índice

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. A estrutura completa está na seção Estrutura de arquivos do tema BaseV1.

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 do Desenvolvedor

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.

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'
    ],

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:

Estrutura de arquivos do tema BaseV1