Pular para o conteúdo principal

Arquitetura do tema

Core do Omeka S theming​

O Omeka S utiliza um sistema de templates com hierarquia de sobreposição. Templates padrão do sistema residem em omeka-s/application. Quando um tema define um arquivo no mesmo caminho relativo, o Omeka S prioriza a versão do tema. Essa sobreposição permite que temas customizem a experiência visual sem modificar o core do sistema.

O tema SGM é uma customização baseada no tema The Daily, que forneceu a estrutura inicial. Herda o sistema de layout, helpers, e estrutura de pastas padrão. Apesar do uso do Tailwind CSS, o tema mantém arquivos CSS separados pois estão associados a elementos em templates padrão do Omeka que não foram alterados. Esses estilos garantem que os componentes herdados continuem estilizados corretamente.

Template path stack e resolução​

A resolução de templates no Omeka S segue uma ordem determinada pelo template_path_stack. Quando um template é solicitado via $this->partial('common/header'), o sistema procura na seguinte ordem:

  1. Tema ativo: themes/sgm/view/common/header.phtml
  2. Módulos ativados: cada módulo pode registrar seu próprio path de templates
  3. Core do Omeka S: application/view/common/header.phtml

Para blocos customizados do SGMBlocks, a resolução funciona da mesma forma. O módulo registra templates em modules/SGMBlocks/view/common/block-layout/. Se o tema definir o mesmo caminho em themes/sgm/view/common/block-layout/, a versão do tema prevalece. Veja Blocos customizados para detalhes.

Eventos de view​

O tema utiliza triggers do Omeka S para extensibilidade:

  • $this->trigger('view.layout'): antes do layout principal
  • $this->trigger('view.show.before'): antes de exibir recurso
  • $this->trigger('view.show.after'): depois de exibir recurso
  • $this->trigger('view.browse.before'): antes de listagem
  • $this->trigger('view.browse.after'): depois de listagem

Esses triggers permitem que módulos executem código em pontos específicos do ciclo de renderização.

view/layout/layout.phtml​

O layout principal é o shell HTML base de todas as páginas do site. Ele organiza a estrutura geral da página incluindo o head, carregamento de assets, e a renderização dos componentes principais.

Metadados básicos​

No head, são definidos os metadados essenciais para o funcionamento responsivo do site:

$this->headMeta()->setCharset('utf-8');
$this->headMeta()->appendName('viewport', 'width=device-width, initial-scale=1');
$this->headTitle($siteTitle)->setSeparator(' · ');

Carregamento de assets​

O layout inclui referências para os principais arquivos CSS e JavaScript:

CSS:

  • output.css: CSS compilado do Tailwind
  • iconfonts.css: fontes de ícones do Omeka
  • Google Fonts: Inter e Material Symbols

JavaScript:

  • jQuery do Omeka
  • global.js: funcionalidades gerais do Omeka
  • thedaily.js: scripts legados do tema The Daily

Renderização de conteúdo​

O layout utiliza partials para incluir os componentes básicos:

<?php echo $this->htmlElement('body'); ?>
<?php echo $userBar; ?>
<?php echo $this->partial('common/header', ['fixedHeader' => $fixedHeader]); ?>
<?php echo $this->content; ?>
<?php echo $this->partial('common/footer'); ?>

O conteúdo dinâmico da página é inserido através de $this->content, que é populado pelo Omeka S conforme a rota atual.

Variável fixedHeader​

O layout gerencia a variável global $GLOBALS['fixedHeader'] que controla se o header deve ser fixo e transparente. Primeiro verifica se a variável já foi definida por um template filho, depois tenta obter da página atual via layoutDataValue('fixed_header') ou via data(). A variável é então passada para o header partial e definida globalmente para uso em outros componentes.

view/layout/page-render/fixed-header.phtml​

Este partial centraliza a detecção do header fixo para evitar repetição de código em múltiplos templates. Ele recebe a variável $page como entrada e define $GLOBALS['fixedHeader'] como efeito colateral.

Como foi construído​

O partial encapsula a lógica de verificação do campo fixed_header em um arquivo reutilizável. Templates de página incluem este partial no topo em vez de duplicar a lógica de detecção. O partial tenta obter o valor via layoutDataValue primeiro, com fallback para data(), normalizando valores como true, 1, '1', 'true', 'on', 'yes'.

Como usar como desenvolvedor​

Inclua no topo de qualquer template de página que precise detectar header fixo:

echo $this->partial('layout/page-render/fixed-header', ['page' => $page]);

A variável $GLOBALS['fixedHeader'] estará disponível para o restante do template e para o layout principal. Outros arquivos existem na pasta view/layout/page-render/: banner-blocks.phtml e main-blocks.phtml. Estes não estão em uso ativo no momento.

view/omeka/site/page/show.phtml​

Template padrão para exibição de páginas. Ele implementa uma cadeia de renderização sofisticada com suporte a templates por slug.

Como foi construído​

