Pular para o conteúdo principal

Cabeçalho transparente

Este recurso não é um bloco. É um campo extra injetado no Omeka\Form\PageLayoutDataForm que grava a chave fixed_header em o:layout_data do SitePage. O valor é um booleano, e o tema do site decide como consumi-lo. O nome fixed_header ficou por motivo histórico, já que o tema SGM combina transparência com posição fixa no topo.

Como foi construído​

Handler e evento​

A implementação usa o SharedEventManager do Laminas. O anexo acontece em Module::attachListeners:

$pageHandler = new PageCustomFieldsHandler();
$sharedEventManager->attach(
    \Omeka\Form\PageLayoutDataForm::class,
    'form.add_elements',
    [$pageHandler, 'handlePageLayoutForm']
);

A classe SGMBlocks\Service\Form\PageCustomFieldsHandler é instanciada direto, sem factory, e fica anexada ao evento form.add_elements do formulário alvo. O handler adiciona o elemento:

$form->add([
    'type'    => \Laminas\Form\Element\Checkbox::class,
    'name'    => 'o:layout_data[fixed_header]',
    'options' => ['label' => 'Cabeçalho de página transparente?'],
    'attributes' => ['id' => 'fixed-header'],
]);

Substituição de factory​

O PageLayoutDataForm nativo do Omeka não dispara form.add_elements porque o core não injeta EventManager nele. Para resolver, o módulo registra em form_elements.factories:

'Omeka\Form\PageLayoutDataForm' => Service\Form\PageLayoutDataFormFactory::class,

A factory SGMBlocks\Service\Form\PageLayoutDataFormFactory instancia o formulário e injeta um EventManager antes de retornar, permitindo que o form.add_elements seja disparado durante o ciclo normal do formulário.

Persistência​

O Omeka S trata o nome o:layout_data[fixed_header] como um input aninhado. Ao submeter o formulário, o array o:layout_data entra em SitePage::setLayoutData e é salvo no banco junto ao registro da página.

AspectoValor
Chave persistidafixed_header dentro de o:layout_data do SitePage
Tipo do valorBooleano. true quando marcado, false ou ausente quando desmarcado
Atributo HTML idfixed-header
Rótulo do campoCabeçalho de página transparente?

Como usar como desenvolvedor​

Ler o valor no tema​

O consumo típico acontece no layout ou no template de exibição da página:

$layoutData = $page->layoutData();
$fixedHeader = !empty($layoutData['fixed_header']);

Com o booleano em mãos, o tema decide:

  • Adicionar uma classe ao <body> do layout, por exemplo body-fixed-header.
  • Passar a flag a um partial de cabeçalho e alternar a classe do <header>.
  • Escolher entre dois parciais distintos, um para o cabeçalho transparente e outro para o cabeçalho opaco.

Mudar o rótulo ou o tipo do campo​

Edite src/Service/Form/PageCustomFieldsHandler.php. O método handlePageLayoutForm recebe o evento e chama $form->add(...). Troque Checkbox por Radio ou Select conforme a necessidade.

Renomear a chave​

Renomear fixed_header envolve três pontos:

  1. Alterar o name no PageCustomFieldsHandler.
  2. Alterar a leitura no tema.
  3. Migrar os dados antigos. Como o valor vive em o:layout_data, a migração pode ser feita com um script que carrega cada SitePage, lê fixed_header, grava na nova chave e salva.

Adicionar validação​

O PageLayoutDataForm também dispara form.add_input_filters. Para adicionar validação, anexe um listener ao mesmo alvo nesse evento. O SGMBlocks ainda não usa esse evento para o campo, mas o SiteCustomFieldsHandler::handleSiteSettingsFilters mostra o padrão para replicar.

Depurar​

  • Se o checkbox não aparece, confirme que o module.config.php registra PageLayoutDataFormFactory em form_elements.factories e que o módulo está ativo. Sem a factory o evento não dispara.
  • Se o valor não persiste, confirme que o name está no formato o:layout_data[fixed_header] e que o Omeka está na versão ^4.0.1.
  • Para inspecionar o payload, registre um log em SitePage::setLayoutData ou use xdebug no Omeka\Api\Adapter\SitePageAdapter.

Arquivos relacionados​

  • Module.php. Anexa o handler ao SharedEventManager.
  • src/Service/Form/PageCustomFieldsHandler.php. Define o campo.
  • src/Service/Form/PageLayoutDataFormFactory.php. Injeta EventManager no formulário nativo.
  • config/module.config.php. Registra a substituição de factory.