Frontend dos Temas

Sass

O Mapas Culturais utiliza o Sass (versão 3.4 em Ruby) como linguagem para escrita dos estilos.

Compilando o Sass

Há dois scripts que auxiliam no desenvolvimento. Um para compilar o CSS. E, o outro para observar os arquivos por modificações e para compilar o CSS sempre que algum arquivo seja alterado.

Ambos os scripts ficam na pasta scripts do repositório. Localizados dentro do container docker, essa pasta se encontra em /var/www/scripts.

• scripts/compile-sass.sh;
• scripts/watch-active-theme-sass.sh.

Quando dev-scripts/start-dev.sh é utilizado para o desenvolvimento, pode-se utilizar os scripts abaixo para chamar os scripts supracitados:

• dev-scripts/compile-sass.sh: executa o scripts/compile-sass.sh dentro do container;
• dev-scripts/watch-sass.sh: executa o scripts/watch-active-theme-sass.sh dentro do container.

Pastas e arquivos (BaseV1)

Os arquivos do Sass ficam na pasta assets/css/sass do tema BaseV1. Dentro da pasta há a seguinte estrutura:

• application: São estilos para componentes utilizados somente em componentes específicos da aplicação;
• components: São estilos para componentes que podem ser reutilizados em toda a aplicação;
• modules: São estilos básicos aplicados nos seletores dos elementos HTML e em classes auxiliares;
• vendor: São estilos que sobrescrevem os estilos dos componentes de terceiros;
• globals: São códigos Sass que são utilizados por todos os arquivos Sass, como funções e variáveis;
• main.scss: É o arquivo principal compilado, seu papel é somente incluir os arquivos das pastas acima, na ordem correta.

Customizando os estilos no tema filho

Os arquivos Sass dos temas filhos do BaseV1 devem ficar na pasta assets/css/sass. Comumente são utilizados apenas 3 arquivos .scss para a customização, como no exemplo do tema Sobral:

• _variables.scss: Utilizado para sobrescrever os valores das variáveis do tema BaseV1. Deve ser incluído antes da inclusão do scss do BaseV1;
• _overrides.scss: Utilizado para sobrescrever os estilos definidos pelo BaseV1, ou dos vendor. Deve ser incluído depois da inclusão do scss do BaseV1;
• main.scss: Arquivo principal compilado, tem como papel incluir os 2 arquivos acima além do scss do tema BaseV1, como no exemplo abaixo:

@import "variables"; 
/* caminho até o main.scss do BaseV1 */ 
@import "../../../../BaseV1/assets/css/sass/main"; 
@import "overrides";

JavaScript

MapasCulturais.auth.require

Requer autenticação antes de executar uma função enviada por parâmetro, abrindo a tela de login caso o usuário não estiver autenticado:

MapasCulturais.auth.require(function () {
   alert('alerta somente para usuários logados');
});

MapasCulturais.createUrl

Cria a URL para uma rota dado controller_id, action_name e parâmetros para URL, como nos exemplos abaixo:

MapasCulturais.createUrl('panel', 'index') // http://localhost/painel/
MapasCulturais.createUrl('agent', 'single', [1]) // http://localhost/agente/1
MapasCulturais.createUrl('agent', 'edita', [1]) // http://localhost/agentes/edita/1
MapasCulturais.createUrl('site', 'teste', {'chave': 'valor', 'outra-chave': 'outro-valor'}) // http://localhost/site/teste/chave:valor/outra-chave:outro-valor/

MapasCulturais.Messages

Exibe mensagens para o usuário (somente nas páginas das entidades):

MapasCulturais.Messages.alert('Mensagem de alerta');
MapasCulturais.Messages.error('Mensagem de erro');
MapasCulturais.Messages.success('Mensagem de sucesso');
MapasCulturais.Messages.help('Mensagem de ajuda');

MapasCulturais.Modal

Componente JS que implementa e inicializa as modais:

@todo: exemplo de html de uma modal

MapasCulturais.EditBox

Componente JS que implementa e inicializa as caixinhas de edição:

@todo: exemplo de html de uma editbox

MapasCulturais.Remove

