Banner de página

O bloco banner-page exibe uma seção com imagem de fundo, título, descrição e, no alinhamento centralizado, overlay e barra de pesquisa opcional. A versão 1.3 do módulo reformulou o bloco: saíram size, button_text e button_link; entraram use_overlay, show_search_bar e show_search_suggestions. Depois disso, o bloco passou a normalizar content_align legado e a restringir overlay/pesquisa ao alinhamento center.

---

Como foi construído

Identificação

Item	Valor
Classe	SGMBlocks\Site\BlockLayout\BannerPage
block_layout	banner-page
Form	SGMBlocks\Form\BannerPageForm
Factory	SGMBlocks\Service\BlockLayout\BannerPageFactory
Partial	common/block-layout/banner-page

Formulário

O BannerPageForm estende Fieldset e define sete elementos no init, nesta ordem: image, title, description, content_align, use_overlay, show_search_bar, show_search_suggestions.

$this->add(['name' => 'o:block[__blockIndex__][o:data][image]',
    'type' => OmekaElement\Asset::class,
    'options' => ['label' => 'Imagem de Fundo'],
    'attributes' => ['required' => true]]);

$this->add(['name' => 'o:block[__blockIndex__][o:data][title]',
    'type' => Element\Text::class,
    'options' => ['label' => 'Título do Banner'],
    'attributes' => ['required' => true]]);

$this->add(['name' => 'o:block[__blockIndex__][o:data][description]',
    'type' => Element\Textarea::class,
    'options' => ['label' => 'Descrição'],
    'attributes' => ['rows' => 4]]);

$this->add(['name' => 'o:block[__blockIndex__][o:data][content_align]',
    'type' => Element\Select::class,
    'options' => ['label' => 'Alinhamento do conteúdo',
        'value_options' => ['center' => 'Centralizado', 'left' => 'Esquerda']],
    'attributes' => ['value' => 'center', 'class' => 'banner-page-content-align']]);

$this->add(['name' => 'o:block[__blockIndex__][o:data][use_overlay]',
    'type' => Element\Checkbox::class,
    'options' => ['label' => 'Usar overlay na imagem'],
    'attributes' => ['value' => true, 'class' => 'banner-page-center-only']]);

$this->add(['name' => 'o:block[__blockIndex__][o:data][show_search_bar]',
    'type' => Element\Checkbox::class,
    'options' => ['label' => 'Mostrar barra de pesquisa'],
    'attributes' => ['value' => false, 'class' => 'banner-page-center-only']]);

$this->add(['name' => 'o:block[__blockIndex__][o:data][show_search_suggestions]',
    'type' => Element\Checkbox::class,
    'options' => ['label' => 'Mostrar sugestões de pesquisa'],
    'attributes' => ['value' => false, 'class' => 'banner-page-center-only']]);

O select de alinhamento usa valores canônicos center e left, com default center. Os três checkboxes carregam a classe banner-page-center-only para o script do admin.

Classe do bloco

BannerPage::prepareForm anexa admin.css e js/banner-page-admin.js.

BannerPage::form popula valores quando $block existe e normaliza o alinhamento:

$form->populateValues([
    'o:block[__blockIndex__][o:data][image]' => $block->dataValue('image'),
    'o:block[__blockIndex__][o:data][use_overlay]' => $block->dataValue('use_overlay') ?? true,
    'o:block[__blockIndex__][o:data][content_align]' => $this->normalizeContentAlign($block->dataValue('content_align')),
    'o:block[__blockIndex__][o:data][title]' => $block->dataValue('title'),
    'o:block[__blockIndex__][o:data][description]' => $block->dataValue('description'),
    'o:block[__blockIndex__][o:data][show_search_bar]' => $block->dataValue('show_search_bar') ?: false,
    'o:block[__blockIndex__][o:data][show_search_suggestions]' => $block->dataValue('show_search_suggestions') ?: false,
]);

BannerPage::render resolve o asset, normaliza o alinhamento e só libera overlay/pesquisa quando o alinhamento é center:

$imageId = $block->dataValue('image');
$image = null;
$contentAlign = $this->normalizeContentAlign($block->dataValue('content_align'));
$isCenter = $contentAlign === 'center';

if ($imageId) {
    try {
        $image = $view->api()->read('assets', $imageId)->getContent();
    } catch (\Exception $e) {
        // Asset não encontrado ou erro ao ler
    }
}

return $view->partial('common/block-layout/banner-page', [
    'image' => $image,
    'use_overlay' => $isCenter && ($block->dataValue('use_overlay') ?? true),
    'content_align' => $contentAlign,
    'title' => $block->dataValue('title'),
    'description' => $block->dataValue('description'),
    'show_search_bar' => $isCenter && ($block->dataValue('show_search_bar') ?: false),
    'show_search_suggestions' => $isCenter && ($block->dataValue('show_search_suggestions') ?: false),
]);

Normalização de content_align

normalizeContentAlign mapeia valores legados para as options atuais do form:

private function normalizeContentAlign($align)
{
    if ($align === 'esquerda' || $align === 'left') {
        return 'left';
    }

    return 'center';
}

Assim esquerda, left, center, centralizado e valores vazios/desconhecidos caem em left ou center antes de ir para o form e para o partial.

Admin JS

asset/js/banner-page-admin.js esconde os campos com seletor [name$="[use_overlay]"], [name$="[show_search_bar]"] e [name$="[show_search_suggestions]"] quando o select .banner-page-content-align não está em center (nem no legado centralizado). Roda no document.ready, no change do select e no evento o:block-added.

Partial

