Extending Exhibit Builder 3
Exhibit Builder 3 allows other plugins to add their own layouts.
Placing layouts within your plugin
The new Exhibit Builder layouts use the same “views” system as other Omeka pages and views.
In any plugin (including the Exhibit Builder itself), layout views go in
the path views/shared/exhibit_layouts
.
Registering a new layout
Exhibit Builder provides a filter named exhibit_layouts
. To add a new
layout, you must hook into this filter and add some information about your
new layout. You need to decide three things:
ID: an internal name for the layout and the name of the layout folder
Name: the admin user-facing name for the layout
Description: the admin user-facing description of the layout
The ID is the key into the array of layouts, and the name and description are keys in an internal array. A filter implementation looks like this:
public function filterExhibitLayouts($layouts) {
$layouts['new-layout'] = array(
'name' => 'New Layout',
'description' => 'A new layout.'
);
return $layouts;
}
Basic structure of an exhibit layout
Each layout has its own folder under the path mentioned above. The folder name
is the layout’s ID, which will be used internally by the Exhibit Builder to find
and store the layouts picked by the user. An ID is simply a text string, and
the convention is that layout IDs be ASCII, lowercase, and hyphen-separated:
sample-layout
, not SampleLayout
or SampleLayout
.
Inside the layout folder, there are several files with predefined names that the Exhibit Builder will look for:
- form.php
The PHP view file for the admin-side display of a form for the user to configure attachments, text, and options for a single block with this layout.
- layout.php
The PHP view file for the public-side display of a single block with this layout.
- layout.css
A CSS stylesheet that is automatically loaded when this layout is used on a public page.
- layout.png
A PNG preview image for the layout. This image is displayed on the admin side when the user is selecting the layout to use. To fit with the images for the other layouts, the image should be 260 pixels wide by 140 pixels tall.
Your views can reference and use other files with names of your choosing, but the ones specified above are required and must be at the given locations.
The layout form – form.php
The page block that the layout is being used on is accesible in the form.php
view as $block
. This block object is passed to the form helpers and is
used when form entries are created manually.
Attachments
The attachment interface is added by a simple helper:
echo $this->exhibitFormAttachments($block);
Text
The text entry box is also added by a simple helper:
echo $this->exhibitFormText($block);
Options
Options are handled differently by each layout, so there is no standard form helper for them. Instead, you should use the built-in Zend form helpers to create form inputs for your layout options.
Internally, options are stored as a JSON-serialized array. Exhibit Builder
automatically saves any options that are sub-keys of the options
key
in a block form.
Each block needs a different form name “stem,” indexed by block. So, when you’re manually creating form inputs, you need to get this stem from the block object:
$formStem = $block->getFormStem();
The pre-existing options are also available on the block object:
$options = $block->getOptions();
With those pieces of data, you can manually create a form input that will reflect the status of an option. For example, a simple text input for an option named ‘some-option’:
echo $this->formText($formStem . '[options][some-option]', @options['some-option']);
The layout view – layout.php
The layout view has four variables assigned to it.
$attachments
An array of the attachment objects for items the user has attached to this block.
$text
A string, containing the HTML text the user entered for this block. This text is filtered and can be output directly.
$options
An array of the options the user selected for this block.
$index
An integer, the index within the page of the current block.
Attachments
Single attachments
There are two main helpers for displaying attachments on a layout. The first is
simply used for displaying a single attachment using Omeka’s file display
functionality. This helper is the exhibitAttachment
helper.
The exhibitAttachment
helper takes 4 arguments, but only the first,
$attachment
, is required.
$attachment
The attachment object to display. This should be retrieved from the
$attachments
array assigned to the view.$fileOptions
An array of options for displaying the attached file. See the Usage section of the
file_markup
documentation for examples of display options.$linkProps
An array of HTML attributes that will appear on the link to the item. This link will appear if an attachment is for an item with no files, or if the
$forceImage
argument is true.$forceImage
A boolean argument. If true, the normal
file_markup
-style display will not be used, and insteadfile_image
will be. This can be useful for displaying attachments in grids or other structures where differing sizes and display methods would be unusable. This argument defaults to false.
The simplest possible example of using this helper just passes the attachment:
foreach ($attachments as $attachment):
echo $this->exhibitAttachment($attachment);
endforeach;
Attachment galleries
The second helper is the exhibitAttachmentGallery
helper. The gallery helper
takes an array of attachments, and displays them in a gallery format.
exhibitAttachmentGallery
takes three arguments, only the first of which,
$attachments
, is required.
$attachments
An array of attachments to display a gallery of.
$fileOptions
An array of file display options: see the explanation for the previous helper. If no
imageSize
option is given, the square thumbnail size is automatically selected by this function.$linkProps
An array of HTML attributes for the link around each displayed attachment. See the explanation for the previous helper.
Again, the simplest possible example simply passes the attachments. A gallery of all attachments on a block in square thumbnail format is simple:
echo $this->exhibitAttachmentGallery($attachments);
Custom displays
Of course, you may wish to use the attached items and files in a completely different way than the normal Omeka file display. In that case, you can directly access the Item and File objects for each attachment object, and work on them however you wish:
foreach ($attachments as $attachment):
$item = $attachment->getItem();
$file = $attachment->getFile();
endforeach;
Layout style - layout.css
The layout.css file is automatically loaded when the layout is used on a page. Any given page can contain many different layouts simultaneously, so you need to take some care that you don’t write styles that will interfere with other layouts.
To help with keeping styles separate, Exhibit Builder automatically wraps
your layout output in a div with the class layout-<your layout id
. In
general, styles in layout.css should start with that class selector as the
first component of every selector.
Including extra assets
Some scripts, styles or other content can be included directly in layout.php.
But, some content may need to be placed in the <head>
, or may only be
included in the page once. For these scenarios, Exhibit Builder provides a
hook to add content to the head for exhibit pages. Note: layout.css is
automatically included, so you don’t need to write anything to include it.
The hook is called exhibit_builder_page_head. It sends two arguments, the
View object $view
, and $layouts
, a keyed array of the layouts in use
on the page being shown. You can check for your layout ID in the keys of
$layouts
and include whatever content your layout needs:
public function hookExhibitBuilderPageHead($args) {
if (array_key_exists('my-layout', $args['layouts'])) {
queue_js_file('my-script');
}
}