gatsby-transformer-ceteicean

Transforms XML files for Custom Elements support via CETEIcean.

Each element in an XML file gets prefixed with a given prefix based on the element's namespace.

To facilitate use with CETEIcean, the transformer generates a list of prefixed elements and data-origname and data-origatts attributes are added to each element.

TEI XML is supported by default and TEI elements will be prefixed with tei-.

Supported extensions: .xml, .odd

Install

npm install gatsby-transformer-ceteicean

Note: You also need to have gatsby-source-filesystem installed and configured so it points to your files.

How to use

In your gatsby-config.js:

module.exports = {
  plugins: [
    `gatsby-transformer-ceteicean`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `./src/data/`,
      },
    },
  ],
}

Where the source folder ./src/data/ contains the .xml files.

How to query

You can query the nodes using GraphQL like this:

{
  allCetei {
    edges {
      node {
        original
        prefixed
        elements
      }
    }
  }
}

which would return:

{
  allCetei: {
    edges: [
      {
        node: {
          original: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<TEI xmlns=\"http://www.tei-c.org/ns/1.0\"/>",
          prefixed: "<tei-TEI data-xmlns=\"http://www.tei-c.org/ns/1.0\" data-origname=\"TEI\" data-origatts=\"xmlns\">",
          elements: [
            "tei-TEI"
          ]
        },
      },
    ]
  }
}

Transformations

Custom transformations of the XML can be queued to be performed before (applyBefore) or after (applyAfter) the default processing described above. You can pass an array of functions to perform transformations. Functions will receive the following object, should modify parts of it, and MUST return the same structure:

{
  original: '', // the XML as a string
  prefixed: '', // the data as a string after default processing
  elements: [] // list of elements generated by the default processing
}

If you're processing the XML before the default processing, you'll want to change original; on the other hand, if you're processing after the default processing, you'll want to change prefixed. Changing elements is not advisable.

You can write transformation scripts in Node, or call out to other processing via API calls or command line to perform XSLT transformations.

const xsltTransform = require("./xsltTransform.js")

const postTansform = (obj) => {
  // perform some transformation
  const prefixed = obj.prefixed.replace(/\s+/g, ' ')

  return {
    original: obj.original,
    prefixed,
    elements: obj.elements
  }
}

module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-ceteicean`,
      options: {
        applyBefore: [xsltTransform],
        applyAfter: [postTransform],
      }
    }
    ...
  ],
}

Namespaces

Non-TEI namespaces can be set on the plugin via options:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-ceteicean`,
      options: {
        namespaces: {
          "http://www.music-encoding.org/ns/mei": "mei",
          "http://dita.​oasis-open.​org/​architecture/​2005/": "dita"
        }
      }
    },
    ...
  ],
}