Omeka supports multiple output formats, which allows users to access the information on a page or about an item in different formats. While Omeka comes with several different formats out of the box, plugins can also add their own custom output formats. This use case will introduce you to the define_response_contexts and define_action_contexts filters and how they're used to create new output formats. This use case is based on an actual plugin that adds an output format: the MediaRss plugin for the CoolIris image viewer.
Files You'll Create in this Use Case
- MediaRss/ (folder)
- plugin.ini
- plugin.php
- views (folder)
- shared (folder)
- items (folder)
- browse.rssm.php
- items (folder)
- shared (folder)
Use Case Steps
1. Create a plugin.ini file for the MediaRss plugin:
[info] name="MediaRSS plugin for the Cooliris Image Viewer" author="Center for History & New Media" description="Adds a MediaRSS feed to your page templates, making them available to the Cooliris Firefox extension." link="http://omeka.org/codex/Plugins/MediaRss_for_Cooliris" omeka_minimum_version="1.0" omeka_tested_up_to="1.0" version="1.0" tags="visualization, rssm"
2. Output formats work the following way: you'll visit a URL in Omeka, and append ?output=format to the URL, and if applicable, Omeka will return a custom data output. An examples of this feature in the core is the RSS2 output format. If you are browsing items (youromekasite.com/items/browse/), and append ?output=rss2 to the URL, Omeka will display an RSS feed instead of an html page. Similarly, this plugin will create an rssm feed (which is an RSS feed with media embedded).
You'll use define_action_contexts to let Omeka know where to use your custom data output. In our example, we're specifying only where the ItemsController is being used with the browse action. Adding 'rssm' to the context for that action, Omeka will now respond differently based upon that URL being called:
<?php add_filter('define_action_contexts', 'media_rss_action_context'); function media_rss_action_context($context, $controller) { if ($controller instanceof ItemsController) { $context['browse'][] = 'rssm'; } return $context; }
3. Once you've defined the Action Contexts, you must specify Omeka's response context for the output. In our example, we'll also add our code to the plugin.php file to call the define_response_contexts hook, and execute code that specifies the rssm suffix and xml content-type header. The content-type for your output format will vary based upon what form your output is in:
add_filter('define_response_contexts', 'media_rss_response_context'); function media_rss_response_context($context) { $context['rssm'] = array('suffix' => 'rssm', 'headers' => array('Content-Type' => 'text/xml')); return $context; }
4. The final step is to create a view which renders when an output format is called. This file will be saved within the views/shared/items/ folder, and named browse.rssm.php. Note the structure of the file name: a reference to the action and the output's suffix.
The following code is in the browse.rssm.php file, and simply iterates through the items on a browse page, adding them to the structure of the XML file.
<?php echo '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'; ?> <rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:atom="http://www.w3.org/2005/Atom"> <channel> <title><![CDATA[<?php echo settings('site_title'); ?>]]></title> <link><![CDATA[<?php echo abs_uri(''); ?>]]></link> <description><![CDATA[<?php echo settings('description'); ?>]]></description> <?php while($item = loop_items()): if (item_has_files()): while(loop_files_for_item($item)): $file = get_current_file(); if ($file->hasThumbnail()): ?> <item> <title><![CDATA[<?php echo item('Dublin Core', 'Title'); ?>]]></title> <media:description><![CDATA[<?php echo item('Dublin Core', 'Description'); ?>]]></media:description> <link><?php echo abs_item_uri(); ?></link> <guid><?php echo $file->getWebPath('thumbnail'); ?></guid> <media:thumbnail url="<?php echo $file->getWebPath('thumbnail'); ?>"/> <media:content url="<?php echo $file->getWebPath('fullsize'); ?>" type="<?php echo $file->mime_browser; ?>"/> </item> <?php endif; endwhile;?> <?php endif; endwhile;?> </channel> </rss>
That's it! You can use Output Formats for any type of controller, and other content-types beyond XML