tldr: Neatline makes it possible to create separate themes for individual exhibits, which is useful if you want to host a collection of self-contained Neatline projects on a single site. To get started, fork the exhibit starter theme, which abstracts out the style, layout, and UX of the Project Gemini over Baja California exhibit.
One of the coolest but most under-documented features in Neatline is the ability to create separate themes for each individual exhibit. Since Neatline exhibits are just one particular type of “view” inside of Omeka, it’s always been possible to customize the styling and layout at the level of the Omeka theme. Changes the the Omeka theme, though, propagate to all the exhibits on the site. In many cases, this is ideal - if you have a collection of closely-related Neatline projects, all part of the same thematic umbrella, it makes sense that they should all look more or less the same. For examples of this, check out Jeremy’s beautiful Astrolabe and Neatscape themes for Omeka, which were designed with Neatline projects in mind.
I’ve held off on documenting this publicly because I wanted to be sure that the file structure and Javacsript APIs used in the themes worked well at scale - but at this point it’s all pretty battle tested, and I’m curious to see what other folks can come up with!
Getting started: Creating the theme directory
Neatline themes are created as directories that sit inside of the Omeka theme. For any given exhibit, Neatline will look for a theme directory that has the same name as the “URL slug” of the exhibit, the unique, plain-text identifier used to form the end of the exhibit’s public-facing URL. So, imagine you’ve got an exhibit called “Test Exhibit,” with a URL slug of
test-exhibit. To create a theme for the exhibit, create a directory called
test-exhibit at this location relative to the root of your Omeka theme:
Anatomy of a Neatline theme
Neatline themes consist of just four files:
style.css to add custom CSS to the exhibit. Neatline loads this as the last stylesheet on the page, after the Omeka CSS and after the CSS provided by the Neatline core (which, if you want, can be omitted from the page by providing a custom
show.php template - see below).
style.css can be anything from a handful of simple rules to change fonts or colors up to a complete redesign of the page.
The cool thing about this architecture is that snippets of code in the
script.js file can hook directly into this messaging system and interact with Neatline just as if they were included in the core codebase - Neatline literally won’t know the difference. There’s really no limit to what you could do here - the entire Neatline editing environment, for instance, is implemented as a single module (containing lots and lots of nested sub-modules), and could theoretically be grafted onto Neatline completely inside of an exhibit theme. This makes it possible to wrap up a Neatline exhibit in pretty much any kind of interface without having to modify the internals.
That said, in most cases you’ll probably just need a few little snippets to add in some visual bells and whistles, or to manage complex layout tasks that are tough to accomplish in CSS. For example, here are a few snippets I used in the Project Gemini over Baja California project:
Position the text container on the left side of the screen and fill the height of the window:
Add an NProgress-powered loading bar to the page:
Implement custom zooming buttons:
Add a “Loading Tiles…” spinner that displays when WMS imagery is being loaded from Geoserver:
For an example of a fully-fledged module, which follows the file layout conventions of the Neatline core, take a look at the
Lines module in the Gemini theme, which intercepts events broadcast by NeatlineText and draws the little yellow lines between the text and the map.
By default, all Neatline exhibits are displayed using the
show.php that ships with the plugin. If you create a file called
show.php in the exhibit theme, though, Neatline will use that file in place of the default. This makes it possible to completely customize the structure of the markup in any way you want. For example, if you look closely at some of the Jacascript examples above, you’ll notice that in a couple of places the code is selecting elements (things like
$('div.narrative')) that aren’t actually templated anywhere in the default
show.php, which looks like this:
This works, though, because I’m providing a custom
show.php template that provides those elements (e.g., see the
#wms-loader element down near the bottom):
Last but not least, Neatline makes it possible to override the template that’s used to generate the metadata output for items displayed inside Neatline exhibits. By default, Neatline uses a simple template that pretty much just follows the layout of the regular item “show” pages in Omeka:
But, imagine you had an exhibit that was filled with items that represent photographs, and, for the sake of cleanliness and visual economy, you just want to display the item title and the image thumbnail. Just drop in a new
item.php template that does exactly what you need:
And Neatline will automatically use that template instead of the default. What if you need different templates for different items, though? For example, imagine that you actually have two types of items in the exhibit - the images, which just need the title and thumbnail, but also a set of letters, which are structured as “Text” type items with the transcriptions of the documents entered into the “Text” field. So, how to display both types of items in the exhibit, without resorting to a weird, Frankenstein template that accommodates both?
First, add tags to the records in Neatline:
Then, just create two template in the exhibit theme - one called
item-image.php (the same as above), the other called
item-letter.php. In the letter template, just display the title and text:
Neatline will automatically use the tag-specific templates for any records tagged with
letter, and fall back to the unadorned
item.php template for records that aren’t tagged.
script.js into separate files? One good solution is to use a task runner like Grunt to concatenate multiple source files into the
script.js files, which, instead of being edited directly, become compiled payload files that are updated automatically by the task runner.
To make it easy to get started, I’ve created a little starter theme, based on the theme used for the Project Gemini over Baja California project, with all of the configuration and file structure in place to build out themes for exhibits that use the NeatlineText extension. This includes all of the layout, styling, and UX interactions from the Gemini project, like the little yellow lines that wire up the text with the map.
Just fork the repo, clone it into your Omeka theme, and theme into the sunset!