site_tools/README.md

# Site Tools

Módulo Drupal com ferramentas utilitárias reutilizáveis para outros módulos do site.

## Funcionalidades

- **Menu de configuração "Local Modules"**: Fornece uma seção centralizada em `/admin/config/local-modules` para configurações de módulos desenvolvidos internamente.
- **Bloco Share Links**: Bloco de compartilhamento em redes sociais extensível via hooks.
- **Condição de visibilidade "Usuário da página é o usuário logado"**: Restringe a exibição de qualquer bloco à situação em que o usuário autenticado é o mesmo da rota `/user/{id}`.
- **Extensão Twig `site_tools_academic_icon`**: Função Twig para renderizar ícones SVG de plataformas acadêmicas (Lattes, ORCID, MathSciNet).

## Sub-módulos

- **site_tools_group_helpers**: Plugin `EntityReferenceSelection` que restringe campos de referência a grupos aos grupos dos quais o usuário atual é membro, com troca automática para o widget `options_select`. Requer o módulo contrib `group`.
- **site_tools_msc_2020**: Widget de seleção em cascata (1–3 níveis) para o vocabulário MSC 2020, com carregamento eficiente dos 597 termos via `loadTree()` + consulta direta ao banco.
- **site_tools_msc_2020_migrate**: Migrations para importação do vocabulário MSC 2020 a partir de CSV.

## Requisitos

- Drupal 10.3+ ou 11

## Instalação

1. Coloque o módulo no diretório `modules/custom/`
2. Ative o módulo via Drush: `drush en site_tools`
3. Limpe o cache: `drush cr`

## Uso

Outros módulos podem usar a seção "Local Modules" adicionando em seus arquivos `.links.menu.yml`:

```yaml
meu_modulo.settings:
  title: 'Meu Módulo'
  description: 'Configurações do meu módulo'
  route_name: meu_modulo.settings
  parent: site_tools.admin_config
  weight: 10
```

E declarando a dependência em `.info.yml`:

```yaml
dependencies:
  - site_tools
```

## Bloco Share Links

O bloco **Share Links** funciona como um container que coleta e exibe links de compartilhamento fornecidos por outros módulos através de hooks.

### Configuração

1. Acesse `/admin/structure/block`
2. Posicione o bloco "Share Links" na região desejada

### Fornecendo Links

Implemente `hook_site_tools_share_links()` no seu módulo:

```php
/**
 * Implements hook_site_tools_share_links().
 */
function meu_modulo_site_tools_share_links(): array {
  $current_url = \Drupal::request()->getUri();
  $encoded_url = urlencode($current_url);

  return [
    'facebook' => [
      'content' => [
        '#type' => 'link',
        '#title' => t('Facebook'),
        '#url' => \Drupal\Core\Url::fromUri(
          "https://www.facebook.com/sharer/sharer.php?u={$encoded_url}"
        ),
        '#attributes' => [
          'target' => '_blank',
          'rel' => 'noopener',
        ],
      ],
      'weight' => 0,
      'provider' => 'meu_modulo',
    ],
  ];
}
```

### Alterando Links

Use `hook_site_tools_share_links_alter()` para modificar ou remover links:

```php
/**
 * Implements hook_site_tools_share_links_alter().
 */
function meu_modulo_site_tools_share_links_alter(array &$links): void {
  unset($links['twitter']);
}
```

### Documentação Completa

Consulte [docs/share-links.md](docs/share-links.md) para documentação detalhada incluindo:
- Exemplos de integração com AddToAny
- Personalização do template Twig
- Classes CSS disponíveis
- Gerenciamento de cache

## Condição de visibilidade: Usuário da página é o usuário logado

O plugin `PageUserIsCurrentUser` adiciona uma condição de visibilidade reutilizável a qualquer bloco do site.

### Configuração

1. Acesse `/admin/structure/block` e edite o bloco desejado
2. Na aba **Visibilidade**, localize a seção **"Usuário da página é o usuário logado"**
3. Marque **"Exibir apenas para o dono da página"** e salve

Quando ativada, o bloco só é exibido se o usuário autenticado tiver o mesmo ID que o parâmetro `{id}` da rota `/user/{id}`. A opção **"Negar a condição"** inverte o comportamento (exibe para todos exceto o dono).

## Extensão Twig: ícones de plataformas acadêmicas

A função `site_tools_academic_icon(name)` retorna o SVG inline do ícone solicitado como marcação segura (sem necessidade de `|raw`).

### Ícones disponíveis

| Nome | Plataforma | Cor |
|------|------------|-----|
| `home` | Página pessoal | sem fill (definir via CSS) |
| `lattes` | Plataforma Lattes (CNPq) | `#005195` |
| `orcid` | ORCID | `#a6ce39` |
| `mathscinet` | MathSciNet (AMS) | `#0f4f96` |

### Uso em templates Twig

```twig
{{ site_tools_academic_icon('lattes') }}
{{ site_tools_academic_icon('orcid') }}
{{ site_tools_academic_icon('mathscinet') }}
```

O SVG já inclui `aria-hidden="true"` e `focusable="false"`. Para acessibilidade, envolva o ícone em um `<a>` com `aria-label`:

```twig
<a href="https://lattes.cnpq.br/{{ lattes_id }}"
   target="_blank" rel="noopener noreferrer"
   aria-label="{{ 'Currículo Lattes'|t }}">
  {{ site_tools_academic_icon('lattes') }}
</a>
```

## Sub-módulo: site_tools_msc_2020

Widget de campo (`FieldWidget`) para seleção hierárquica de termos do vocabulário **MSC 2020** (Mathematics Subject Classification), com até 3 níveis em cascata via AJAX.

### Configuração

1. Ative o sub-módulo: `drush en site_tools_msc_2020`
2. No formulário de exibição do campo (`/admin/structure/types/manage/.../form-display`), selecione o widget **"MSC 2020 — Seleção em cascata"**
3. Configure o **Nível máximo** (1, 2 ou 3) nas opções do widget

### Níveis

| Nível | Código | Exemplo |
|-------|--------|---------|
| 1 | 2 dígitos | `03` |
| 2 | 3 caracteres | `03B` |
| 3 | 5 caracteres | `03B05` |

O valor armazenado é sempre o TID do nível mais profundo selecionado. Selecionar "— área geral —" em um nível armazena o TID do nível imediatamente superior.

## Sub-módulo: site_tools_msc_2020_migrate

Migrations para importação do vocabulário MSC 2020 a partir de arquivos CSV.

### Uso

```bash
drush en site_tools_msc_2020_migrate
drush migrate:import --group=msc_2020
```