Documentação do Módulo

Identificação

O SGMBlocks é um módulo de Omeka S na versão 1.3, declarado em config/module.ini. Ele é específico do projeto Sistema de Gestão de Mídias da UFG e complementa o tema do site do SGM com blocos de layout, campos extras no formulário de página e campos extras no formulário de configurações do site. O módulo deriva do PageBlocks de Ivy Rose e foi reduzido ao escopo do SGM.

O código vive em application\modules\SGMBlocks durante o desenvolvimento e segue a convenção de módulos do Omeka S, com um Module.php no topo, config/module.config.php para registro de serviços, src/ para classes PHP, view/ para partials, asset/ para CSS e JS, e language/ para traduções.

O que o módulo entrega

O módulo entrega três tipos de extensão ao Omeka S:

Blocos de layout registrados em block_layouts.factories e exibidos no editor de páginas do admin. São nove: accordion-block, banner-page, button-block, icon-block, page-description, resource-list-block, search-bar-block, thumbnail-block, timeline-block.
Campo extra em página injetado no Omeka\Form\PageLayoutDataForm. É um checkbox fixed_header persistido em o:layout_data da página e consumido pelo tema para decidir o modo do cabeçalho.
Campo extra em site injetado no Omeka\Form\SiteSettingsForm. É a chave sgmblocks_search_suggestions, um array de sugestões de busca persistido nas configurações do site e lido pelos blocos que mostram a barra de pesquisa.

Os dois pontos de extensão dos formulários usam o Laminas\EventManager\SharedEventManager. Os eventos são anexados em Module::attachListeners.

Estrutura de pastas

SGMBlocks/
├── Module.php
├── config/
│   ├── module.config.php
│   └── module.ini
├── src/
│   ├── Form/
│   │   ├── AccordionBlockForm.php
│   │   ├── BannerPageForm.php
│   │   ├── ButtonBlockForm.php
│   │   ├── IconBlockForm.php
│   │   ├── PageDescriptionForm.php
│   │   ├── ResourceListBlockForm.php
│   │   ├── SearchBarBlockForm.php
│   │   ├── ThumbnailBlockForm.php
│   │   └── TimelineBlockForm.php
│   ├── Service/
│   │   ├── BlockLayout/
│   │   │   ├── AccordionBlockFactory.php
│   │   │   ├── BannerPageFactory.php
│   │   │   ├── ButtonBlockFactory.php
│   │   │   ├── IconBlockFactory.php
│   │   │   ├── PageDescriptionFactory.php
│   │   │   ├── ResourceListBlockFactory.php
│   │   │   ├── SearchBarBlockFactory.php
│   │   │   ├── ThumbnailBlockFactory.php
│   │   │   └── TimelineBlockFactory.php
│   │   └── Form/
│   │       ├── PageCustomFieldsHandler.php
│   │       ├── PageLayoutDataFormFactory.php
│   │       └── SiteCustomFieldsHandler.php
│   └── Site/
│       └── BlockLayout/
│           ├── AccordionBlock.php
│           ├── BannerPage.php
│           ├── ButtonBlock.php
│           ├── IconBlock.php
│           ├── PageDescription.php
│           ├── ResourceListBlock.php
│           ├── SearchBarBlock.php
│           ├── ThumbnailBlock.php
│           └── TimelineBlock.php
├── view/
│   └── common/
│       └── block-layout/
│           ├── accordion-block.phtml
│           ├── banner-page.phtml
│           ├── button-block.phtml
│           ├── icon-block.phtml
│           ├── page-description.phtml
│           ├── resource-list-block.phtml
│           ├── search-bar-block.phtml
│           ├── timeline-block.phtml
│           └── thumbnail-block/
│               └── render.phtml
├── asset/
│   ├── css/
│   │   ├── admin.css
│   │   └── style.css
│   └── js/
│       ├── accordion-block-admin.js
│       ├── resource-list-block-admin.js
│       ├── timeline-block-admin.js
│       └── site-settings.js
└── language/

Cada subpasta tem um contrato claro. src/Form mantém definições de formulário Laminas. src/Site/BlockLayout mantém as classes de bloco que implementam Omeka\Site\BlockLayout\AbstractBlockLayout. src/Service/BlockLayout mantém as factories que instanciam essas classes via FormElementManager. src/Service/Form mantém handlers e factories para os formulários nativos do Omeka. view/common/block-layout contém os partials chamados por view partial. asset/ fica disponível via helper assetUrl.

Inventário dos blocos

