-
Notifications
You must be signed in to change notification settings - Fork 5
Islandora Sync Tutorial
Out of the box Islandora stores the bulk of the data related to assets in the system in the Fedora repository. By taking advantage of Drupal's front end Form API as an interface to Fedora, Islandora provides a robust user friendly method of submitting and updating digital assets while taking advantage of Fedora's set of repository services.
With the assets stored in Fedora, content is exposed to the user via specialized Drupal modules tailored for content in an Islandora repository, referred to as Solution Packs. For example, a Solution Pack might provide specific UI components for exposing images from a Fedora repository in a particular way -- such as deep zoom capabilities or annotation options.
Because content submitted through the Islandora interface is stored in Fedora by default, the standard Drupal conventions of interacting with this content do not apply. As a result, stock Drupal modules that expect data to be in a particular format (perhaps a Node or Taxonomy Drupal data structure) cannot make this assumption with Islandora content.
For example, if one wanted to use a particular slideshow or lightbox image display module out of the box with Islandora content, it would require modification and could not be used as is.
This potentially limits the flexibility of interacting with Islandora content stored in Fedora with standard Drupal modules.
Depending on the use case, mirroring pieces of your content stored in your Fedora repository in Drupal native data structures may provide a solution.
The Islandora Sync module allows a user to select datastreams and pieces of metadata content stored in XML and mirror this content in a matching Drupal Content Type. With a copy of this content in a native Drupal structure, a user may interact with the content as they would with any other Drupal content in this form.
Typical use cases might be:
- Image gallery
- Drupal Views
- Displaying content on map
A brief overview of the Islandora Sync process is as follows:
- A Fedora content model is associated with a Drupal content type
- The fields in the Drupal content type are associated with Fedora datastreams
- XML Metadata datastream elements in Fedora (Such as DC or MODS datastreams) are mapped to Drupal content type fields via XPath
- The Sync process is selected to execute at a particular time (On create, update, or via cron)
There are several limitations of the Islandora Sync module that one should be aware of in order to make appropriate decisions in evaluating for your particular use case.
-
Islandora triggers synchronization process
Hooks to push content from Fedora up to Drupal are contained only in Islandora. This is significant because the assumption is content is being ingested into the system via Islandora. If content is added directly to Fedora, the Islandora Sync hooks will not be triggered. Keep this in mind if you have processes other than Islandora adding content to Fedora.
-
One way sync from Fedora up to Drupal
The Islandora Sync module currently only supports pushing content from Fedora into Drupal. Hooks exist for pushing Drupal only content into Fedora, but this has not been implemented yet.
-
Performance unknown for large data sets
The original use case presented for development was manipulation of slices of collection data. For example, using several Drupal modules to display selected content in an exhibit style view. Performance limitations may appear if attempting to synchronize large numbers (10k+) of items.
The following tutorial will show a step by step process using the stock Islandora VM to construct an Image gallery and slideshow using a popular stock Drupal module.
This walk through was performed on the most recent Islandora VM provided, version 7.x-1.2 of Islandora. If you already have a local installation of Islandora, following the commands should yield the same result, provided the version of Islandora is 7.x-1.2 or above.
This tutorial assumes you have a working instance of Islandora or the most recent download of VirtualBox and a copy of the Islandora VM. All commands were run on the Islandora-7.x-1.2_ubuntu_32bit_vm_v1.ova image.
In your VM terminal window, we will download some setup modules via Drush. In case of the VM machine, the apache user is www-data and to keep permissions we execute commands as this user. This may differ on your local setup.
On your VM or Islandora install, cd to your root Drupal directory
cd /var/www/drupal7
Use Drush to download and enable required modules
sudo -u www-data drush dl relation entity field_collection features field_group relation_select
sudo -u www-data drush en relation entity field_collection features field_group relation_select -y
Move to the module directory for your Drupal install
cd sites/all/modules
Use git to download appropriate modules from github and enable via Drush
sudo -u www-data git clone https://github.com/islandora/islandora_sync.git
sudo -u www-data drush en islandora_sync islandora_sync_field_collection islandora_sync_relation -y
sudo -u www-data git clone https://github.com/discoverygarden/mods_basic_image.git
sudo -u www-data drush en mods_basic_image -y
Use Drush to download and enable our slideshow modules
sudo -u www-data drush dl views_slideshow jquery_update bxslider_views_slideshow
sudo -u www-data drush en views_slideshow jquery_update bxslider_views_slideshow -y
Get additional javascript libraries for bxslider module
cd /var/www/drupal7/sites/all/libraries
sudo -u www-data mkdir bxslider
cd bxslider
Retrieve additional javascript libraries for the slider presentation
sudo -u www-data wget http://bxslider.com/lib/jquery.bxslider.zip
sudo -u www-data unzip jquery.bxslider.zip
sudo -u www-data cp jquery.bxslider.min.js bxslider.min.js
After you have install the modules above, you will have Islandora Sync enabled and installed, plus an example content type to demonstrate synchronizing content using the Basic Image collection.
After install, log into your Drupal installation and navigate to Admin->Structure. You should see an additional content type named 'MODS Image'
Click 'edit' on the MODS Image content type and you'll notice a new tab titled 'Fedora Commons'. This administrative menu contains the sync settings for this particular content type.
The following details are of note:
-
Sync to Drupal / Sync to Fedora checkboxes
Currently, only Sync to Drupal is supported, meaning pulling data from Fedora and populating Drupal with content. Checking Sync to Drupal enables this feature.
-
Sync Timing
The Sync process can be triggered on specific actions in real time, or it may be preferred to batch the sync process to run with cron.
-
Sync Hooks
When should the Sync process be triggered? You may specify when to copy content from Fedora to Drupal, or choose to ignore certain operations.
-
Fedora Content Model to Map
A list of the Fedora Content Models is presents as a selection to map to the Drupal content type. After associating a Fedora Content Model with your Drupal content type, all new items matching this Content Model manipulated in Islandora will be eligible for syncing back to Drupal
files/isynctutorial/2-sync_content_type_fedora_details-1.png
We've seen how to associate a Fedora Content Model with Drupal content types, but we still must specify how to map Fedora datastreams to Drupal content type fields. After selecting 'Manage Fields' on your content type each field will have a 'fedora' label on the far right. We'll look at a simple Image case first. In MODS Image, choose the fedora link on the image entry.
files/isynctutorial/3-sync_field_image.png
You'll be presented the Sync settings for this particular field.
-
Sync with Fedora Commons
The first option is if the sync process should pay attention to this field. Your use case may call for mixing sync'd fields with pure Drupal fields in a content type. An example of this use case might be to use a computed field in Drupal to manipulate data to a format that plays nicely with a module you would like to use.
-
Fedora Commons data structure
Next we must specify which datastream we wish to map to this Drupal field. Currently supported options are Managed Datastream (usually files such as images or audio files), XML value (usually a piece of data in your MODS or DC record in Islandora) or Relationship (a RELS-EXT datastream)
-
Datastream ID
The datastream id in Fedora of the content we wish to map
In the simple case of an Image, we choose Managed datastream and identify the Datastream ID as OBJ. In the Basic Image collection, the image is stored in our Fedora object with this id. This may change depending on the Content Model you are mapping. For example, if we wished to pull over an image from a Large Image collection, we might choose the JPG datastream rather than OBJ. In the case of the Large Image collection, the OBJ datastream refers to the uncompressed TIF, usually in Drupal we probably would prefer the downsized jpeg to work with for slideshows and galleries.
files/isynctutorial/4-sync_field_image_details.png
-
XML XPath Configuration
When mapping a piece of data in an XML file to a Drupal field, we'll choose the XML value option, and specify a datastream that holds XML data. All Fedora objects have a XML Dublin Core record under the datastream ID, and in our example case we have an additional datastream containing an XML MODS file, so we identify our datastream id as 'MODS'
To specify exactly what part of the MODS record we wish to map to the Drupal field and XPath query is used. In our case we are only reading from Fedora, and often these values can be directly cut and pasted from your matching Islandora Forms configuration used to insert the data.
The MODS Image content type has several examples of nesting content and dealing with multiple values in a MODS record.
files/isynctutorial/5-sync_field_genre_details.png
Now that we've looked over the new content type that was added, we're ready to add some content. Any new content associated with the specified content model will be synchronized with Drupal. Existing content already present will not be affected, this is important to realize.
Navigate back to the main page, choose Islandora Repository and select the Basic Image collection.
files/isynctutorial/6-sync_collection_summary.png
Choose the Manage tab, then the 'Add an object to this Collection' link.
files/isynctutorial/7-sync_basic_image_collection_summary.png
Add 3 or 4 Basic Image objects to this collection, filling out the title and uploading the appropriate image format for this collection. After you have completed, choose the content link in your administration menu. You should have several new objects on the Drupal side, where as previously this content was only on the Fedora side of your Islandora instance.
files/isynctutorial/8-content_page_summary.png
At this point, updates to the content on the Islandora side will be reflected on the Drupal side. Changes to the sync'd Drupal fields will be overwritten if the related Islandora object is updated. Non-synchronized fields will remain unchanged.
Now we may interact with this content as we would with any other similar Drupal node.
This section is more of a Drupal exercise, to show a simple slideshow gallery using a popular image module in Drupal.
Under Structure->Views, we'll create a new view to display all content of our new content type, MODS Basic Image.
files/isynctutorial/9-slideshow_view_setup_1.png
Select Continue&Edit.
Under Format, select the link titled Unformatted list and update to Slideshow, and accept the defaults.
files/isynctutorial/10-slideshow_view_setup_2.png
Under Show, select the link titled Content and update to Fields, and accept the defaults.
Under Fields, select Add and search for the appropriate Image field associated with our content type -- titled Content:Image, Apears in node:mods_image. Accept the default settings.
files/isynctutorial/11-slideshow_field_setup.png
You should see your newly added content in the preview pane at the bottom of the View configuration.
Note the path of your view, choose save and navigate to the url. Your slideshow of content synchronized from Islandora is available.
files/isynctutorial/12-slideshow_view.png
At this point, any changes to the items using the Islandora interface will propagate to the existing Drupal objects. If the item is deleted from the Islandora repository, the related Drupal node will also be removed (if specified).
This is a simple use case of using a stock Drupal module, but showcases the power of Islandora sync for splash pages or dynamic content being driven from Fedora which hopefully reduces development and content editors time, while providing options for non-programmers to interact with data from an Islandora repository.