Metadata formats

The steps to create a new metadata format class are:

1. Create a new file in the local (or client for Axiell supplied metadata formats) format directory. Name the file after the metadataPrefix of the metadata format that it implements and use a php file extension. For example: oai_dc.php
2. Open the file with your favourite editor. As the metadata format is written in the PHP programming language we must include PHP opening and closing tags at the beginning and end of the file:

   <?php
       …
   ?>
   

3. Each class must extend the BaseMetadataFormat class so we have to specify the location to the file that contains that class:

   require_once WS::$shared . '/BaseMetadataFormat.php';
   

4. Begin the class definition. We must specify the class name in a variable $class and then specify the class itself. The class name should be the name of the metadataPrefix followed by an underscore followed by the name of the format directory, i.e. local or client. We must extend the BaseMetadataFormat class:

   $class = 'oai_dc_local';class oai_dc_local extends BaseMetadataFormat
   {
       …
   }
   

   Note: You must append the format directory name to the class name, for example oai_dc_local (or oai_dc_client for Axiell supplied metadata formats).

5. Define the class constructor. In the constructor you must call the parent (BaseMetadataFormat) constructor with four parameters, the metadataPrefix, schema and metadataNamespace that identify the format and the version of the format that you are implementing:

   public function __construct()
   {
     parent::__construct('oai_dc',
         'http://www.openarchives.org/OAI/2.0/oai_dc.xsd',
         'http://www.openarchives.org/OAI/2.0/oai_dc/',
         '2.0');
   }
   

6. Define the getColumnsByModule function. This specifies the modules and columns to be retrieved from the EMu CMS. The function must return an associative array that has module names as keys and an array of column names as values:

   public function getColumnsByModule()
   {
       $columnsByModule = array
       (
           'emultimedia' => array
           (
               'DetSubject_tab',
               'DetPublisher',
               'MulDescription',
               'MulMimeFormat',
               'MulMimeType',
               'MulTitle',
           ),
       );
       return($columnsByModule);
   }
   

   Note: The columns irn, AdmDateInserted, AdmTimeInserted, AdmDateModified and AdmTimeModified are automatically added for each module so you do not have to specify them.

   See Specifying columns for more details.

7. Define the writeMetadata function. The function actually outputs the XML metadata record section. The function must accept two parameters, an EMu module name $name and an array $row. The parameter $name is the name of a module specified in the getColumnsByModule function. The parameter $row is an associative array of column names to column values for a single EMu record:

   public function writeMetadata($name, array $row)
   {
       $this->writer->startElement('oai_dc:dc');
       $this->writer->writeAttribute('xmlns:oai_dc',
       'http://www.openarchives.org/OAI/2.0/oai_dc/');
       $this->writer->writeAttribute('xmlns:dc',
       'http://purl.org/dc/elements/1.1/');
       $this->writer->writeAttribute('xmlns:xsi',
       'http://www.w3.org/2001/XMLSchema-instance');
       $this->writer->writeAttribute('xsi:schemaLocation',
       'http://www.openarchives.org/OAI/2.0/oai_dc/' .
       'http://www.openarchives.org/OAI/2.0/oai_dc.xsd');
   
       $date = $this->getDateInserted($row);
   
       $this->writer->writeElement('dc:date', $date);
       if ($this->hasValue($row, 'MulDescription'))
           $this->writer->writeElement('dc:description',
               $row['MulDescription']);
   
       if ($this->hasValue($row, 'MulMimeFormat'))
           $this->writer->writeElement('dc:format', $row['MulMimeFormat']);
   
       if ($this->hasValue($row, 'DetSubject_tab'))
       {
           foreach ($row['DetSubject_tab'] as $subject)
             $this->writer->writeElement('dc:subject', $subject);
       }
   
       if ($this->hasValue($row, 'MulTitle'))
           $this->writer->writeElement('dc:title', $row['MulTitle']);
   
       if ($this->hasValue($row, 'MulMimeType'))
           $this->writer->writeElement('dc:type', $row['MulMimeType']);
   
       $this->writer->endElement();
   }
   

   See Writing metadata for more details.

   Note: You should always check that a value for a column in the $row variable exists before trying to output it as XML, otherwise your output may be invalid. The BaseMetadataFormat class provides the hasValue method for this purpose.

8. Add the metadataPrefix of the new metadata format to the ws.ini configuration file supportedFormats option.

Note: Full metadata format examples can be found in the Appendices.

The steps to modify an existing metadata format class are:

1. Create a new file. As for Creating a new metadata format.
2. Open the file. As for Creating a new metadata format.
3. As we are extending an existing metadata format, we have to specify the location of that class:

   require_once WS::$base . '/common/formats/oai_dc.php';
   

