README.txt in Views OAI-PMH 7.3

CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Missing features
 * Requirements
 * Recommended modules
 * Installation
 * Upgrade
 * Configuration
 * Dealing with attributes
 * Dealing with multivalued fields
 * Default view
 * Theming and templating
 * Implementing new metadata formats
 * Altering existing metadata formats
 * Maintainers


INTRODUCTION
------------
The Views OAI-PMH module allows the creation of OAI-PMH endpoints, exposing any
data the Views module has access to.

The following metadata formats are supported:

 - Dublin Core (oai_dc)
 
 - IMS Learning Objects Exchange (oai_ilox)
 
 - Interoperability Metadata Standard for Electronic Theses and Dissertations
   (oai_etdms)
 
 - Learning Objects Metadata (oai_lom)
 
 - Learning Resource Exchange (oai_lre)
 
 - Metadata Object Description Schema (mods)
 
 - Érudit.

Other modules may provide their own metadata formats by implementing Drupal-
style hooks.

The 7.x-3.x branch was mainly motivated by the need to support a more complex
metadata format, namely the Metadata Object Description Schema (MODS)
http://www.loc.gov/standards/mods/ . While trying to implement the format, we 
encountered various issues which gradually led us to refactor/rewrite most of 
the module. The changes outlined below should give a good idea of the problems
we wanted to solve.

 * Changes:

   - Simpler architecture and less code. Just two Views plugins (instead of 10),
     a display plugin and a style plugin.

   - No more global variables. Lazy loading of metadata format definitions.

   - Proper hooks allow modules to provide their own metadata formats, and to
     alter the metadata formats provided by other modules.

   - Mapping now uses its own settings data structure instead of hijacking a
     view's field labels.

   - Attributes are no longer global to all elements. The same attribute may now
     appear with different values, on different tags within the same record.

   - More robust XML building, using PHP's DOMDocument class.

   - Logic out of the theming layer.

   - Now impossible to disable the oai_dc metadata format, which is required by
     the OAI-PMH standard.

   - New support for the Metadata Object Description Schema (MODS) format.

   - New support for the Interoperability Metadata Standard for Electronic
     Theses and Dissertations (ETD-MS) format.

   - Include the oai-identifier description container in response to "Identify"
     requests.

   - Metadata prefixes are now configurable.

   - Properly output the view's URL instead of the site's base URL in <request>
     tags.

   - All errors are now detected and reported in the response, as required by
     the OAI-PMH standard, instead of stopping short after the first error. Also
     removed duplicate error messages and made record identifier checks more
     strict.

 * For a full description of the module, visit the project page:
   https://www.drupal.org/project/views_oai_pmh

 * To submit bug reports and feature suggestions, or to track changes:
   https://www.drupal.org/project/issues/search/views_oai_pmh


MISSING FEATURES
----------------

There are missing from the actual version and should be included in
the future.

 * Mising features:

  - Live preview for metadata formats other than oai_dc.

  - Gzip compression.

  - Handling for deleted records.

  - Sets.


REQUIREMENTS
------------

