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


---

# 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/formacao-para-desenvolvedores/frontend-dos-temas.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.