Converter

While a user has an article open for editing in the Writer, it is represented in the Browser as a collection of nodes with text content and attributes. Everytime the article is to be sent or read from the article repository, it needs to be translated to an XML representation. The XML document structure for an article is well defined by the newsitem-text.xml format specification.

The process of converting to/from nodes and XML is done by Writer, but it takes help from one or many converters. Example of plugins that provide converters are plugins that contribute content to the article text, or add metadata information about the article.

sequenceDiagram
    participant Writer
    participant Article Repository
    participant Core Converter
    participant Plugin Converter 1
    participant Plugin Converter 2
    Writer->>Article Repository: Read article XML
    loop Convert XML to nodes
        Writer->>Core Converter: core XML
        Core Converter-->>Writer: Nodes with data from the XML
        Writer->>Plugin Converter 1: XML that Plugin 1 is reponsible for
        Plugin Converter 1-->>Writer: Nodes with data from the XML
        Writer->>Plugin Converter 2: XML that Plugin 2 is reponsible for
        Plugin Converter 2-->>Writer: Nodes with data from the XML
    end

Conversion process from XML document to nodes in Browser

Telling Writer about your converter

The way to tell Writer that there's a converter to be used for a plugin, is to register it in the package file for the plugin. Read more about the Package file. In the example below, a plugin with the name plugin is registering a converter that is defined in the MyPluginConverter.js file

// MyPluginPackage.js

import {converter} from './MyPluginConverter'

export default {
    name: 'myplugin',
    id: 'com.example.myplugin',
    version: '1.0.0',
    configure(configurator) {
        configurator.addConverter('newsml', converter)
    }
}

The converter should contain a function for converting data from XML to Substance Nodes, called import, and one function for converting from Substance Nodes to XML, called export. Here's an example where the plugin called myplugin is adding content to the article, through the object extension in the writer format. In this example, the plugin implements an object where it is possible to define a question and provide an answer.

The converter can also contain a function matchElement, to let it know if it's responsible for the current node.

// MyPluginConverter.js

const MyPluginConverter = {
    type: 'myplugin',
    tagName: 'object',

    matchElement: function (el) {
        return el.is('object') && el.attr('type') === 'myplugin'
    },

    /**
     * Responsible for converting data from XML to a node in Browser
     */
    import: function (xmlElement, node) {
        node.question = xmlElement.attr('question')
        node.answer = xmlElement.attr('answer')
    },

    /**
     * Responsible for converting data from nodes to XML
     */
    export: function(node, xmlElement) {
        xmlElement.attr({
            question: node.question,
            answer: node.answer
        })
    }
}

export {MyPluginConverter}

An article example with the plugin1 active could look like:

<!-- In this interview series, we have found that the number one answer to our specific question is: -->
<object type="myplugin" question="Do you like hotdogs?" answer="yes, I do"/>