A configuration for either toData or toView transformation.

While processing, the following steps will be sequentially invoked for a given node:

  1. prepare
  2. imported
  3. importedWithChildren
  4. appended

Note that for a given node, first all prepare steps are executed for a given node, then all imported steps, and so on. Thus, do not expect by default that a node handled in prepare step comes unchanged to the next step imported.

interface RuleSectionConfigBase {
    appended?: AppendedFunction;
    id?: string;
    imported?: ImportedFunction;
    importedWithChildren?: ImportedFunction;
    prepare?: PrepareFunction;
    priority?: PriorityString;
}

Properties

appended?: AppendedFunction

This method operates on a just appended child node. As it is called while processing the parent node, the source node reference in context refers to the original representation of the parent node.

Note that while in general parent should be of type ParentNode and child of type ChildNode, previous processing may have provided a different state. Thus, you may require applying corresponding type checks first.

id?: string

Optional ID for a given configuration. Possibly useful for debugging purpose.

imported?: ImportedFunction

This method operates on a just imported node to the target document. It is neither attached to DOM and does not contain any child nodes.

Note, that information provided via context (such as the original source node) must not be manipulated.

Also note that previous processing may have already adapted or even exchanged the imported node. So, it may make sense to do some checks on the original node instead, like, if a given rule is applicable.

Typical behaviors done at this stage:

  • Adapt attributes.
  • Exchange node by another (just by returning a new one).

You may also append child nodes in this state. Original child nodes will then be appended. Nevertheless, structural changes are best applied in the importedWithChildren step, as you have full control of the structure then.

Alternative to this, you may add children to the original DOM as part of the prepare step.

importedWithChildren?: ImportedFunction

This method operates on an imported node to the target document. While it is not attached to DOM yet, children already got converted and appended.

Note, that information provided via context (such as the original source node) must not be manipulated.

Also note that previous processing may have already adapted or even exchanged the imported node. So, it may make sense to do some checks on the original node instead, like, if a given rule is applicable.

prepare?: PrepareFunction

This method may operate on the source node prior to importing it into the target document. This may be useful if the source API is richer than available later in processing. Like, for to data mapping, the data view may contain HTMLElement providing access to HTMLElement.dataset, while the XML element in the target document later is a raw Element.

Note that some limitations apply to actions performed in this stage:

  • You must not relocate or remove the node handed over.
  • You must not modify any DOM nodes outside the given node.

Thus, it is safe, for example, to add or remove child nodes or attributes in this stage.

priority?: PriorityString

Priority in which the given rule section is executed. Defaults to priority normal.