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.

For a complete list of available operations, refer to the Operation API documentation.

A custommutation @ fontoxml-base-flow/src/addcustommutation.js is a callback registered under a unique name using addcustommutation @ fontoxml-base-flow/src/addcustommutation.js. These can then be invoked as an operation step of type custom-mutation.

This guide will use an example custommutation @ fontoxml-base-flow/src/addcustommutation.js which is used to cycle through different states of text casing. You can find the recipe for this custommutation @ fontoxml-base-flow/src/addcustommutation.js in our Recipes section.

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

define([
	'fontoxml-base-flow/CustomMutationResult'
], function (
	CustomMutationResult
) {
	'use strict';

	return 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 @ fontoxml-base-flow/src/custommutationresult.js.ok() or custommutationresult @ fontoxml-base-flow/src/custommutationresult.js.notAllowed() must be returned.

Register the CustomMutation

Once you are done writing the custommutation @ fontoxml-base-flow/src/addcustommutation.js it needs to be registered under a unique name. This is done in an install.js file using the addcustommutation @ fontoxml-base-flow/src/addcustommutation.js function.

install.js

JavaScript

define([
	'fontoxml-base-flow/addCustomMutation',

	'./convertTextCase'
], function (
	addCustomMutation,

	convertTextCase
	) {
	'use strict';

	return function install () {
		addCustomMutation('convertTextCase', convertTextCase);
	};
});

Use the CustomMutation in an operation

Using a custommutation @ fontoxml-base-flow/src/addcustommutation.js 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 @ fontoxml-base-flow/src/addcustommutation.js 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"
		}
	}
}