O partial banner-page.phtml anexa style.css no topo, verifica se há $image e, se sim, emite a seção. O fallback de alinhamento no módulo é center:

<section class="sgm-banner-page" style="background-image: url('<?= $this->escapeHtmlAttr($image->assetUrl()) ?>');">
    <div class="sgm-banner-overlay">
        <div class="sgm-banner-content sgm-banner-content-<?= $this->escapeHtmlAttr($content_align ?: 'center') ?>">
            <?php if (!empty($title)): ?><h1 class="sgm-banner-title"><?= $this->escapeHtml($title) ?></h1><?php endif; ?>
            <?php if (!empty($description)): ?><p class="sgm-banner-description"><?= $this->escapeHtml($description) ?></p><?php endif; ?>

            <?php if ($show_search_bar): ?>
                <div class="sgm-banner-search">
                    <form action="..." method="get">
                        <input type="text" name="q" placeholder="Pesquisar...">
                        <button type="submit">Buscar</button>
                    </form>
                    <?php if ($show_search_suggestions): ?>
                        <div class="sgm-search-suggestions">...</div>
                    <?php endif; ?>
                </div>
            <?php endif; ?>
        </div>
    </div>
</section>

No tema SGM o partial sobrescrito trata center e left de forma distinta: center usa a imagem como background-image com overlay opcional; left usa fundo sólido, imagem em camada e breadcrumb fora da homepage. Overlay e formulário de busca só entram se as flags já vieram gated pelo BannerPage::render.

Persistência

Chave em o:data	Tipo	Observação
image	inteiro id de asset	Asset da biblioteca do site.
title	string	Obrigatório. Escapado com escapeHtml no partial.
description	string	Opcional. Escapado com escapeHtml no partial.
content_align	string	Options do select: center, left. Default do form: center. Legado esquerda/centralizado é normalizado no PHP.
use_overlay	booleano	Default true. Só tem efeito no render quando o alinhamento é center.
show_search_bar	booleano	Default false. Só tem efeito no render quando o alinhamento é center.
show_search_suggestions	booleano	Default false. Só tem efeito se show_search_bar for true e o alinhamento for center.

Assets carregados

• Frontend: asset/css/style.css. Define .sgm-banner-page, .sgm-banner-overlay, .sgm-banner-content-center / .sgm-banner-content-centralizado, .sgm-banner-content-left / .sgm-banner-content-esquerda, e tamanhos históricos .sgm-banner-small, .sgm-banner-medium.
• Admin: asset/css/admin.css e asset/js/banner-page-admin.js.

---

Como usar como desenvolvedor

Sobrescrever o partial no tema

Copie view/common/block-layout/banner-page.phtml para themes/<tema>/view/common/block-layout/banner-page.phtml. O Laminas resolve o do tema primeiro. Trate content_align já normalizado (center ou left) e confie nas flags use_overlay, show_search_bar e show_search_suggestions já gated pelo bloco.

Extender o formulário

Para adicionar um campo novo, edite src/Form/BannerPageForm.php e acrescente outro $this->add(...) com o padrão o:block[__blockIndex__][o:data][nome]. Depois acrescente a leitura no BannerPage::form dentro do populateValues, e a propagação ao partial em BannerPage::render. O novo valor já será persistido pelo Omeka junto aos demais. Se o campo só fizer sentido no layout centralizado, reutilize a classe banner-page-center-only e atualize o seletor em banner-page-admin.js.

Adicionar validação

Anexe um listener ao form.add_input_filters do BannerPageForm. Exemplo conceitual:

$sharedEventManager->attach(
    BannerPageForm::class,
    'form.add_input_filters',
    function ($event) {
        $inputFilter = $event->getParam('inputFilter');
        $inputFilter->add([
            'name' => 'o:block[__blockIndex__][o:data][title]',
            'required' => true,
            'validators' => [['name' => 'StringLength', 'options' => ['max' => 120]]],
        ]);
    }
);

Ler o bloco em outros templates

foreach ($page->blocks() as $block) {
    if ($block->layout() === 'banner-page') {
        $imageId = $block->dataValue('image');
        $title = $block->dataValue('title');
        $align = $block->dataValue('content_align'); // pode ainda ser legado; normalize se for ler
    }
}

Depurar

• Se o banner não renderiza, confirme que image tem um id válido. Sem asset válido o render retorna uma string vazia porque o partial abre com <?php if ($image): ?>.
• Se overlay ou pesquisa não aparecem, confira o alinhamento. Com left, o PHP força as três flags para off.
• Se a barra de pesquisa não aparece com alinhamento center e show_search_bar = true, inspecione $site no template do módulo. O partial do módulo usa $site->slug() para montar a URL do form; o tema SGM usa o partial common/search-form.

---

Observações

Gate de overlay e pesquisa no center

O admin esconde os três checkboxes quando o alinhamento é left. O render reforça a regra no servidor: mesmo com valores antigos gravados em o:data, o partial só recebe use_overlay, show_search_bar e show_search_suggestions verdadeiros se $contentAlign === 'center'.

Escape

• title e description usam escapeHtml.
• A URL da imagem usa escapeHtmlAttr dentro de background-image: url(...).
• A URL do formulário de busca no partial do módulo sai de $this->url('site/search', ...) e é escapada com escapeHtmlAttr.

Campos removidos na 1.3

Os campos size, button_text e button_link saíram do BannerPageForm. Dados antigos persistidos em páginas do admin ainda existem em o:data, mas não aparecem mais no formulário nem no partial. Se algum tema ainda referencia essas chaves, migre o consumo para a nova estrutura ou adicione fallback explícito no tema.