# Frontend dos Temas

{% embed url="<https://www.youtube.com/watch?v=MJ8s0s_jOzE&feature=emb_imp_woyt>" %}

## Sass

O Mapas Culturais utiliza o [Sass](https://sass-lang.com/) (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.&#x20;

Ambos os scripts ficam na pasta [scripts](https://github.com/mapasculturais/mapasculturais/tree/master/scripts) do repositório. Localizados dentro do container docker, essa pasta se encontra em `/var/www/scripts`.

* [scripts/compile-sass.sh](https://github.com/mapasculturais/mapasculturais/blob/master/scripts/compile-sass.sh);
* [scripts/watch-active-theme-sass.sh](https://github.com/mapasculturais/mapasculturais/blob/master/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](https://github.com/mapasculturais/mapasculturais/blob/master/dev-scripts/compile-sass.sh): executa o `scripts/compile-sass.sh` dentro do container;
* [dev-scripts/watch-sass.sh](https://github.com/mapasculturais/mapasculturais/blob/master/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](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/BaseV1/assets/css/sass) do tema ***BaseV1***. Dentro da pasta há a seguinte estrutura:

* [application](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/BaseV1/assets/css/sass/application):  São estilos para componentes utilizados somente em componentes específicos da aplicação;
* [components](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/BaseV1/assets/css/sass/components): São estilos para componentes que podem ser reutilizados em toda a aplicação;
* [modules](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/BaseV1/assets/css/sass/modules): São estilos básicos aplicados nos seletores dos elementos HTML e em classes auxiliares;
* [vendor](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/BaseV1/assets/css/sass/vendor): São estilos que sobrescrevem os estilos dos componentes de terceiros;
* [globals](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/BaseV1/assets/css/sass/globals): São códigos Sass que são utilizados por todos os arquivos Sass, como funções e variáveis;
* [main.scss](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/BaseV1/assets/css/sass/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](https://github.com/mapasculturais/mapasculturais/tree/master/src/protected/application/themes/Sobral/assets/css/sass):

* [\_variables.scss](https://github.com/mapasculturais/mapasculturais/blob/master/src/protected/application/themes/Sobral/assets/css/sass/_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](https://github.com/mapasculturais/mapasculturais/blob/master/src/protected/application/themes/Sobral/assets/css/sass/_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](https://github.com/mapasculturais/mapasculturais/blob/master/src/protected/application/themes/Sobral/assets/css/sass/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:

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

```javascript
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):

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

```markup
@todo: exemplo de html de uma modal
```

### `MapasCulturais.EditBox`

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

```markup
@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
<?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](https://vitalets.github.io/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>`

```markup
<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>`

```markup
<!-- 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:

```markup
<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`

```markup
<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>`

```markup
<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>`

```markup
@todo
```

### Diretiva multiselect `<multiselect>`

```
@todo
```

### Diretiva editableMultiselect `<editable-multiselect>`

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