Starting with Omeka 1.2, theme writers have the ability to add configuration options to themes. These options are stored in the Options table in Omeka, and are called using the get_theme_option helper in the theme.
Adding a Configuration Form to your Theme
Before end-users can configure a theme, you must include a config.ini
file in your theme. This config file uses methods from Zend Form to create a configuration form available in the Omeka admin. Adding this file will make a "Configure" button appear next to the name of the currently-active theme.
Each field should be indicated by prepending a 'fieldname' before all the options in the config.ini
file.
- fieldname.type: The type of field. Possible values include 'file', 'text', 'textarea', 'checkbox', and 'select'.
- fieldname.options.label: The form label for the field
- fieldname.options.description: The explanatory text for the field. This will display below the field in the form
Example 'checkbox' field type
The following creates a field called 'display_featured_item' that uses a <input type="checkbox">
input.
display_featured_item.type = "checkbox" display_featured_item.options.label = "Display Featured Item" display_featured_item.options.description = "Check this box if you wish to show the featured item on the homepage." display_featured_item.options.value = "1"
Example 'file' field type
The following creates a field called 'logo' that uses a <input type="file">
input.
logo.type = "file" logo.options.label = "Logo File" logo.options.description = "Choose a logo file. This will replace the site title in the header of the theme. Recommended maximum width for the logo is 500px." logo.options.validators.count.validator = "Count" logo.options.validators.count.options.max = "1"
Example 'select' field type
The following creates a field called 'style_sheet' that uses a <select>
input.
style_sheet.type = "select" style_sheet.options.label = "Style Sheet" style_sheet.options.description = "Choose a style sheet" style_sheet.options.multiOptions.spring = "Spring" style_sheet.options.multiOptions.summer = "Summer" style_sheet.options.multiOptions.autumn = "Autumn" style_sheet.options.multiOptions.winter = "Winter" style_sheet.options.value = "winter"
Example 'textarea' field type
The following creates a field called 'homepage_text' that uses a <textarea>
input.
homepage_text.type = "textarea" homepage_text.options.label = "Homepage Text" homepage_text.options.description = "Add some text to be displayed on your homepage." homepage_text.options.rows = "5" homepage_text.options.attribs.class = "html-input"
Using Configuration Options in your Theme
Once a user has saved some configuration options, you can then use the values for those options anywhere in your theme. The easiest way to do this is to define a PHP variable using the get_theme_option helper, like so:
<?php $optionValue = get_theme_option('Option Name'); ?>
In another example, the Rhythm theme includes a custom function inside the custom.php
file for retrieving and using the 'Style Sheet' option:
function rhythm_get_stylesheet($styleSheet = null) { if (!$styleSheet) { // If the 'Style Sheet' option has a value, use it. Otherwise, use 'fall' $styleSheet = get_theme_option('Style Sheet') ? get_theme_option('Style Sheet') : 'fall'; } return $styleSheet; }
This code will return the value for get_theme_option('Style Sheet'). If the option doesn't have a value, it will use 'fall'.
The theme then uses this function in header.php
to call the appropriate style sheet:
<link rel="stylesheet" media="screen" href="<?php echo html_escape(css(rhythm_get_stylesheet())); ?>" />