4. Begin the class definition. We extend the existing metadata format:

   $class = 'oai_dc_local';class oai_dc_local extends oai_dc
   {
       …
   }
   

5. Unless we need to redefine the schema and metadataNamespace that identifies the format or the version of the metadata format we are extending, there is no need to define a class constructor. If you want to redefine the metadataPrefix then you should be Creating a new metadata format.
6. Define the getColumnsByModule function. As for Creating a new metadata format.
7. Define the writeMetadata function. As for Creating a new metadata format.

The columns specified in the getColumnsByModule function can be more than simple column names. It is also possible to:

• Retrieve columns from modules to which the current record attaches.

  For example, suppose that the Catalogue module documents the creator of an object as an attachment (to a record in the Parties module) in a column called CatCreatorRef. If the Catalogue module is searched, it is possible to get the creator's last name for each Catalogue record in the result set as follows:

  'CatCreatorRef.NamLast'
  

  This technique can be extended to retrieve data for more than one column:

  'CatCreatorRef.(NamTitle,NamLast,NamFirst)'
  

• Retrieve columns from records that attach to the current record.

  For example, to retrieve information from a set of Catalogue records which attach to the current Parties record via the Catalogue's CatCreatorRef column, specify:

  '<ecatalogue:CatCreatorRef>.(irn,TitMainTitle)'
  

• Rename columns.

  It is possible to rename any column when it is returned by adding the new name in front of the real column being requested, followed by an equals sign. For example, to request data from the NamLast column but rename it to last_name, specify:

  'last_name=NamLast'
  

  The $row variable will contain an element called last_name rather than NamLast.

• Group nested table columns.

  Grouping allows an association between columns to be reflected in the structure of the data returned. To group the columns, surround them with square brackets:

  '[DocIdentifier_tab,DocMimeType_tab,DocMimeFormat_tab]'
  

  The $row variable will contain an element, called group1, where each corresponding row of the tables specified in the group is listed together, for example:

  [group1] => Array
  (
      [0] => Array
      (
          [DocMimeFormat_tab] => tiff
          [DocMimeType_tab] => image
          [DocIdentifier_tab] => image.tif
      )
      [1] => Array
      (
          [DocMimeFormat_tab] => jpeg
          [DocMimeType_tab] => image
          [DocIdentifier_tab] => image.thumb.jpg
      )
  )
  

  as opposed to the ungrouped example:

  [DocMimeType_tab] => Array
  (
      [0] => image
      [1] => image
  )
  [DocIdentifier_tab] => Array
  (
      [0] => image.tif
      [1] => image.thumb.jpg
  )
  [DocMimeFormat_tab] => Array
  (
      [0] => tiff
      [1] => jpeg
  )
  

  By default, groups are given a name of group1, group2 and so on, which can be changed easily enough, for example, we can change the group name to multimedia:

  'multimedia=[DocIdentifier_tab,DocMimeType_tab,DocMimeFormat_tab]'
  

  Any of the methods for specifying columns listed in the IMu PHP documentation here can be used.

The BaseMetadataFormat class property writer is an instance of the PHP XMLWriter class and can be accessed by any class that extends the BaseMetadataFormat class. When defining a metadata format's writeMetadata function, the writer property can be used to output any arbitrary XML. The XMLWriter class defines a number of methods for writing XML:

• startElement: start an XML element tag.
• writeAttribute: write an XML attribute name and value.
• text: write an XML text node.
• endElement: end an XML attributes tag.
• writeElement: start an XML element tag, write a text node and end the XML element tag.

For example, the following methods:

$this->writer->startElement('start');
$this->writer->writeAttribute('name', 'value');
$this->writer->text('this is some text');
$this->writer->endElement();

will output the XML:

<start name="value">this is some text</start>

and the following method:

$this->writer->writeElement('start', 'this is some more text');

will output the XML:

<start>this is some more text</start>

It is your responsibility to produce valid XML output, although the XMLWriter will automatically escape predefined entities in any text output. See the PHP XMLWriter documentation for more details.

As it is possible to use all of the facilities of the PHP programming language, the options for writing XML are very flexible.

It is possible to output static (hard coded) text or mix static and dynamic text:

$this->writer->writeElement('dc:publisher', 'The National Museum');
$this->writer->writeElement('dc:identifier',
    'http://nationalmusuem.com/collection?object=' .  $row['irn']);

We can conditionally output text:

if ($this->hasValue($row, 'DetPublisher') && $row['DetPublisher'] == 'NM')
  $this->writer->writeElement('dc:publisher', 'The National Museum');

We can also output entirely dynamic content:

if ($this->hasValue($row, 'DetPublisher'))
  $this->writer->writeElement('dc:publisher', $row['DetPublisher']);