Resources/Guides/Tips for Omeka S custom theme building?

Hi all,

I’m new to Omeka and I’ve been researching the platform for a multi-site exhibits project I’m working on. Omeka S seems to be the ideal version to use, however I find its current selection of themes/templates to be minimal. I’ve been looking into customizing existing themes or even building a new one and there as well comprehensive documentation seems to be scant.

My challenge is not with HTML/CSS (I have experience with structure/layout and styling websites), but understanding the view helpers and functions/configuration needed to call and display content/layout. Basically, the structure of a theme.

Can anyone recommend resources/guides/tutorials/tips/best practices – anything beyond the basic (not particularly instructive…) steps in the current Omeka S documentation – that’s helped them with modifying/building an S theme?


PS - And if anyone from the Omeka team reads this–are there plans to expand documentation on theme building? Even recommended links would be helpful.

1 Like

Documentation for theme writers is an area we know we have to improve.

Do you have a specific idea of what you’d find most immediately useful, or what is most seriously lacking? The structure of a theme in terms of files is one of the few things there’s really anything concrete for.

One piece that was sorely missing was information about representations and how to use them to display data/metadata about records, and that’s a pretty major concept in the themes.

All -
We are slowly wandering a similar path to customize Omeka-S themes. Context: a couple of historians with just enough tech knowledge to be dangerous, are building an omeka-s based platform to hold sharable teaching resources for our campus faculty.

What follows describes our process (very incomplete) and that suggests areas where documentation might help, offered in the spirit of sharing resources that seem to work for us. We’re still very much in the discovery process, but our steps so far are:

  1. Create a place to experiment. We have an institutionally hosted version (which we can’t access at the server level) and we installed a version of Omeka-S on MAMP on a mac laptop for testing. Time: maybe 20 minutes; less if you’ve done this before. The directory we’ve been editing is Applications/ MAMP/htdocs/omeka-s/themes. When we get the theme the way we want it we’ll hand the theme directory contents off to our campus IT people to install for us on our institutional site.

  2. We’re adapting the ‘Cozy’ theme because we want the slide-out menu system, but don’t know enough to write one from scratch that will work with Omeka-S. Of the 4 provided themes, only Cozy has this already built. Also, Cozy allows the most customization from within the Omeka Admin panel using “Edit Theme Settings.”

  3. The files we’re tinkering with so far are: style.css, theme.ini, and layout.phtml. Here’s where to find them in the theme folder (from our MAMP install):

  4. Cosmetic stuff: style.css is the place to tinker with the visual appearance. There’s a fair amount of trial and error to see which elements do what (documentation here would be awesome), but the results are easy enough to see by refreshing a browser window. There is also a module one can install in Omeka-S that allows adding css rules to a site (kindly suggested to us in this thread: Theme/CSS Editing Within Omeka-S?), but without understanding how the style.css elements are defined it is hard to just use the module.

  5. Fonts: it seems these have to be changed in two places. layout.phtml defines what fonts to download. Google’s font site is probably the first stop as you pick your replacement fonts.
    Here’s the line to edit in layout.phtml:
    It would be great to have some docs on what Omeka-s does with these different font weights, types and sizes - I can guess, but a few comments would be great.
    In style.css you’ll then need to change the font everywhere it appears - use search and replace to find them all.

  6. Search Bar: for our project we do not want a search box on each page, and for now it seems we can eliminate it by editing layout.phtml. To eliminate the search bar we commented out this line:

    <?php echo $this->partial('common/search-form'); ?>
  7. What about theme.ini? This seems to preset different values such as the theme name, author, and default values for some of the elements that show up in “Edit Theme Settings.” Mostly these changes appear to users in Admin mode.

So, this is a trial and error project right now, but we’re making progress. For us getting a basic template/theme designed will be enough, since we don’t live for this kind of tinkering and editing. It would be really nice if “Edit Theme Settings” had more comprehensive choices, such as fonts, logo positioning (left, center, right) or check box to show (or not) things like the search bar. Interestingly, there is a similar setting for pagination elsewhere in the Admin interface, but not as part a theme. I suspect that a lot of effective customization could take place without server-level editing if the “Edit Theme settings” had a slightly larger number of options.

This is a bit long, but hopefully helpful to others starting out. Let me also take a minute to think the development team for their outstanding work and patience as this new version rolls out.

All suggestions, corrections, or better ways to do this are most welcome!


The suggestions on further theme settings are much appreciated. We’re always looking for feedback for what people are looking to do, and that’s sometimes hard to come by for themes for whatever reason. Always feel free to bug us about things you can’t do, think you can’t do, or think should be easier.

CSS and elements… there’s a limit to how much of that we’d document probably… there are a lot of elements, and the themes provide some of the markup themselves… typically the web inspector is sufficient to discover the appropriate id/class/selector for an element you’re trying to work with. But I’m open to suggestions here.

We don’t really do much special with fonts. You’re right that you both need to include the proper font (assuming you want to use a webfont) and change the CSS referring to it if you’re changing fonts. The weights are also not really anything special… really it’s down to the theme to use different weights or not in its CSS.

Adding or removing elements from all pages is done in layout.phtml, as you’ve said.

