Metadata manipulator: InsertXmlFromTemplate

Overview

This metadata manipulator generates MODS XML fragments from external Twig templates.

Toolchains

This manipulator can be used with CSV and CONTENTdm toolchains that use the mods\ metadata parsers.

Configuration

To register this manipulator in your toolchain, add an entry similar to the following to the "[MANIPULATORS]" section of your .ini file. The manipulator's configuration signature is:

metadatamanipulators[] = "InsertXmlFromTemplate|null4|/tmp/twigtemplates/related_item.xml"

Parameters

This manipulator takes two parameters:

• The first parameter (required) is a null mapping (described in more detail in the MIK wiki's Mappings file page).
• The second parameter (required) is the absolute path to the Twig template you want to apply to the field.

The null mapping value used as the first parameter is required only to ensure that the manipulator is executed. Unlike standard MIK field mappings, which populate a simple MODS snippet with a single source field's value using the %value% placeholder, this manipulator has access to all metadata fields, as described below.

Also, unlike other entries in a mappings file, mappings for the null value used in the .ini configuration do not take a MODS snippet as the right-hand part of the mapping because the XML generated by the template configured to use that null mapping is used instead of a simple snippet. The left and right sides of the mapping should contain the same value, like this:

null4,null4

Using the example configuration provided above, the output of the template at /tmp/twigtemplates/related_item.xml is inserted into your MODS XML files. The second null4 is required only because MIK mappings must have both a left and right value.

Functionality

The Twig templating engine provides a flexible way to interpolate values into XML templates. For example, a template like this:

<relatedItem type="host">
   <titleInfo>
      <title>{{ RelatedTitle }}</title>
   </titleInfo>
   <identifier type="local">{{ RelatedIdentifier }}</identifier>
   <location>
      <url>{{ RelatedUrl }}</url>
   </location>
</relatedItem>

can generate a MODS fragment like

<relatedItem type="host">
  <titleInfo>
     <title>A Complete Guide to Kittens</title>
  </titleInfo>
  <identifier type="local">kitteng-5601</identifier>
  <location>
     <url>https://kittenguide.com</url>
  </location>
</relatedItem>

This manipulator invokes the specified Twig template and interpolates values from your source metadata to generate MODS XML fragments. In Twig templates, the double curly brackets are called "delimiters" and the string between them is a "variable". In the implementation of Twig templates used in this metadata manipulator, the variables are column headings from your CSV metadata file, e.g.:

"Title","Description","RelatedTitle","RelatedIdentifier","RelatedUrl"
"A very cute cat","This cat is so cute I had to submit it for inclusion in the Complete Guide.","A Complete Guide to Kittens","kitteng-5601","https://kittenguide.com"

Templates should have a single top-level MODS element as their outer-most element, but can include arbitrarily complex markup inside the top level.

Twig features such as control structures, functions, and whitespace control are available. For example, some of rows in your CSV input file contain yyyy-mm-dd dates (stored in the GoodDate field in your metadata) and some rows contain dates in a different format (stored in the NastyDate field), you can create a template that generates a different <dateIssued> element depending on which date is available:

{% if GoodDate %}
  <originInfo><dateIssued encoding="w3cdtf" keyDate="yes">{{ GoodDate }}</dateIssued></originInfo>
{% endif %}
{% if NastyDate %}
  <originInfo><dateIssued keyDate="yes">{{ NastyDate }}</dateIssued></originInfo>
{% endif %}

Note that variables passed into templates by this metadata manipulator are always strings, so Twig control structures that apply to iterators such as {% for item in navigation %} won't be useful.

Using this manipulator with CONTENTdm toolchains

Unlike with CSV metadata, where the variables used in the templates are column headings, when used with CONTENTdm toolchains, the variables are the internal "nicknames" that CONTENTdm assigns to fields. For example, the example template above, used with a CONTENTdm toolchain, might look like this:

<relatedItem type="host">
   <titleInfo>
      <title>{{ titler }}</title>
   </titleInfo>
   <identifier type="local">{{ identir }}</identifier>
   <location>
      <url>{{ identiu }}</url>
   </location>
</relatedItem>

The most common way of determining what the nicknames for specific fields are is to use the CONTENTdm Collection Inspector (see this Cookbook recipe for more information).

You can also look at the raw CONTENTdm metadata stored in your tookchain's temp_directory .ini setting. However, this metadata is stored as a serialized PHP array and may not prove very useful when determining the nicknames to use in your template. The nicknames commonly look like "title", "creato", "subjec", "date", "identi", and "rights", but they can vary depending on what the corresponding human-readable labels are.

Dealing with wrapper elements in the XML generated by this manipulator

MIK's default behaviour is to not repeat wrapper elements such as <name>, <subject>, <titleInfo>, and <extension>. Instead, it combines all children of these elements into a single instance of the wrapper element.

If your Twig template contains wrapper elements that are used elsewhere in the MODS file, such as is the case with the example above with <titleInfo>, you may need to include the following option in your .ini file's [METADATA_PARSER] section. This configuration option will instruct MIK to ignore its default behavior of collapsing top-level wrapper elements:

[METADATA_PARSER]
repeatable_wrapper_elements[] = titleInfo