`block_layout`	Classe	Form	Factory	Partial
`accordion-block`	`SGMBlocks\Site\BlockLayout\AccordionBlock`	`SGMBlocks\Form\AccordionBlockForm`	`SGMBlocks\Service\BlockLayout\AccordionBlockFactory`	`common/block-layout/accordion-block`
`banner-page`	`SGMBlocks\Site\BlockLayout\BannerPage`	`SGMBlocks\Form\BannerPageForm`	`SGMBlocks\Service\BlockLayout\BannerPageFactory`	`common/block-layout/banner-page`
`button-block`	`SGMBlocks\Site\BlockLayout\ButtonBlock`	`SGMBlocks\Form\ButtonBlockForm`	`SGMBlocks\Service\BlockLayout\ButtonBlockFactory`	`common/block-layout/button-block`
`icon-block`	`SGMBlocks\Site\BlockLayout\IconBlock`	`SGMBlocks\Form\IconBlockForm`	`SGMBlocks\Service\BlockLayout\IconBlockFactory`	`common/block-layout/icon-block`
`page-description`	`SGMBlocks\Site\BlockLayout\PageDescription`	`SGMBlocks\Form\PageDescriptionForm`	`SGMBlocks\Service\BlockLayout\PageDescriptionFactory`	`common/block-layout/page-description`
`resource-list-block`	`SGMBlocks\Site\BlockLayout\ResourceListBlock`	`SGMBlocks\Form\ResourceListBlockForm`	`SGMBlocks\Service\BlockLayout\ResourceListBlockFactory`	`common/block-layout/resource-list-block`
`search-bar-block`	`SGMBlocks\Site\BlockLayout\SearchBarBlock`	`SGMBlocks\Form\SearchBarBlockForm`	`SGMBlocks\Service\BlockLayout\SearchBarBlockFactory`	`common/block-layout/search-bar-block`
`thumbnail-block`	`SGMBlocks\Site\BlockLayout\ThumbnailBlock`	`SGMBlocks\Form\ThumbnailBlockForm`	`SGMBlocks\Service\BlockLayout\ThumbnailBlockFactory`	`common/block-layout/thumbnail-block/render`
`timeline-block`	`SGMBlocks\Site\BlockLayout\TimelineBlock`	`SGMBlocks\Form\TimelineBlockForm`	`SGMBlocks\Service\BlockLayout\TimelineBlockFactory`	`common/block-layout/timeline-block`

Handlers e factories de formulários

SGMBlocks\Service\Form\PageCustomFieldsHandler. Anexado a form.add_elements no Omeka\Form\PageLayoutDataForm. Adiciona o checkbox o:layout_data[fixed_header].
SGMBlocks\Service\Form\SiteCustomFieldsHandler. Anexado a form.add_elements e form.add_input_filters no Omeka\Form\SiteSettingsForm. Também ouve view.layout do controller Omeka\Controller\SiteAdmin\Index para injetar admin.css e site-settings.js na página de edição do site.
SGMBlocks\Service\Form\PageLayoutDataFormFactory. Registrada em form_elements.factories para substituir a factory padrão do PageLayoutDataForm. Injeta EventManager no formulário para permitir o disparo de form.add_elements.

Áreas de persistência

O módulo grava em três áreas distintas do Omeka S:

Dados de bloco em o:block[__blockIndex__][o:data], ou seja, dentro do JSON de o:page[o:block] de cada SitePage. Os campos de cada bloco vivem nessa chave.
Dados de layout da página em o:layout_data do SitePage. O módulo grava apenas fixed_header.
Site settings em Omeka\Settings\Site com a chave sgmblocks_search_suggestions. O valor é um array de itens com text e url.

Asset pipeline

asset/css/style.css é carregado no frontend pelos partials que precisam de estilo próprio. O carregamento é feito via $this->headLink()->appendStylesheet($this->assetUrl('css/style.css', 'SGMBlocks')) dentro dos partials.
asset/css/admin.css é carregado no admin pelos blocos que sobrescrevem prepareForm e pela injeção do SiteCustomFieldsHandler via view.layout.
asset/js/accordion-block-admin.js é anexado pelo AccordionBlock::prepareForm e controla a lista dinâmica de itens do acordeão no editor.
asset/js/banner-page-admin.js é anexado pelo BannerPage::prepareForm e esconde overlay/pesquisa quando o alinhamento é left.
asset/js/resource-list-block-admin.js é anexado pelo ResourceListBlock::prepareForm e controla pickers, ordenação e drag-and-drop de páginas.
asset/js/timeline-block-admin.js é anexado pelo TimelineBlock::prepareForm e controla a lista dinâmica de itens da linha do tempo.
asset/js/site-settings.js é anexado pelo SiteCustomFieldsHandler na página de edição do site e controla a lista dinâmica de sugestões de busca.

Notas de versão

1.3. Quatro novos blocos, button-block, search-bar-block, accordion-block, icon-block. Reformulação do banner-page com remoção dos campos size, button_text, button_link e adição de use_overlay, show_search_bar, show_search_suggestions. Novo asset accordion-block-admin.js. Bloco resource-list-block com três modos de listagem (coleções, itens, páginas), partial paginado e asset resource-list-block-admin.js.

Onde ir a seguir

Arquitetura geral. Detalhamento técnico de Module.php, module.config.php, src/, view/, asset/ e language/.
Fluxo de funcionamento. Registro, eventos, ciclo do formulário e ciclo do render com diagrama.
Cada bloco e cada campo extra tem seu próprio arquivo dentro de funcionalidades/.

Identificação​

O que o módulo entrega​

Estrutura de pastas​

Inventário dos blocos​

Handlers e factories de formulários​

Áreas de persistência​

Asset pipeline​

Notas de versão​

Onde ir a seguir​