An Islandora Solution Pack that allows for ingesting and viewing arbitrary types of XML files. This solution pack is not intended to replace others that offer more comprehensive and specialized tools for XML formats like EAD and TEI. Instead, its focus is on being a general-purpose solution for making a variety of types of XML content accessible. It offers a simpler solution to the goals of the overly complex Islandora Feeds module, the original motivation for which can be found in this Islandora Google group discussion.
Examples of this solution pack in action include:
- Canada's Early Women Writers (using the one-XLST-stylesheet-per-collection approach)
- A collection of Wordsworth's and Coleridge's Lyrical Ballads marked up in TEI (using Michael Joyce's custom viewer).
This solution pack provides tools for ingesting and viewing XML OBJ files in Islandora much like those offered by other solutions packs. These files could be TEI, EAD, DocBook, SVG, or locally defined XML. Some differences between this solution pack and most others include:
- It does not generate any derivatives. However, the 'modules' subdirectory contains an example module that illustrates how you would generate derivatives.
- It is designed specifically to delegate presentation of XML OBJ content to Islandora viewer modules. That being the case, it does present raw XML content to end users if no viewer is configured and also supports fairly sophisticated processing of OBJ datastreams using XSLT stylesheets.
- Even though the solution pack manages XML data, it does not use the Islandora XML Forms interface to allow editing of the OBJ datastream. MODS datastreams attached to the object can be edited as in other solution packs. The XML Solution Pack offers only a rudimentary way of editing an XML file - just a plain text area. Users who need to modify an XML file using more sophisticated tools must download the object's OBJ XML datastream, edit it outside of Islandora, and upload it using the "Replace" link provided within the object's Datastreams tab. The editing feature in this module is intended for fixing typos, etc. and performs no well-formedness checking or validation on the edited XML content.
Users may upload a thumbnail image and default XSLT stylesheet for each XML object. Objects managed by this solution pack can also have a MODS datastream just like other Islandora objects do.
The admin settings for this solution pack, available at
admin/islandora/solution_pack_config/xml, let site administrators determine:
- the location of a default thumbnail image for use if no object-specific thumbnail exists (this default thumbnail can also be applied in batch ingests)
- the ID of the datastream that needs to be present to render metadata and description at the bottom of the object display.
- the Islandora viewer for objects managed by this solution pack
Standard Drupal permissions are available for allowing users to upload object-specific thumbnails and object-specific XSLT sytlesheets.
Rendering the OBJ datastream using XSL Transformations
The module allows the use of XSLT 1.0 stylesheets to render the XML to users in the following ways:
- Users may upload a stylesheet when they create an object managed by this solution pack. The stylesheet becomes a datastream on the object with the datastream ID 'RENDER_STYLESHEET' and is applied to the XML OBJ file when users view the object.
- Owners of collections may upload an XSL stylesheet as a datastream on a collection object. If this datastream has an ID of 'RENDER_STYLESHEET', it is used for all XML objects that are members of the collection (unless a member object has its own RENDER_STYLESHEET datastream).
- If neither of the above is true, the XML file is simply escaped and rendered betweem HTML <pre> tags, or, if a viewer module (like the one included with this solution pack) is enabled and configured, it renders the XML output.
In cases 1 and 2, parameters can be passed to the XSLT stylesheet via URL query parameters, e.g.
http://host/islandora/object/islandora:29?foo=true&bar=Mark. The values of
bar would then be accessible in the render stylesheet as follows:
<xsl:param name="foo"></xsl:param> <xsl:param name="bar"></xsl:param> <xsl:if test="$foo='true' and $bar"> <div>Hello <span><xsl:value-of select="$bar"/></span></div> </xsl:if>
The stylesheet parameter 'pid' is always passed to the stylesheet, and is accessible within stylesheets as
$pid. It does not need to be declared as a pararameter.
More information on using parameters in RENDER_STYLESHEETs is available.
Rendering the OBJ datastream using viewers
Note that if a viewer is enabled, the XML OBJ datastream content is not styled with the RENDER_STYLESHEET XSLTs as described above. However, third-party viewers are free to use the RENDER_STYLESHEET or any other stylesheet they wish.
Metadata and description display
If an XML object has a MODS datastream, its content and the "Description" content will appear at the bottom of the object display (including custom metadata display configurations), just as in other Islandora solution packs. If an object has no MODS datastream, no metadata or description will appear. A datastream ID other than 'MODS' can be configured in the module's admin settings.
Objects managed by this module cannot be loaded using the Islandora Batch, but a custom Drush-based loader is available in the
modules subdirectory. Its README provides details on preparing content and ingesting it.
Indexing XML content
By default, all content is slurped into one field for simple search as it is with any other XML datastream, but it is possible to configure FedoraGSearch to index specific fields so they can be used in advanced search forms and in Solr-based metadata displays. To have FedoraGSearch do this:
- Create an XSLT stylesheet to create the Solr fields. An annotate example is provided in this module's
extras/sample_stylesheetsdirectory. Place your transform in your
tomcat/webapps/fedoragsearch/WEB-INF/classes/fgsconfigFinal/index/FgsIndex/islandora_transformsdirectory (or wherever your FedoraGSearch configs are located) with the other stylesheets.
- Include the stylesheet from within your
foxmlToSolr.xsltstylesheet, following the pattern of other stylesheets in the
- On reindexing, or on ingest of new simple XML objects, each of the fields created in your stylesheet will be added to the object's Solr document. You will not need to modify your Solr schema or configuration for this to work.
Some features that would be useful include:
- sample render XSLT stylesheets for common types of XML objects, like TEI, EAD, DocBook (partially addressed here), etc.
- checks for well formedness on XML and XSLT files as they are uploaded
- checks for validity against a specific schema or DTD
- Possible solution is to attach a schema file to the collection object as a datastream
- additional viewers that present the XML content in interesting ways
- caching of the rendered versions of large or expensive-to-render XML files (which may be done best in viewers).
Development and feedback
Pull requests are welcome, as are use cases and suggestions.