Navegação das docs

SDD

Human Request: Links Dinâmicos em Galerias, Controles de Exibição e Correções de Layout (req-024)

Esta especificação define o lote de trabalho req-024 (BATCH-026) para o Engenheiro Executor. O escopo abrange a implementação de links configuráveis nas imagens de galerias…

Esta especificação define o lote de trabalho req-024 (BATCH-026) para o Engenheiro Executor. O escopo abrange a implementação de links configuráveis nas imagens de galerias, controles dinâmicos de altura e margem nas galerias, e correções de layout e espaçamento nos módulos de Destaques, Menus e Galerias.

1. Contexto e Requisitos

1.1 Links Personalizados por Imagem em Galerias

No módulo de Galerias (galleries), cada imagem curada na lista exibe apenas o thumbnail, nome do arquivo e campo de legenda. É necessário tornar as imagens clicáveis individualmente na galeria renderizada.

Cada item da curadoria de imagens passará a aceitar a configuração opcional de um link, com os seguintes tipos de destino:
1. Página: Seleção de uma página interna do site (gera o link canônico correspondente).
2. Link Customizado: Inserção manual de URL e seleção do alvo (_self ou _blank).
3. Link com Classe CSS: Inserção manual de URL e classe CSS customizada.
4. Última Publicação (Publicador): Seleção de um Publicador de Destaques ativo; no carregamento do site, o link resolverá dinamicamente para a URL da publicação mais recente desse publicador (com ordenação selecionável).
Na interface do painel, cada linha de imagem na lista terá um painel retrátil "Configurar Link" contendo os dropdowns e inputs necessários, os quais aparecerão de acordo com o tipo de link selecionado.
Os templates de galeria serão atualizados para dar suporte às novas variáveis: [[item#link-url]], [[item#link-target]] e [[item#link-css-classes]].

1.2 Controles de Exibição de Galerias (Altura e Margem Lateral)

Para melhorar a adequação visual das galerias nas páginas:

Inclusão de dois novos campos numéricos na aba "Controles de Exibição" no painel de Galerias:
1. Altura do Container: Altura vertical em pixels. Padrão: 300.
2. Margem Lateral: Distância em pixels nas laterais esquerda e direita da galeria. Padrão: 0 (encostado).
Os templates visuais de galerias (carrossel, slider, grid) devem ser atualizados para aplicar dinamicamente esses valores no estilo dos elementos (imagens e seções raiz), utilizando as variáveis globais de controle [[height]] e [[margin_lateral]].

1.3 Correção de Mapeamento no Destaques (`linked-fields-list`)

No mapeamento de variáveis do módulo de Destaques (publisher-highlights), as tags de variáveis vinculadas no container #linked-fields-list estão coladas horizontalmente. É necessário espaçá-las adicionando margens horizontais.

1.4 Correção do Menu Horizontal (`menus-horizontal-navbar`)

No template menus-horizontal-navbar (tanto em pt-br quanto en), os submenus (nível 2 e subsequentes) estão sem recuo horizontal (padding) interno, fazendo com que o texto dos links encoste na borda esquerda da caixa flutuante. É necessário aplicar o margeamento/padding adequado via CSS nos links internos das camadas inferiores do dropdown.

1.5 Correção do Layout de Alvenaria (`galleries-masonry`)

No template galleries-masonry (tanto em pt-br quanto en), a legenda das imagens está muito próxima das bordas esquerda e inferior. É necessário aumentar esse espaçamento aplicando margeamento ou padding.

2. Especificações de Alteração de Código

2.1 Módulo de Galerias: Painel Administrativo

[MODIFY] galleries.js

Estrutura dos itens de imagem: Atualize o contrato dos itens curados para suportar as propriedades de link:
- link_type (padrão: 'nenhum'), link_page_id, link_url, link_target (padrão: '_self'), link_css_classes, link_publisher_id, link_order_by (padrão: 'date_desc').
Interface do Item (buildItemRow):
- Adicione o botão toggle retrátil com ícone linkify e o texto "Definir Link" (ou similar).
- Adicione a div oculta .gallery-item-link-fields contendo:
  - Dropdown do tipo de link: Nenhum, Página, Link Customizado, Link com Classe CSS, Última Publicação.
  - Dropdown de Página: populado com as opções vindas da variável global galleries_pages.
  - Input de URL (para custom e class link).
  - Dropdown de Alvo (_self, _blank).
  - Input de Classe CSS.
  - Dropdown de Publicador: populado com as opções vindas da variável global galleries_publishers.
  - Dropdown de Ordenação do Publicador (date_desc, date_asc, etc.).
- Vincule eventos de alteração (change, input) a esses inputs para salvar o estado correspondente no objeto items[idx] e chamar serializeAndPreview().
- Vincule o clique do botão toggle para alternar (slideToggle / toggle) a visibilidade da div de configurações de link.
Controles de Exibição globais:
- Atualize currentSchemaOut() e hydrateGalleryControls() para ler/salvar os campos #gallery-height (padrão 300) e #gallery-margin-lateral (padrão 0).
- Adicione o listener de eventos de digitação (input change) para #gallery-height e #gallery-margin-lateral chamando serializeAndPreview().

[MODIFY] galleries.php

Carregamento de Listas Globais: Em galleries_adicionar() e galleries_editar(), busque todos os registros ativos de páginas e publicadores de destaques no idioma corrente, e os exporte para o frontend injetando a tag de script com as variáveis globais JSON:

$publishers = banco_select_name(
   banco_campos_virgulas(Array('name', 'id')),
   'publishers',
   "WHERE status='A' AND language='".$_GESTOR['linguagem-codigo']."' ORDER BY name ASC"
) ?: [];
$pages = banco_select_name(
   banco_campos_virgulas(Array('name', 'id')),
   'pages',
   "WHERE status='A' AND language='".$_GESTOR['linguagem-codigo']."' ORDER BY name ASC"
) ?: [];
$_GESTOR['pagina'] .= '<script>'
   . 'var galleries_publishers = ' . json_encode($publishers) . ';'
   . 'var galleries_pages = ' . json_encode($pages) . ';'
   . '</script>';

Variáveis de Template: Registre as novas variáveis globais e de item na função galleries_variaveis_template() para alimentar o html-editor:
- Globais: height, margin_lateral.
- De item: link-url, link-target, link-css-classes.

[MODIFY] Páginas HTML do Painel de Galerias:

Injetar os inputs de altura e margem na aba de Controles de Exibição, logo abaixo dos checkboxes em:

[MODIFY] galleries.widget.php

Resolução de Páginas em Lote: Colete todos os link_page_id dos itens da galeria e monte uma única query para recuperar o slug/caminho canônico dessas páginas (assim como feito no Menus), populando um mapa.
Resolução Dinâmica do Link de Publicador: Adicione uma função auxiliar para consultar a publicação mais recente de um publicador dado o publisher_id e a ordenação (order_by), retornando seu caminho de URL.
Mapeamento de Variáveis de Item (galleries_widget_resolver_item_vars):
- Retorne link-url, link-target e link-css-classes.
- Se o link_type for 'nenhum', retorne 'javascript:void(0);' para o link-url.
- Se o link_type for 'pagina', retorne a URL correspondente recuperada do mapa.
- Se o link_type for 'publicador', execute a consulta da publicação mais recente.
- Se o link_type for 'link-custom' ou 'link-action', retorne a URL manual do schema.
Resolução de Globais (galleries_widget_resolver_globais): Resolva height e margin_lateral a partir do schema (com fallbacks para 300 e 0 respectively).

2.3 Ajustes nos Templates de Galerias

Atualize os arquivos de templates (tanto em pt-br quanto en) para aplicar a margem e a altura:

Margem Lateral: Adicione o estilo inline no elemento raiz <section> de todos os templates: style="margin-left: @[[margin_lateral]]@px; margin-right: @[[margin_lateral]]@px;"
Altura do Container:
- Slider (pt-br e en): Aplique o estilo style="height: @[[height]]@px;" no elemento da imagem (img) e no container do slide (figure.gallery-slide).
- Carousel (pt-br e en): Remova a classe de altura fixa da imagem (h-56) e aplique o estilo inline style="height: @[[height]]@px;" no elemento da imagem (img).
- Grid (pt-br e en): Remova a classe de altura fixa da imagem (h-48) e aplique o estilo inline style="height: @[[height]]@px;" no elemento da imagem (img).
Espaçamento da Legenda no Masonry (pt-br e en):
- Altere a tag figcaption de class="text-sm text-gray-600 mt-1 px-1" para class="text-sm text-gray-600 mt-2 px-3 pb-2".

2.4 Ajustes de Outros Módulos e Layouts

[MODIFY] publisher-highlights.js

Espaçamento do Mapeamento de Variáveis: Na função renderLinkedVars(), altere a linha 359:
- De: var $row = $('<div class="ui label" style="margin:2px 0;display:inline-block;"></div>')
- Para: var $row = $('<div class="ui label" style="margin:2px 4px;display:inline-block;"></div>')

[MODIFY] Templates de `menus-horizontal-navbar` (pt-br e en)

Adicione um bloco <style> contido na tag raiz <section> para formatar e adicionar padding interno nos links dos submenus recursivos:

    <style>
        /* Adiciona padding interno e organiza layout de blocos nas subpastas do navbar */
        [data-title="menu-horizontal-navbar"] ul.absolute a {
            display: block !important;
            padding: 0.5rem 1rem !important; /* px-4 py-2 */
            font-size: 0.875rem !important; /* text-sm */
        }
        [data-title="menu-horizontal-navbar"] ul.absolute a:hover {
            background-color: #f3f4f6 !important; /* hover:bg-gray-100 */
        }
    </style>

3. Verificação

Para validar a implementação:

Mapeamento de Variáveis Destaques: Acesse o painel de Destaques e vincule variáveis. Verifique se as tags não aparecem mais coladas horizontalmente.
Submenus no Menu Horizontal: No preview do painel ou página publicada, abra o submenu de um menu horizontal e certifique-se de que os itens filhos têm recuo horizontal (padding) e a área de hover funciona perfeitamente.
Links e Controles nas Galerias:
- Crie uma galeria e configure diferentes tipos de links (página, custom com blank, e publicador). No preview, confirme se os links são gerados no HTML das imagens.
- Altere a altura da galeria para 450 e a margem lateral para 20. Certifique-se de que a galeria reflete as dimensões no preview instantaneamente.
- No template Masonry, certifique-se de que a legenda não fica mais colada na esquerda e na parte inferior do card.

# Human Request: Links Dinâmicos em Galerias, Controles de Exibição e Correções de Layout (req-024)
Esta especificação define o lote de trabalho `req-024` (BATCH-026) para o Engenheiro Executor. O escopo abrange a implementação de links configuráveis nas imagens de galerias, controles dinâmicos de altura e margem nas galerias, e correções de layout e espaçamento nos módulos de Destaques, Menus e Galerias.
---
## 1. Contexto e Requisitos
### 1.1 Links Personalizados por Imagem em Galerias
No módulo de Galerias (`galleries`), cada imagem curada na lista exibe apenas o thumbnail, nome do arquivo e campo de legenda. É necessário tornar as imagens clicáveis individualmente na galeria renderizada.
* Cada item da curadoria de imagens passará a aceitar a configuração opcional de um link, com os seguintes tipos de destino:
  1. **Página:** Seleção de uma página interna do site (gera o link canônico correspondente).
  2. **Link Customizado:** Inserção manual de URL e seleção do alvo (`_self` ou `_blank`).
  3. **Link com Classe CSS:** Inserção manual de URL e classe CSS customizada.
  4. **Última Publicação (Publicador):** Seleção de um Publicador de Destaques ativo; no carregamento do site, o link resolverá dinamicamente para a URL da publicação mais recente desse publicador (com ordenação selecionável).
* Na interface do painel, cada linha de imagem na lista terá um painel retrátil "Configurar Link" contendo os dropdowns e inputs necessários, os quais aparecerão de acordo com o tipo de link selecionado.
* Os templates de galeria serão atualizados para dar suporte às novas variáveis: `[[item#link-url]]`, `[[item#link-target]]` e `[[item#link-css-classes]]`.
### 1.2 Controles de Exibição de Galerias (Altura e Margem Lateral)
Para melhorar a adequação visual das galerias nas páginas:
* Inclusão de dois novos campos numéricos na aba "Controles de Exibição" no painel de Galerias:
  1. **Altura do Container:** Altura vertical em pixels. Padrão: `300`.
  2. **Margem Lateral:** Distância em pixels nas laterais esquerda e direita da galeria. Padrão: `0` (encostado).
* Os templates visuais de galerias (carrossel, slider, grid) devem ser atualizados para aplicar dinamicamente esses valores no estilo dos elementos (imagens e seções raiz), utilizando as variáveis globais de controle `[[height]]` e `[[margin_lateral]]`.
### 1.3 Correção de Mapeamento no Destaques (`linked-fields-list`)
No mapeamento de variáveis do módulo de Destaques (`publisher-highlights`), as tags de variáveis vinculadas no container `#linked-fields-list` estão coladas horizontalmente. É necessário espaçá-las adicionando margens horizontais.
### 1.4 Correção do Menu Horizontal (`menus-horizontal-navbar`)
No template `menus-horizontal-navbar` (tanto em pt-br quanto en), os submenus (nível 2 e subsequentes) estão sem recuo horizontal (padding) interno, fazendo com que o texto dos links encoste na borda esquerda da caixa flutuante. É necessário aplicar o margeamento/padding adequado via CSS nos links internos das camadas inferiores do dropdown.
### 1.5 Correção do Layout de Alvenaria (`galleries-masonry`)
No template `galleries-masonry` (tanto em pt-br quanto en), a legenda das imagens está muito próxima das bordas esquerda e inferior. É necessário aumentar esse espaçamento aplicando margeamento ou padding.
---
## 2. Especificações de Alteração de Código
### 2.1 Módulo de Galerias: Painel Administrativo
#### [MODIFY] [galleries.js](file:///[REDACTED])
1. **Estrutura dos itens de imagem:** Atualize o contrato dos itens curados para suportar as propriedades de link:
   * `link_type` (padrão: `'nenhum'`), `link_page_id`, `link_url`, `link_target` (padrão: `'_self'`), `link_css_classes`, `link_publisher_id`, `link_order_by` (padrão: `'date_desc'`).
2. **Interface do Item (`buildItemRow`):**
   * Adicione o botão toggle retrátil com ícone `linkify` e o texto "Definir Link" (ou similar).
   * Adicione a div oculta `.gallery-item-link-fields` contendo:
     * Dropdown do tipo de link: Nenhum, Página, Link Customizado, Link com Classe CSS, Última Publicação.
     * Dropdown de Página: populado com as opções vindas da variável global `galleries_pages`.
     * Input de URL (para custom e class link).
     * Dropdown de Alvo (`_self`, `_blank`).
     * Input de Classe CSS.
     * Dropdown de Publicador: populado com as opções vindas da variável global `galleries_publishers`.
     * Dropdown de Ordenação do Publicador (`date_desc`, `date_asc`, etc.).
   * Vincule eventos de alteração (`change`, `input`) a esses inputs para salvar o estado correspondente no objeto `items[idx]` e chamar `serializeAndPreview()`.
   * Vincule o clique do botão toggle para alternar (`slideToggle` / `toggle`) a visibilidade da div de configurações de link.
3. **Controles de Exibição globais:**
   * Atualize `currentSchemaOut()` e `hydrateGalleryControls()` para ler/salvar os campos `#gallery-height` (padrão `300`) e `#gallery-margin-lateral` (padrão `0`).
   * Adicione o listener de eventos de digitação (`input change`) para `#gallery-height` e `#gallery-margin-lateral` chamando `serializeAndPreview()`.
#### [MODIFY] [galleries.php](file:///[REDACTED])
1. **Carregamento de Listas Globais:** Em `galleries_adicionar()` e `galleries_editar()`, busque todos os registros ativos de páginas e publicadores de destaques no idioma corrente, e os exporte para o frontend injetando a tag de script com as variáveis globais JSON:
   ```php
   $publishers = banco_select_name(
       banco_campos_virgulas(Array('name', 'id')),
       'publishers',
       "WHERE status='A' AND language='".$_GESTOR['linguagem-codigo']."' ORDER BY name ASC"
   ) ?: [];
   $pages = banco_select_name(
       banco_campos_virgulas(Array('name', 'id')),
       'pages',
       "WHERE status='A' AND language='".$_GESTOR['linguagem-codigo']."' ORDER BY name ASC"
   ) ?: [];
   $_GESTOR['pagina'] .= '<script>'
       . 'var galleries_publishers = ' . json_encode($publishers) . ';'
       . 'var galleries_pages = ' . json_encode($pages) . ';'
       . '</script>';
   ```
2. **Variáveis de Template:** Registre as novas variáveis globais e de item na função `galleries_variaveis_template()` para alimentar o html-editor:
   * Globais: `height`, `margin_lateral`.
   * De item: `link-url`, `link-target`, `link-css-classes`.
#### [MODIFY] Páginas HTML do Painel de Galerias:
Injetar os inputs de altura e margem na aba de Controles de Exibição, logo abaixo dos checkboxes em:
* [pt-br/pages/galleries-adicionar.html](file:///[REDACTED])
* [pt-br/pages/galleries-editar.html](file:///[REDACTED])
* [pt-br/pages/galleries-clonar.html](file:///[REDACTED])
* [en/pages/galleries-adicionar.html](file:///[REDACTED])
* [en/pages/galleries-editar.html](file:///[REDACTED])
* [en/pages/galleries-clonar.html](file:///[REDACTED])
---
### 2.2 Módulo de Galerias: Renderizador e Widget
#### [MODIFY] [galleries.widget.php](file:///[REDACTED])
1. **Resolução de Páginas em Lote:** Colete todos os `link_page_id` dos itens da galeria e monte uma única query para recuperar o slug/caminho canônico dessas páginas (assim como feito no Menus), populando um mapa.
2. **Resolução Dinâmica do Link de Publicador:** Adicione uma função auxiliar para consultar a publicação mais recente de um publicador dado o `publisher_id` e a ordenação (`order_by`), retornando seu caminho de URL.
3. **Mapeamento de Variáveis de Item (`galleries_widget_resolver_item_vars`):**
   * Retorne `link-url`, `link-target` e `link-css-classes`.
   * Se o `link_type` for `'nenhum'`, retorne `'javascript:void(0);'` para o `link-url`.
   * Se o `link_type` for `'pagina'`, retorne a URL correspondente recuperada do mapa.
   * Se o `link_type` for `'publicador'`, execute a consulta da publicação mais recente.
   * Se o `link_type` for `'link-custom'` ou `'link-action'`, retorne a URL manual do schema.
4. **Resolução de Globais (`galleries_widget_resolver_globais`):** Resolva `height` e `margin_lateral` a partir do schema (com fallbacks para `300` e `0` respectively).
---
### 2.3 Ajustes nos Templates de Galerias
Atualize os arquivos de templates (tanto em `pt-br` quanto `en`) para aplicar a margem e a altura:
1. **Margem Lateral:** Adicione o estilo inline no elemento raiz `<section>` de **todos** os templates:
   `style="margin-left: @[[margin_lateral]]@px; margin-right: @[[margin_lateral]]@px;"`
2. **Altura do Container:**
   * **Slider ([pt-br](file:///[REDACTED]) e [en](file:///[REDACTED])):** Aplique o estilo `style="height: @[[height]]@px;"` no elemento da imagem (`img`) e no container do slide (`figure.gallery-slide`).
   * **Carousel ([pt-br](file:///[REDACTED]) e [en](file:///[REDACTED])):** Remova a classe de altura fixa da imagem (`h-56`) e aplique o estilo inline `style="height: @[[height]]@px;"` no elemento da imagem (`img`).
   * **Grid ([pt-br](file:///[REDACTED]) e [en](file:///[REDACTED])):** Remova a classe de altura fixa da imagem (`h-48`) e aplique o estilo inline `style="height: @[[height]]@px;"` no elemento da imagem (`img`).
3. **Espaçamento da Legenda no Masonry ([pt-br](file:///[REDACTED]) e [en](file:///[REDACTED])):**
   * Altere a tag `figcaption` de `class="text-sm text-gray-600 mt-1 px-1"` para `class="text-sm text-gray-600 mt-2 px-3 pb-2"`.
---
### 2.4 Ajustes de Outros Módulos e Layouts
#### [MODIFY] [publisher-highlights.js](file:///[REDACTED])
1. **Espaçamento do Mapeamento de Variáveis:** Na função `renderLinkedVars()`, altere a linha 359:
   * De: `var $row = $('<div class="ui label" style="margin:2px 0;display:inline-block;"></div>')`
   * Para: `var $row = $('<div class="ui label" style="margin:2px 4px;display:inline-block;"></div>')`
#### [MODIFY] Templates de `menus-horizontal-navbar` ([pt-br](file:///[REDACTED]) e [en](file:///[REDACTED]))
Adicione um bloco `<style>` contido na tag raiz `<section>` para formatar e adicionar padding interno nos links dos submenus recursivos:
```html
    <style>
        /* Adiciona padding interno e organiza layout de blocos nas subpastas do navbar */
        [data-title="menu-horizontal-navbar"] ul.absolute a {
            display: block !important;
            padding: 0.5rem 1rem !important; /* px-4 py-2 */
            font-size: 0.875rem !important; /* text-sm */
        }
        [data-title="menu-horizontal-navbar"] ul.absolute a:hover {
            background-color: #f3f4f6 !important; /* hover:bg-gray-100 */
        }
    </style>
```
---
## 3. Verificação
Para validar a implementação:
1. **Mapeamento de Variáveis Destaques:** Acesse o painel de Destaques e vincule variáveis. Verifique se as tags não aparecem mais coladas horizontalmente.
2. **Submenus no Menu Horizontal:** No preview do painel ou página publicada, abra o submenu de um menu horizontal e certifique-se de que os itens filhos têm recuo horizontal (padding) e a área de hover funciona perfeitamente.
3. **Links e Controles nas Galerias:**
   * Crie uma galeria e configure diferentes tipos de links (página, custom com blank, e publicador). No preview, confirme se os links são gerados no HTML das imagens.
   * Altere a altura da galeria para `450` e a margem lateral para `20`. Certifique-se de que a galeria reflete as dimensões no preview instantaneamente.
   * No template Masonry, certifique-se de que a legenda não fica mais colada na esquerda e na parte inferior do card.