News Omeka S Page Templates

Page templates, a feature introduced in Omeka S v4.1.0, is a game changer for theme developers looking for custom layouts per page, going beyond the standard cross-page template system that was applied by default to all pages in previous versions.

Thanks to this feature, the entire page can have a template selected by the author, with the choices coming from the current theme. Small differences in overall layout or completely custom pages can be created as page templates and exposed for site authors to use.

The “Korematsu” theme, a custom theme developed by Omeka for the “AM I AN AMERICAN OR AM I NOT?” website is a practical example of how page templates can be used.

Based on the website design and some specific needs per page, this theme offers 6 different page templates:

• Default: the default template used in most of the pages.
• No page navigation: Same as the default template, but excluding the page navigation controls.
• Page with Hero: a template that adds a hero image (configured in the theme options) to the top of the page. In this specific site, it is used in the homepage (but not limited to it).
• Page with Hero - No page navigation: Same as the template above, but excluding the page navigation controls.
• Full Width: A template that allows contents to expand to the viewport full width (no boxed layout).
• Full Width - No page navigation: Same as the template above, but excluding the page navigation controls.

Let’s dive deeper into page templates, how they were implemented in this specific site, and some use cases.

How to implement page templates

1. Register the page template in your theme’s theme.init file using the format:

   page_templates.template-filename = "[Template display name]"
   

   For the Korematsu theme, we registered our custom page templates like this:

   page_templates.no-page-nav = "No page navigation"
   page_templates.page-with-hero = "Page with Hero"
   page_templates.page-with-hero-no-page-nav = "Page with Hero - No page navigation"
   page_templates.full-width = "Full width"
   page_templates.full-width-no-page-nav = "Full width - No page navigation"
   

2. Create the template files within your theme directory, in view/common/page-template/ with the same names you defined in the step above, using the .phtml extension:
   
   You can use application/view/omeka/site/page/show.phtml as a base for your custom page templates, then apply your custom code.

How to assign a page template to a page

Once your page template files are set and ready to go, you can assign them in the Omeka S dashboard:

1. Click on “Edit” on the page you want to assign the template to.

2. Click on the Configure Layout icon in the Layout options bar (1), in the right panel select the template (2):
   

3. Save and test the page with the custom template assigned.

Use cases

One of the custom page templates we are using in the Korematsu theme is “Page with Hero - No page navigation”. This is used in the homepage as we wanted to have a hero just in this page. However, since it is a template, it can be used in any other page if required.

Another requirement was to hide the page navigation controls in this page (and some other specific pages), so we created a variation of every template to exclude these controls.

To build this template we used the default template included in the Omeka S core (application/view/omeka/site/page/show.phtml) as basecode, and just modified it accordingly.

For example, to get rid of the page navigation controls on our custom template, we just deleted the portion of code that prints this:

<?php if ($showPagePagination): ?>
    <?php echo $this->sitePagePagination(); ?>
<?php endif; ?>

It is also a good practice to add a custom class to the body based on the current page template. This can be done in the same custom page template file:

$this->htmlElement('body')->appendAttribute('class', 'page-with-hero');

This is very helpful in case you want to assign custom specific styles to certain page templates.

Regarding the hero part, it is important to mention that page template code is rendered within the main content div (id=”main-content”). If you want to modify something outside this div based on the page template (which was the case for the Korematsu theme hero in the homepage per the design specs), you need to follow this approach:

1. In the custom template file, set the $page variable to the layout template:

   $this->layout()->setVariable('page', $page);
   

   This allows us to get the current page template in the layout.phtml file (where we wanted to add our Hero element).

2. In the layout.phtml file, get the current page template name:

   $pageTemplate = isset($page) ? $page->layoutDataValue('template_name') : '';
   

3. Then, insert the partial (in this case, we called it banner) right before the main content div if the current page template name is page-with-hero:

   <?php if (strpos($pageTemplate, 'page-with-hero') === 0): ?>
    <?php echo $this->partial('common/banner'); ?>
   <?php endif; ?>
   

   Now, whenever we assign the “Page with Hero” or “Page with Hero - No page navigation” template to any page, this code in the layout file will validate it and will render the banner partial.

Examples of page templates in the Korematsu theme

Page with Hero - No page navigation

Default

Default - No Page Navigation

Full Width - No Page Navigation