site_tools/docs/share-links.md

# Share Links Block

O módulo Site Tools fornece um bloco de compartilhamento (`Share Links`) que exibe links para compartilhar o conteúdo atual em redes sociais ou outros canais.

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

## Instalação

1. Copie o módulo para `modules/custom/site_tools`
2. Ative o módulo: `drush en site_tools`
3. Posicione o bloco "Share Links" na região desejada em `/admin/structure/block`

## Fornecendo Links de Compartilhamento

Para adicionar links ao bloco, implemente `hook_site_tools_share_links()` no seu módulo.

### Estrutura do Hook

```php
/**
 * Implements hook_site_tools_share_links().
 */
function meu_modulo_site_tools_share_links(): array {
  $links = [];

  // Cada link é identificado por uma chave única.
  $links['minha_rede'] = [
    // Obrigatório: render array ou markup HTML.
    'content' => [
      '#type' => 'link',
      '#title' => t('Compartilhar'),
      '#url' => \Drupal\Core\Url::fromUri('https://exemplo.com/share'),
    ],
    // Opcional: peso para ordenação (menor = aparece primeiro).
    'weight' => 0,
    // Opcional: identificação do módulo provedor.
    'provider' => 'meu_modulo',
  ];

  return $links;
}
```

### Exemplo: Link de Email

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

  // Obtém o título da página atual.
  $title = \Drupal::service('title_resolver')->getTitle(
    $request,
    \Drupal::routeMatch()->getRouteObject()
  );

  return [
    'email' => [
      'content' => [
        '#type' => 'link',
        '#title' => t('Email'),
        '#url' => \Drupal\Core\Url::fromUri('mailto:', [
          'query' => [
            'subject' => $title,
            'body' => t('Confira este conteúdo: @url', ['@url' => $current_url]),
          ],
        ]),
        '#attributes' => [
          'class' => ['share-link', 'share-link--email'],
          'title' => t('Compartilhar por email'),
        ],
      ],
      'weight' => 100,
      'provider' => 'meu_modulo',
    ],
  ];
}
```

### Exemplo: Integração com AddToAny

```php
/**
 * Implements hook_site_tools_share_links().
 */
function meu_modulo_site_tools_share_links(): array {
  // Verifica se o módulo AddToAny está disponível.
  if (!\Drupal::moduleHandler()->moduleExists('addtoany')) {
    return [];
  }

  // Renderiza o bloco do AddToAny.
  $block_manager = \Drupal::service('plugin.manager.block');
  $plugin_block = $block_manager->createInstance('addtoany_block', []);
  $render = $plugin_block->build();

  return [
    'addtoany' => [
      'content' => $render,
      'weight' => 0,
      'provider' => 'addtoany',
    ],
  ];
}
```

### Exemplo: Links Manuais para Redes Sociais

```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);

  $title = \Drupal::service('title_resolver')->getTitle(
    \Drupal::request(),
    \Drupal::routeMatch()->getRouteObject()
  );
  $encoded_title = urlencode($title ?? '');

  return [
    'facebook' => [
      'content' => [
        '#type' => 'link',
        '#title' => t('Facebook'),
        '#url' => \Drupal\Core\Url::fromUri(
          "https://www.facebook.com/sharer/sharer.php?u={$encoded_url}"
        ),
        '#attributes' => [
          'class' => ['share-link', 'share-link--facebook'],
          'target' => '_blank',
          'rel' => 'noopener',
        ],
      ],
      'weight' => 0,
    ],
    'twitter' => [
      'content' => [
        '#type' => 'link',
        '#title' => t('X (Twitter)'),
        '#url' => \Drupal\Core\Url::fromUri(
          "https://twitter.com/intent/tweet?url={$encoded_url}&text={$encoded_title}"
        ),
        '#attributes' => [
          'class' => ['share-link', 'share-link--twitter'],
          'target' => '_blank',
          'rel' => 'noopener',
        ],
      ],
      'weight' => 1,
    ],
    'whatsapp' => [
      'content' => [
        '#type' => 'link',
        '#title' => t('WhatsApp'),
        '#url' => \Drupal\Core\Url::fromUri(
          "https://api.whatsapp.com/send?text={$encoded_title}%20{$encoded_url}"
        ),
        '#attributes' => [
          'class' => ['share-link', 'share-link--whatsapp'],
          'target' => '_blank',
          'rel' => 'noopener',
        ],
      ],
      'weight' => 2,
    ],
  ];
}
```

## Alterando Links de Outros Módulos

Use `hook_site_tools_share_links_alter()` para modificar ou remover links fornecidos por outros módulos.

```php
/**
 * Implements hook_site_tools_share_links_alter().
 */
function meu_modulo_site_tools_share_links_alter(array &$links): void {
  // Remove um link específico.
  unset($links['twitter']);

  // Altera o peso de um link.
  if (isset($links['facebook'])) {
    $links['facebook']['weight'] = -10;
  }

  // Modifica atributos de um link.
  if (isset($links['email']['content']['#attributes'])) {
    $links['email']['content']['#attributes']['class'][] = 'minha-classe';
  }
}
```

## Personalizando o Template

O bloco usa o template `site-tools-share-links.html.twig`. Para sobrescrevê-lo no seu tema:

1. Copie `templates/site-tools-share-links.html.twig` para o diretório `templates/` do seu tema
2. Limpe o cache: `drush cr`

### Variáveis Disponíveis

| Variável | Descrição |
|----------|-----------|
| `links` | Array de links de compartilhamento |
| `links[key].content` | Render array do link |
| `links[key].weight` | Peso para ordenação |
| `links[key].provider` | Módulo que forneceu o link |
| `attributes` | Atributos HTML do container |

### Exemplo de Template Customizado

```twig
{% if links %}
<div{{ attributes.addClass('share-bar') }}>
  <span class="share-bar__title">{{ 'Compartilhe:'|t }}</span>
  <ul class="share-bar__list">
    {% for key, link in links %}
      <li class="share-bar__item share-bar__item--{{ key }}">
        {{ link.content }}
      </li>
    {% endfor %}
  </ul>
</div>
{% endif %}
```

## CSS

O módulo inclui estilos básicos em `css/share-links.css`. As classes disponíveis são:

| Classe | Elemento |
|--------|----------|
| `.site-tools-share-links` | Container principal |
| `.site-tools-share-links__label` | Label "Share:" |
| `.site-tools-share-links__items` | Container dos links |
| `.site-tools-share-links__item` | Wrapper de cada link |
| `.site-tools-share-links__item--{key}` | Modificador por tipo de link |

## Cache

O bloco possui cache que varia por URL (`url.path`). Se você precisar invalidar o cache programaticamente:

```php
\Drupal\Core\Cache\Cache::invalidateTags(['site_tools_share_links']);
```

## Referência da API

Consulte `site_tools.api.php` para documentação completa dos hooks.