CustomMutation

Type: Function

Fonto offers many generic operations, covering most operations that can be performed on typical XML documents. However, some specific situations may require more direct access to the XML structure. In this case, developers may consider writing a custom mutation.

A custom mutation is a callback, registered under a unique name using addCustomMutation. When the custom mutation is invoked by an operation (using a step of type custom-mutation/), the callback is invoked with the following arguments. Please refer to the corresponding topics for more details on the API of each argument:

The custom mutation callback may modify the XML through the provided blueprint and can change the selection by modifying selection according to the needs of the application. It should always return an instance of the CustomMutationResult class, indicating the result of the operation. In addition to this result, the changes made to the blueprint should be valid for the mutation to succeed. This validation is automatically performed if the callback returns CustomMutationResult.ok().

Many standard mutation primitives are accessible from the fontoxml-base-flow package, which is part of the base platform. For creation of new elements and other nodes, use the Document node of the targeted document as a factory.

See the documentation on createElementNS for more information.

Although the Nodes obtained through the blueprint and selection contain mutation methods, never use these to mutate the XML document directly. Always use the blueprint API.

Arguments

# Name Type Description
1. argument StepData

The step data passed to the operation step.

2. blueprint Blueprint

Blueprints provide a layer over the XML DOM in which changes can be made without affecting the actual document(s)

3. format Format

Provides access to the schema, including validation.

4. selection BlueprintSelection

The current selection, or the range as specified by the overrideRange argument (See OverrideRange).

Returns

Type: CustomMutationResult

The result of this mutation. Note that returning ok() is ignored when validation fails.

Was this page helpful?