How to create a custom mutation

This is a guide on creating and using CustomMutations. These are used to manipulate the XML and should only be used if none of the existing operations can be used.

A CustomMutation is a callback registered under a unique name using addCustomMutation. These can then be invoked as an operation step of type custom-mutation.

Create the callback

Create a new file for the callback which will be used as a CustomMutation. This file needs to return a function.

convertTextCase.js

JavaScript

import CustomMutationResult from 'fontoxml-base-flow/src/CustomMutationResult.js';

export default function convertTextCase(argument, blueprint, format, selection) {
    return CustomMutationResult.ok();
}

As the example above shows instead of returning a boolean value to indicate whether the custom mutation was successful CustomMutationResult.ok() or CustomMutationResult.notAllowed() must be returned.

See the CustomMutations API documentation for the arguments passed to a CustomMutation.

Register the CustomMutation

Once you are done writing the CustomMutation it needs to be registered under a unique name. This is done in an install.js file using the addCustomMutation function.

install.js

JavaScript

import addCustomMutation from 'fontoxml-base-flow/src/addCustomMutation.js';
import convertTextCase from './convertTextCase.js';

export default function install() {
    addCustomMutation('convertTextCase', convertTextCase);
}

Use the CustomMutation in an operation

Using a CustomMutation within an operation is done by adding a step of type: custom-mutation/CUSTOM_MUTATION_NAME.

While the example below show the usage of a CustomMutation as the only step of an operation it can also be used as one of multiple steps.

operations.json

JavaScript

{
	"set-word-casing": {
		"label": "UPPER CASE/lower case",
		"description": "Converts selected text to all uppercase / all lowercase / capitalize each word",
		"keyBinding": "Shift+F2",
		"steps": {
			"type": "custom-mutation/convertTextCase"
		}
	}
}