Componente JS que implementa link para deleção de item (file, metalist e eventOccurrence). Após deleção, remove o item da lista:

<?php foreach($files as $file): ?>
   <li id="file-<?=$file->id ?>">
      <a href="<?=$file->url;?>"> <?=$file->name;?> </a>
      <a class="js-remove-item delete"
         data-href="<?php echo $download->deleteUrl?>" 
         data-target="#file-<?=$file->id ?>" 
         data-configm-message="Remover este arquivo?"> deletar </a>
   </li>
<?php endforeach; ?>

MapasCulturais.AjaxUploader

Implementa modal para upload de arquivos via Ajax.

MapasCulturais.Video

Implementa componente de vídeos das páginas das entidades.

MapasCulturais.Search

Implementa campo de busca de entidade, utilizado, por exemplo, na seleção do owner agent, do projeto dos eventos, do projeto e espaço pai, etc.

MapasCulturais.cookies

Implementa um getter e um setter para manipular cookies pelo JS.

MapasCulturais.Editables

Componente JS que inicializa os X-editables e implementa o salvamento das páginas de edição das entidades.

MapasCulturais.MetalistManager

Componente JS que implementa e inicializa os componentes de metalist (download e vídeos), das páginas de edição das entidades.

X-editable

O X-editable é uma biblioteca para edit in-place, ou seja, para criar elementos HTML editáveis. É a biblioteca utilizada nas páginas de edição das entidades. E, no Mapas Culturais, é implementada uma abstração em cima da biblioteca para facilitar sua utilização.

Campo de Texto Simples <input>

<span class="js-editable required" 
   data-edit="nomeCompleto" 
   data-original-title="Nome Completo" 
   data-emptytext="Informe seu nome completo">
      [Valor atual do campo ou metadado, ou vazio se não estiver preenchido]
</span>

Campo de Texto <textarea>

<!-- campo COM limite de caracteres e exibição dos botões -->
<span 
   class="js-editable required" 
   data-edit="shortDescription" 
   data-original-title="Descrição Curta" 
   data-emptytext="Insira uma descrição curta" 
   data-showButtons="bottom" 
   data-tpl='<textarea maxlength="400"></textarea>'>
   [Texto atual ou vazio]
</span>

<!-- campo SEM limite de caracteres e SEM exibição dos botões -->
<span class="js-editable" 
   data-edit="longDescription" 
   data-original-title="Descrição Longa" 
   data-emptytext="Insira uma descrição longa">
   [Texto atual ou vazio]
</span>

Campo de Seleção <select>

As opções do select são obtidas do registro do metadado:

<span class="js-editable" 
   data-edit="genero" 
   data-original-title="Gênero" 
   data-emptytext="Selecione o gênero">
      [Valor atual ou vazio]
</span>

Campo de Data datepicker

<span class="js-editable" 
   data-type="date" 
   data-value="2021-09-08" 
   data-edit="dataDeNascimento" 
   data-viewformat="dd/mm/yyyy" 
   data-showbuttons="false" 
   data-original-title="Data de Nascimento" 
   data-emptytext="Insira a data de nascimento">
   <!-- 
      O valor aqui é somente para apresentação quando a página não está em modo de edição e 
      é sobrescrito pelo valor do `data-value` formatato como configurado em `data-viewformat`
    -->
   08/09/2021 
</span>

AngularJS

Diretiva EditBox <edit-box>

<a ng-click="editbox.open('id-da-caixa', $event)" title="Abrir EditBox">abrir</a>

<edit-box 
   id="id-da-caixa" 
   position="right" 
   title="Título da caixa" 
   spinner-condition="data.processando"
   cancel-label="Fechar" 
   submit-label="Enviar"
   on-open="" 
   on-cancel="" 
   on-submit="" 
   close-on-cancel='true'>
   <h1>Conteúdo</h1>
</edit-box>

Diretiva mcSelect <mc-select>

@todo

Diretiva multiselect <multiselect>

@todo

Diretiva editableMultiselect <editable-multiselect>

<editable-multiselect 
   entity-property="acessibilidade_fisica" 
   empty-label="Selecione" 
   allow-other="true" 
   box-title="Acessibilidade física:">
</editable-multiselect>