O template implementa três camadas de renderização:

1. Detecção de header fixo:

echo $this->partial('layout/page-render/fixed-header', ['page' => $page]);

2. Template por slug: Verifica se existe omeka/site/page/show/{slug}.phtml. Se existir, renderiza e retorna, interrompendo a execução do template padrão. O único template por slug ativo é soon.phtml.

3. Renderização de blocos banner-page: Blocos do tipo banner-page são renderizados primeiro, fora do container principal, permitindo que ocupem a largura total da viewport.

4. Renderização de blocos principais: Blocos restantes são renderizados dentro de um container com sistema de grid de 12 colunas. O template implementa:

  • Suporte a grupos de blocos via blockGroup
  • Aplicação de classes CSS dinâmicas baseadas em layoutDataValue
  • Estilos inline para padding, cores de fundo, altura mínima
  • Controle de gaps via grid_column_gap e grid_row_gap

Blocos excluídos da renderização principal: thumbnail-block, page-description, banner-page.

Estrutura de dados​

Páginas têm blocos acessíveis via $page->blocks(). Cada bloco tem:

  • layout(): nome do layout do bloco
  • dataValue('chave'): valor de um campo do bloco
  • layoutDataValue('chave', $default): valor de layout data

view/omeka/site/item/show.phtml​

Template responsável pela exibição detalhada de um item individual.

Como foi construído​

O template organiza a exibição em seções distintas:

1. Preparação de dados:

  • Obtém mídias do item via $item->media()
  • Configura meta tag Open Graph com thumbnail
  • Obtém coleções associadas via $item->itemSets()
  • Ativa header fixo via $GLOBALS['fixedHeader'] = true

2. Banner do item: Renderizado via common/resources/banner partial, que exibe imagem de destaque e informações da coleção.

3. Metadados: Renderizados via common/resources/meta partial, que exibe propriedades do item em formato tabular.

4. Recursos vinculados: Exibe valores relacionados via $item->displaySubjectValues() com paginação.

5. Galeria de mídia: Utiliza $this->lightGalleryOutput() para renderizar mídias em galeria interativa.

view/omeka/site/item/browse.phtml​

Template para listagem de itens dentro de uma coleção.

Como foi construído​

O template implementa uma listagem paginada com:

1. Query de itens: Obtém itens da coleção atual via parâmetros de query, com paginação manual.

2. Banner da coleção: Renderizado via common/resources/banner partial com a coleção como contexto.

3. Metadados da coleção: Renderizados via common/resources/meta partial.

4. Grid de itens: Utiliza common/block-layout/browse-preview partial para renderizar thumbnails em grid.

5. Paginação customizada: Implementa paginação manual com controles de anterior e próximo, números de página, e elipses para gaps. A paginação mantém parâmetros de busca na URL.

view/omeka/site/item-set/show.phtml​

Template para exibição detalhada de uma coleção individual.

Como foi construído​

1. Header section: Exibe thumbnail da coleção, título via displayTitle, e descrição via displayDescription.

2. Tabela de metadados: Itera sobre $itemSet->values() agrupados por termo de propriedade. Para cada propriedade, obtém o label via API e formata os valores. A tabela também exibe contagem de itens na coleção.

3. Grid de itens: Lista todos os itens da coleção em grid responsivo. Cada item exibe thumbnail, título, e descrição. Configurações browse_heading_property_term e browse_body_property_term controlam quais propriedades aparecem como título e descrição.

view/omeka/site/item-set/browse.phtml​

Template para listagem de coleções.

Como foi construído​

Exibe grid de coleções com thumbnail, título e descrição. Utiliza as mesmas configurações de heading e body property que o browse de itens. Cada coleção é um link para sua página de detalhes.

view/omeka/site/index/search.phtml​

Template para página de busca avançada. Documentado em detalhes em Recurso de pesquisa.

Estrutura de pastas do tema​

sgm/
├── asset/                    # Assets estáticos
│   ├── css/                  # CSS compilado
│   ├── js/                   # JavaScript
│   ├── img/                  # Imagens
│   └── styles/               # Fontes CSS do Tailwind
├── config/                   # Configurações
│   └── theme.ini             # Configurações do tema
├── view/                     # Templates PHP
│   ├── layout/               # Layout principal
│   │   ├── layout.phtml      # Shell HTML base
│   │   └── page-render/      # Helpers de renderização
│   ├── common/               # Componentes reutilizáveis
│   │   ├── block-layout/     # Templates de blocos
│   │   ├── resources/        # Partials de recursos
│   │   └── *.phtml           # Partials diversos
│   └── omeka/                # Templates do Omeka
│       └── site/             # Views públicas
│           ├── page/         # Páginas
│           ├── item/         # Itens
│           ├── item-set/     # Coleções
│           └── index/        # Index e busca

Essa organização modular separa claramente a lógica do layout base, blocos reutilizáveis, templates específicos do Omeka, e helpers de renderização.