theme.ini is both the just administrative data for the theme directory and Themes page in the admin, as well as holding the definitions for things that are in the Theme Settings form.

Thanks for the quick reply. I suspect the greatest utility will probably come from having a larger number of choices available via “Edit Theme Settings” and in the Admin “Site Settings” page. What do you think about a expanded version of the Cozy theme (think of it like a ‘generic’ theme) with all the possible settings and options. People could turn them on or off as needed, or adapt from the ‘generic’ theme if they felt ambitious and wanted to edit the style.css sheet directly.

Something like:
Header (color, background color)
Main Body (color, background color)
Footer (color, background color)
Menu/Sidebar (color, background color)
Logo for Header (file upload/selection, sizing, page position {left, right, center})
Logo for Footer (file upload/selection, sizing, page position {left, right, center})
Font selection (or maybe that’s a better task for Site Settings).

In the Admin interface the other place where a couple more options would help is in Site Settings. Consider adding:
[ ] Show search box and search icon
[ ] Show breadcrumbs
[ ] Show side menu trigger button
(are these different representations of the same thing? I couldn’t tell from the layout.phtml code. It would be good to have allow only breadcrumbs or only the menu or both. Right now it seems the Cozy theme has both by default.)

For our purposes I’m ok with editing the files direclty as I outlined in my earlier post. But long-term, a set of choices such as these might let most people avoid editing the layout.phtml page or the style.css which is probably a good thing, since much damage could be done there.

Thanks for listening to these suggestions!

I’m eagerly following this thread, and I’d like to chime in and advocate for more theme settings AND for a basic guide to CSS customization in Omeka (something along the lines of what dringrose shared above). I’ve found many Omeka users have to take on what I call “ad hoc” IT roles. I fall into this category. I know just enough to be dangerous – to make basic CSS edits and tweaks – but it takes hours of trial and error. I suspect this is replicated across the Omeka community.

In terms of specific theme enhancements, the biggest issue that comes up constantly with the faculty and students with whom I work – for years now, both in Omeka Classic and S – is better control of image sizes AND more image size options. Despite hours of fiddling, I’ve not been able to figure how to control this properly in Omeka S.

Can you elaborate on the kind of process you’re using to make changes? There’s enough to the CSS that trying to document it comprehensively I don’t think is feasible (plus, it differs from theme to theme), but maybe we can give some more basic guidance for how to make changes. With the browsers’ inspectors, a substantial “trial and error” process shouldn’t be necessary, even if you’re just trying things out.

Could you also clarify what you mean by size control? I’m assuming you mean not so much the “type” of image (square, thumbnail, large/full) but the actual size it appears on the page? It’s true that this used to be more straightforward in (much) older versions of Omeka… the main issue is that the themes are generally responsive now, so they work with multiple screen sizes: this generally means that locking in a specific pixel size for an image isn’t really done anymore.

You still have control over size with CSS, the obvious sizing properties and in particular the sizes of the containers that images are displayed in… but the 1:1 correspondence of the thumbnail constraint size and the displayed size of the image on the page isn’t going to be there.

I’ll offer one.

I’m trying to do a relatively simple change like that discussed in this thread below - in my case wrap site names in bootstrap panels so they flow differently on the screen.

What I can’t find is something that says “to use your custom CSS file add to the top of index.phtml”, or a clear reference to a 3rd party on a themes related pages that explains what it should be.

These are the sorts of pages I’ve looked at:

This is all compounded by a lack of (that I can discern) documentation covering how Omeka S assembles pages - our site has a customised layout.phtml that does not add special classes to yet the home page continues to have class=“minimal” added.
(I’m happy to split this last bit off to a separate discussion if you’d prefer).


The “home page,” if you’re talking in the same way that linked thread does, is kind of its own thing: you don’t control it with your selected theme at all. You can set a site as default, so its front page will become the home page… new since that old thread is a block that lists sites like the front page does, so you can easily make a “front page” site that you can freely style.

Thanks for the suggestion.
We’ll need to do some upgrades to reach 1.3 and its List of Sites block so in the mean time I will continue to investigate what might be causing me trouble in the current template(s).

In case it helps anyone, here is something I’ve just set up in our dev environment - I’m not sure if it’ll reach prod, it depends on if its superseded by the 1.3 upgrade and if 1.3 does what we’re after.
I’m doing this because of the issue I mentioned in passing a couple of posts ago with the tag being written with unwanted CSS classes applied.

Our first discovery is that our custom layout/layout.phtml does not customise omeka/index/index.phtml, only site layout.

We could change the layout/layout route in settings to a specific layout file but that applies the customisation to omeka/index/index.html AND our sites layout.

My current work around is setting layout/layout to a redirector in our local.settings.php

'view_manager' => [
        'template_map' => [
            'layout/layout' => __DIR__ . '/../themes/utas-default/view/layout.php',
            'omeka/index/index' => __DIR__ . '/../themes/utas-default/view/omeka/index/index.phtml',

The contents of which is


$current_request_uri = $_SERVER['REQUEST_URI'];

if ('/' != $current_request_uri) {
} else {

From there the index and site layouts are customised independently - I haven’t had this working long enough to figure out if its causing any extra problems though.

1 Like