Custom layouts for Exhibit Builder 3.0

There is documentation about adding layouts to EB 3.0 for plug-in creators, but not for theme creators. Is this at all possible? Is a custom plug-in required to register the layout with Exhibit Builder?

I am looking to be able to, for example, display the item title above an exhibit attachment. Or, to let my users select a layout which puts the caption next to the thumbnail in a gallery instead of below it, rather than doing it through conditional stylesheets (or hard coding it in a text block).

If you want to create a new layout, it has to be from a plugin. Public theme files aren't loadable in the admin side in the way that they'd need to be to get stuff like the forms to work.

Themes can override the display of any layout, however, including those added by plugins.

In that case, are there any very-extremely-basic tutorials for creating 2.x plugins? I've seen the Read the Docs documentation, but it's not so useful for total newbies.

Hmm, the "Plugin Basics" section there does seem to be pretty lacking in the, well... basics.

For a situation like this, you'd be looking at a very simple plugin.

Your file structure would look like:

  • AwesomeLayout/
    • AwesomeLayoutPlugin.php
    • plugin.ini
    • views/
      • shared/
        • exhibit_layouts/
          • awesome/

The plugin.ini is pretty self-explanatory, and it's mostly geared for distribution anyway, so something very minimal should be sufficient:

name = "Awesome Exhibit Layout"
author = "sheepeeh"
version = "1.0"

The "main" code file of the plugin derives its name from the plugin's folder name, and you just tack "Plugin.php" onto the end. So, for this excellently-named example, the file is AwesomeLayoutPlugin.php. This file actually does have some reasonably decent and up-to-date documentation. For something this small the file will be very simple, and you can draw it right out of the Exhibit Builder 3 extension docs. The filter you need to use is exhibit_layouts:

class AwesomeLayoutPlugin extends Omeka_Plugin_AbstractPlugin
    protected $_filters = array('exhibit_layouts');

    public function filterExhibitLayouts($layouts)
        $layouts['awesome'] = array(
            'name' => 'Awesome Layout',
            'description' => 'A new awesome layout.'
        return $layouts;

From there it should just be a matter of creating the files mentioned in the Exhibit Builder 3 docs: form.php, layout.php, and layout.css. In this example, those would all go under views/shared/exhibit_layouts/awesome.

Oh, and, as far as working with the layout files themselves, particularly if they're just starting out as tweaks to the stock layouts, I'd say going directly to the originals would be a good move.

A final thing, if you're planning to make several layouts, they can all be added by a single plugin, just by having their folders all in your plugin's views/shared/exhibit_layouts, and tacking each one onto $layouts in your filterExhibitLayouts method. There's no limit on the number of layouts any plugin can add.

That's extremely helpful, thanks!

Here's what I actually wound up with:

Revisiting this with a slightly more complicated modification.

People would like to be able to add custom titles to items in exhibits, but have them look the same as they do with the DC Title. This is sort of possible by having folks edit the HTML for the caption and putting the title in a classed DIV, but it would be preferable to alter the item attachment form to have an extra textfield for caption title. (Not everyone is comfortable writing code, even if it's very simple.)

Adding fields for Exhibit blocks is pretty straightforward and covered in the documentation, but adding fields for attachments is not.

Is this even possible without forking Exhibit Builder and writing a custom page-form.php?

I've messed around with a plugin that loads a custom views/helpers/ExhibitFormAttachments.php which calls exhibits/custom_attachment.php, but without much luck. Stuff loads without errors, but I can't seem to add an additional field.

I've gone ahead and tried out a simple change to enable support for choosing the file type/size used within the gallery for the normal bundled Gallery layout. More or less, it keeps the layout and markup exactly the same, just tweaking the CSS slightly to account for non-square images. The relevant layout option is "Gallery file size."

Anybody interested can checkout the latest master on Github of the Exhibit Builder; it doesn't have any increased requirements or database changes.

I couldn't make anything sensible with the exhibit builder - it doesn't seem to be very flexible, but maybe my requirements are too specific. Anyway, I wrote myself a plugin that uses its own shortcode to display all items in a collection the way I wanted