Plugins/FedoraConnector

About FedoraConnector

FedoraConnector was created by the Scholars' Lab and makes it possible to use objects from a Fedora Commons repository inside Omeka for exhibits and pages. This will permit users to ingest, comment on, annotate, and curate objects housed in a Fedora repository while using the simple, easy-to-learn Omeka interface. This plugin will not, however, allow you to manage your Fedora Commons-based repository objects.

Prerequisites

Required Yum or Aptitude Packages

  • php-xml

XML processing is required to interact with the Fedora repository through its REST API.

An Active Fedora Commons Repository

This plugin assumes that your Fedora repository is active and accessible, either through localhost (the default) or the web. Currently, FedoraConnector can only interact with Fedora servers that place no authorization on an object's datastreams, i. e., it does not save usernames and passwords for accessing data remotely. Please refer to Fedora Commons documentation for installing, configuring, and running a digital repository.

Download

Installing and Configuring

  1. Checkout from svn or download/extract zipped package to omeka/plugins (see Installing_a_Plugin).
  2. Install FedoraConnector on the Settings->Plugins page.
  3. Use the plugin configuration page to set the datastreams to omit from the list of available Fedora datastreams, separated by commas. Default: RELS-EXT,RELS-INT,AUDIT

Usage

The plugin creates two tabs: Fedora Servers and Fedora Objects.

Fedora Servers

Use the Fedora Servers page to add new or edit existing servers. This section will also enable the user to set the default Fedora server, which will appear selected by default in the Add Datastreams section (discussed below). Upon plugin installation, a default server is set: http://localhost:8080/fedora/ which assumes Fedora Commons is running on the local machine on which Omeka is also installed.

Fedora Datastreams

A Fedora datastream is a digital object that represents or is associated with an intellectual object. For example, a digitized photograph may have three datastreams: a digital image, a Dublin Core XML file, and a MODS metadata file which contains more than the basic information encoded in DC. More than one datastream can be associated with an Omeka item. For example, a thumbnail and larger sized image my be datastreams associated with a single Fedora object.

Adding a datastream to an Omeka item is a fairly simple process. In the Add/Edit Item page, a new left-hand menu option has been added by the plugin, "Fedora Datastream." Clicking on this option will display a table of the datastreams currently attached to the object, if any, and an option to add another.

Add a Datastream

  1. Click Add
  2. Select the server from the drop down menu and input the Fedora PID into the text input, and then click Submit. The PHP script queries the Fedora Server and receives the list of available datastreams (minus those omitted from the Config) to populate a new form.
  3. Select one or more datastreams to attach with checkboxes. Use the drop down menu to select the XML datastream that best represents the intellectual object's metadata. DC is selected as default. Click Submit.

Import Object Metadata

  1. Return to the Fedora Datastreams tab.
  2. The Object Metadata column in the table records the ID of the datastream that records the Fedora object's intellectual metadata. If an Importer (see below) has been written for that type of XML datastream, an Import link will appear. A Dublin Core (DC) Importer has already been written, as has a MODS Importer. The MODS to Dublin Core crosswalk is provided by the Library of Congress. Click the link to import the metadata from Fedora into the Omeka Item metadata.

Datastreams can be deleted from this page as well. If the datastream is of the "image/*" mime-type, a thumbnail will be rendered under the Preview column.


Listing Datastreams in Admin Views

You may wish to list an Omeka Item's Fedora datastreams in its admin show action in an info panel, like Tags or Collection is displayed.

  • Open admin/themes/default/items/show.php for editing.
  • Scroll down to the div#info-panels. Insert the code below between the divs where ever you choose, for example, between the Tags and File Metadata.
 
    <div class="info-panel">
    	<h2>View Fedora Datastreams</h2>
    	<?php echo list_fedora_datastreams($item); ?>
    </div>

Displaying Datastreams in Public Views

Datastreams may be displayed in public views in one of two ways. A single datastream may be rendered from a function that calls its ID (and optionally, an array() called $options which may contain further rendering instructions) or every datastream associated with an item can be rendered in succession with the function:

<?php echo render_fedora_datastreams_for_item($item->id); ?>

The above code can be inserted into items/show.php for your currently selected theme.

The render_fedora_datastreams_for_item() function loops through each datastream associated with the Omeka Item ID and calls render_fedora_datastream ($id, $options=array()). render_fedora_datastream() accepts the unique ID of the datastream in the FedoraConnector_Datastream table and an array of options that may include further rendering instructions. Within this function is a PHP Switch/Case scenario based on the mime-type of the datastream. Handlers for "image/jp2" (the code is specific to the University of Virginia Library's own implementation and probably does not apply to other institutions) and "image/jpeg" are included.

The Case calls a function that is included in Disseminators.php. A disseminator, in Fedora terms, is a function or method for displaying a certain type of datastream. The format is as follows: "fedora_disseminator_" . mime-type (minus the forward slash symbol '/').

In Simple Pages:

<?php echo render_fedora_datastream(1); ?>

can be inserted into the Textarea Input to render the datastream at that position. The function renders the datastream with the ID of 1. The table under the Fedora Datastreams admin tab is useful for displaying information and thumbnails for each datastream recorded in Omeka.

Extending the Plugin's Functionality

Disseminators

Disseminators are rendering handlers for certain mime-types and/or datastream types. Two functions are included in Disseminators.php, which is located within the FedoraConnector plugin folder. As mentioned previously, the naming convention for disseminator functions is "fedora_disseminator_" . mime-type (minus the forward slash symbol '/').

The disseminator for image/jpeg is a good example of a simple function that can also be applied to other image mime-types such as image/gif and image/png.

//image/jpeg
function fedora_disseminator_imagejpeg($datastream,$options){
	$db = get_db();
	$server = fedora_connector_get_server($datastream);
	$url = $server . 'objects/' . $datastream->pid . '/datastreams/' . $datastream->datastream . '/content';
	$html = '<img alt="image" src="' . $url . '"/>';
	return $html;
}

The function gets the server URL associated with this datastream and assembles a REST call in the $url variable. The $url is set the src attribute of <img>.

The image/jp2 disseminator is more complex and applies the U.Va.'s impementation of a adore-djatoka service call bound to a Fedora service, djatoka:jp2SDef. Despite the function's specificity toward that institution, it illustrates the way the $options array can be used to issue instructions to the service to return variable image sizes based on the strings "thumb" and "screen."

Importers

Import functions are located in Importers.php. Two are included. The naming convention for these functions is as follows: "fedora_importer_" . Name of datastream (case sensitive!). Dublin Core (DC) is a universally required datastream. MODS is widely used, but not absolute to Fedora repositories.

Datastreams that record object metadata are XML, so Importer functions make heavy use of DomDocument and DOMXPath.

Like disseminator functions, a url variable is generated from the datastream's server and several strings that form a REST call to the XML datastream, which is loaded into DomDocument for further processing.

FedoraConnector/TeiDisplay Integration

As of December 2010, the TeiDisplay plugin integrates with FedoraConnector plugin functions (if the plugin is installed) to render TEI datastreams directly from a Fedora repository. The plugins assume a Text Encoding Initiative XML datastream is designated the id "TEI" in Fedora. This can be modified in TeiDisplay/plugin.php tei_display_install() and FedoraConnector/plugin.php render_fedora_datastream(). Like Omeka Files, TEI files can be configured for segmental/entire display and custom stylesheets.