This module requires the following modules:

 * Views (https://www.drupal.org/project/views)


RECOMMENDED MODULES
-------------------

 * Biblio (https://www.drupal.org/project/biblio):
   Improves the module help page showing information about the module drush
   commands.


INSTALLATION
------------

 * Install as you would normally install a contributed Drupal module.
   See: https://www.drupal.org/node/895232 for further information.


UPGRADE
-------

Any views created with the 7.x-1.x or 7.x-2.x module version will be 
incompatible. The mappings of the view fields to OAI-PMH elements will have to 
be manually redone in the views. Backup your data before upgrading!

The structure of the module's theming layer is completely different, so any
theme code (theme functions or template files) made for the original Views
OAI-PMH versions will have to be reworked.


CONFIGURATION
-------------

Anyone familiar with the Views module should quickly feel comfortable with
Views OAI-PMH. Outlined below are the steps required to create a new OAI-PMH
endpoint. Understanding Views concepts such as displays, fields and filters is
required.

 * Configure the module following these steps:

   - Add a new view, with neither a page nor a block display, i.e. with just a
     "Master" display, showing content unsorted (Views OAI-PMH handles the
     sorting). Continue & edit this view.
    
   - Add an "OAI-PMH" display to the view.

   - Edit the Repository name. By default it is filled with the site's name. 
     This name will appear in response to OAI-PMH "Identify" requests.
    
   - Add any desired filter criteria. These will limit what content is available
     from your new OAI-PMH endpoint.
    
   - Add any fields that provide the data that you wish to publish through
     OAI-PMH (for example, "Content: Title", "Content: Body", "Content: Post
     date"). Some things to consider when configuring a field:
  
   - You may uncheck the "Create a label" option, as labels will not be part of
     the OAI-PMH output and will simply be ignored. You may still want to use
     labels for documentation purposes though.
 
   - In the "No results behavior" section, the "Hide if empty" option must be
     checked to avoid empty XML tags or attributes in the output.
 
   - In the "Rewrite results" section, check the "Strip HTML tags" option. HTML
     markup is not allowed in OAI-PMH elements.
 
   - Title fields must have the "Link this field to the original piece of
     content" option disabled.
 
   - Text fields must use the "Plain text" formatter. Again, HTML markup is not
     allowed in OAI-PMH elements.
 
     * Date fields must be formatted according to the requirements of the
       metadata format, e.g. W3CDTF.

     * Link fields and Entity Reference fields must not output links, just plain
       text, e.g. an URL, a title.

   - In the "Format" section, click the "Settings" link. This will take you to
     the "OAI-PMH Style options", where you'll find the mapping interface.
   
   - Enable the desired metadata formats for your new OAI-PMH endpoint. The
     Dublin Core (oai_dc) format is mandatory.
   
   - If desired, edit the metadata prefixes that will be recognized by your OAI-
     PMH endpoint. Note that each prefix must be unique.
   
   - For each enabled format, a table is provided where you may associate each
     field that's been added to the display with an element in that metadata
     format. For example, in the "Field mappings for Dublin Core" table you
     could associate the "Content: Title" field with the "dc:title" element, the
     "Content: Body" with the "dc:description" element, and the "Content: Post
     date" with the "dc:date" element.

   - Configure a path for this display, such as "my-oai-pmh", in the "OAI-PMH
     Settings" section.
  
   - In the "Pager" section, make sure to use the "Full" pager. The specified
     number of items per page will control how many records will appear in an
     OAI-PMH response (harvesters will make multiple requests using resumption
     tokens to get more records).

   - Save the view.
   
   - Optionally, you can test your new endpoint by going to
     http://re.cs.uct.ac.za/ and entering the absolute URL for your display,
     e.g. http://example.com/my-oai-pmh, in the "Enter the OAI baseURL" box, and
     then clicking the "Test the specified/selected baseURL" link (on the right
     side of the page).


DEALING WITH ATTRIBUTES
-----------------------

Some metadata formats require that XML tags have specific attributes, such as a
"language" attribute. Views OAI-PMH allows you to map a field to an attribute:
Just select a target that's prefixed with "(Attribute)", e.g. "(Attribute)
Language".

Sometimes your content does not provide any data for those values, in which
case you can add to the view a "Global: Custom Text" field, which you'll be
able to map to an attribute.

A field that's mapped to an attribute must be positioned above the field that's
mapped to the element that uses the attribute. For example, to generate the
following MODS snippet:

  <language>
    <languageTerm authority="rfc3066">fr</languageTerm>
  </language>
  <name authority="local">
    <namePart>Smith, John</namePart>
  </name>

The view might use four fields (order is important):

 - "Global: Custom text", configured with text "rfc3066"

 - "Content: My language field", which will provide a language code, e.g. "fr"

 - "Global: Custom text", configured with text "local"

 - "Content: My author field", which will provide an author's name, e.g. "Smith,
   John".

Then the view would have the following MODS mappings:

  - "Global: Custom text" mapped to "(Attribute) authority"
  - "Content: My language field" mapped to "language (multiple) > languageTerm"
  - "Global: Custom text" mapped to "(Attribute) authority"
  - "Content: My author field" mapped to "name (multiple) > namePart"

If it wasn't for the second "Global: Custom text" field being mapped to
"(Attribute) authority", there would be no "authority" attribute on the
<name> tag because the first attribute gets consumed by the <languageTerm>
tag, which appears before <name>. Indeed, any field that's mapped to an
attribute is consumed by the first encountered element that allows that
attribute, making that attribute value unavailable to any other elements
further down the list of fields.

Moreover, attributes are assigned depth-first to the target element. For
example, when building the output for the "name (multiple) > namePart" element,
the system first checks if the MODS metadata format allows an authority
attribute on a <namePart> tag. That attribute not being allowed on this tag,
the system then tries with the parent tag, <name>, finds that it is allowed
there, and therefore lets the <name> tag that consume the attribute.


DEALING WITH MULTIVALUED FIELDS
-------------------------------

We usually need multivalued fields to generate multiple tags in the XML output,
one for each value. For example, a multivalued Entity Reference field might
generate the following oai_dc snippet:

  <dc:creator>Brooks, Kevin</dc:creator>
  <dc:creator>Nicci, French</dc:creator>
  <dc:creator>Mason, Matt</dc:creator>

For this to happen, the field must be configured appropriately in the view:

 - Formatter: Title (no link)

 - Multiple field settings > Display all values in the same row: Enabled.

 - Multiple field settings > Display type: Simple separator

 - Multiple field settings > Separator: Any character or character sequence that
   is unlikely to appear in a title.

 - Multiple field settings > Display "all" value(s) starting from "0".

 - No results behavior > Hide if empty: Enabled.

In the mapping interface, the field is then mapped to "dc:creator" (in the
Dublin Core table).

Unless noted otherwise in a mapping's target name, multiple values will
automatically generate multiple leaf nodes in the XML. For example, a
multivalued field that's mapped to "physicalDescription > form" in MODS will
generate a new <form> tag for each value, all under a common
<physicalDescription> parent, as in the following snippet:

    <physicalDescription>
        <form>text</form>
        <form>image</form>
        <form>video</form>
    </physicalDescription>

Some mappings, however, generate multiple nodes higher up in the XML tree. In
those cases, the label "(multiple)" indicates which tag will get repeated. The
following MODS snippet shows the output for a multivalued field that's mapped
to "name (multiple) > namePart":

    <name authority="local">
        <namePart>Brooks, Kevin</namePart>
    </name>
    <name authority="local">
        <namePart>Nicci, French</namePart>
    </name>
    <name authority="local">
        <namePart>Mason, Matt</namePart>
    </name>

In the above example, it is the <name> tag, rather than the leaf, that gets
repeated for each field value. Note that the "authority" attribute gets
repeated as well. As mentioned earlier, an attribute gets consumed by the first
encountered element that allows that attribute. When that element has multiple
values, the same attribute will apply to all of the values.

If a multivalued field is mapped to an attribute, however, the system will
instead try to assign each value to an element whose position with respect to
its siblings in the XML tree matches the value's index. It is thus possible to
output the following MODS snippet:

    <name authority="local" xlink:href="http://example.com/people/brooks-kevin">
        <namePart>Brooks, Kevin</namePart>
    </name>
    <name authority="local" xlink:href="http://example.com/people/nicci-french">
        <namePart>Nicci, French</namePart>
    </name>
    <name authority="local" xlink:href="http://example.com/people/mason-matt">
        <namePart>Mason, Matt</namePart>
    </name>

To generate the above output, the view might have the following three fields
(again, order is important):

 - "Global: Custom text", configured for text "local"

 - "Content: My author field", an Entity Reference field configured with the
   formatter "URL as plain text", and proper settings for a multivalued field.

 - "Content: My author field", another instance of the same Entity Reference
   field, this time configured with the formatter "Title (no link)". Also
   configured with proper settings for a multivalued field.

Then the view would have the following MODS mappings:

 - "Global: Custom text" mapped to "(Attribute) authority"

 - "Content: My author field" mapped to "(Attribute) xlink:href"

 - "Content: My author field" mapped to "name (multiple) > namePart"


DEFAULT VIEW
------------

After the Views OAI-PMH module has been enabled, a new view called "OAI-PMH
endpoint" becomes available. You may review and edit it using Views UI, at 
Administer » Structure » Views. That view provides a basic example for
mapping oai_dc elements to fields provided by the Biblio module 
https://www.drupal.org/project/biblio .

The oai_dc metadata format is mandatory for OAI-PMH compliance. How you map its
elements, however, will depend on your site's structure. If your site does not
use the Biblio module, for instance, you'll have to edit the view, or disable it
and create a new one, then add the required fields and configure the mappings.


THEMING AND TEMPLATING
----------------------

To manipulate the output before it gets rendered as XML, you may implement the
"views_oai_pmh_response" theme hook in your theme. This function receives,
among other arguments, a PHP DOMDocument object containing the XML tree of the
OAI-PMH response. For more details, see the default implementation of
theme_views_oai_pmh_response() in views_oai_pmh.theme.inc.

Field templates are not supported.


IMPLEMENTING NEW METADATA FORMATS
---------------------------------

Any module can provide additional metadata formats to Views OAI-PMH. This
requires implementing two hooks:

 * hook_views_oai_pmh_metadata_format_info()

   - This hook returns the OAI-PMH metadata formats supported by the module. It
     simply returns an array where each value is the identifier of a metadata
     format provided by the module, e.g. "oai_dc", "my_oai_format".

  * hook_views_oai_pmh_metadata_format()

   - This hook receives a metadata format identifier as argument and returns an
     instance of the metadata format object corresponding to that id. That
     object's class must be a subclass of the views_oai_pmh_format class, which
     you can find in includes/format.inc. Have a look at the includes/formats
     directory for implementation examples.

Views OAI-PMH itself implements those two hooks to provide its own formats. You
can find these implementations in the views_oai_pmh.module file.


ALTERING EXISTING METADATA FORMATS
----------------------------------

A module may implement the hook_views_oai_pmh_metadata_format_alter() hook to
alter any of the metadata formats provided by other modules. The function's sole
argument is an object of class views_oai_pmh_format. The implementor may
check that object's id attribute to identify the format.


MAINTAINERS
-----------

Current maintainers:
 * Adrian Cid Almaguer (adriancid) - https://www.drupal.org/u/adriancid


This project has been sponsored by:

 * Consortium on Electronic Literature (CELL) http://eliterature.org/cell/
 * Minnesota Historical Society http://www.mnhs.org/index.htm
 * The Open University http://www.open.ac.uk
 * Support for metadata format EruditArticle (in the 7.x-3.x branch) has been
   developed has part of the CO.SHS project (co-shs.ca) and sponsored by the
   Canada Foundation for Innovation (Initiative sur la cyberinfrastructure –
   premier défi – premier concours). It was implemented by Laboratoire NT2
   (nt2.uqam.ca).