Node

There are many different types of Nodes built into Substance, e.g BlockNode, FileNode, TextBlock, Container, PropertyAnnotation, and probably more. Each Node-type has different utility and usage, but what they all have in common is their ability to transport data.

For simplicity this document will focus on the BlockNode. Check the Substance source code for information about all the other types.

Defining a Node

What's needed to define a Node is a schema for the Node's data structure. In its simplest form, a node inherits some functionality from a parent Node, and then defines its properties.

Simple BlockNode Example:

// MyAmazingBlockNode.js
import {BlockNode} from 'substance'

class MyAmazingBlockNode extends BlockNode {}

MyAmazingBlockNode.schema = {
    type: 'myamazingplugin',
    uuid: {type: 'string', optional: false},
    message: {type: 'string', optional: true},
    year: {type: 'number'},
    isCool: {type: 'boolean'}
}

export {MyAmazingBlockNode}

Once a Node is defined, and registered in the Package file, the Converter responsible for your plugin is able to import and export data from your Node and the underlying NewsML document.

Extending a Node with utility

Sometimes you might want to manipulate the data stored in the Node directly, or supply utility functions for your plugin which returns your data in a specific format. This is easily added to the defined Node class, and then accesses directly from the Component registered to that Node.

Node Utility Function Example:

// MyAmazingBlockNode.js
import {BlockNode} from 'substance'

class MyAmazingBlockNode extends BlockNode {

    safeMessage() {
        return this.message ? this.message : 'Oh dear, there is no message!' 
    }

}

MyAmazingBlockNode.schema = {
    type: 'myamazingplugin',
    message: {type: 'string', optional: true},
}

export {MyAmazingBlockNode}

// MyAmazingComponent.js
import {Component} from 'substance'

class MyAmazingComponent extends Component {

    render($$) {
        const {node} = this.props
        return $$('div').append(node.safeMessage())
    }
}

export {MyAmazingComponent}

Extending a Node with Generic Properties

The introduction of Generic Properties from version 6.0.0 of the Digital Writer, means that nodes should now extend the Container or BlockNode from the Writer, instead of the Substance class.

Extending the node classes from the Writer for content nodes, allow the Writer to use predefined fields for this content.

To support generic properties there are 2 requirements on the Node class.

It must import and extend the Container or BlockNode from writer and the class extends this.

import {BlockNode, Container} from 'writer'

class ImageGalleryNode extends Container {

It must have the GenericPropsComponent in the render function to control where to show the properties.

import {BlockNode, Container} from 'writer'

el.append([
    $$(GenericPropsComponent, {
        node: this.props.node,
        isolatedNodeState: this.props.isolatedNodeState,
        pluginName: 'im-imagegallery'
    }).ref('genericProps')
])

The input properties for the GenericPropsComponent is:

Node: The Node object, typically in this.props.node.
isolatedNodeState: This is the current state of the Node UI, meaning if it is active or not in the editor. For the nodes, this is typically available in this.props.isolatedNodeState.
pluginName: This is used to map the field configuration to decide which fields to show.

For content Nodes that support generic properties, it is possible to setup which fields to show in the Digital Writer configuration.

"propertiesConfig": {
    "showByDefault": ["im-ximimage"],
    "properties": [
        {
            "name": "alignment",
            "title": "Alignment",
            "plugins": [
                "im-imagegallery",
                "im-ximimage"
            ],
            "values": [
                {
                    "title": "Left",
                    "value": "left"
                },
                {
                    "title": "Right",
                    "value": "right"
                },
                {
                    "title": "Center",
                    "value": "center"
                }
            ]
        }
    ]
}

If the plugin name from the component is in the list of plugins for any of the properties, those properties will show up for the Content in the editor.

The values will be added to the NewsML under the object output for the plugin, as a properties Node:

<object id="1234..." uuid="024e..." type="x-im/content-part" title="Vivamus...">
  <properties>
    <property name="alignment" value="center"/>
  </properties>
    ...
</object>

PreviousComponent NextConverter