addExternalValue

Type: Function

How to get addExternalValue?

JavaScript

import addExternalValue from 'fontoxml-selectors/src/addExternalValue.js'

Provides a way to expose external data to XPath.

Calling this function creates both a getter function on the XPath side as well as a setter function on the JavaScript side, which together can be used to pass data from JS to XPath. Updating this data (by calling the setter) will automatically invalidate any observed XPath queries that depend on it.

This API can be thought of as registering a map of values. Both getter and setter accept a single key argument to identify the value in the map to use.

To ensure the proper conversion of values between XPath and JavaScript, make sure to pass appropriate XPath types for both the key argument as well as the returned values. To ensure efficient lookups, they key argument should always be a single value of an atomizable type, i.e., xs:string, xs:boolean or any subtype of xs:numeric or of node(). For the return value, any type can be used that can be converted from JavaScript to an XPath XDM value, in the same way as this happens for return values in registerCustomXPathFunction.

When given a key that does not match one of the values that has been set, the getter returns the defaultValue. This is set to null by default, which is converted to the empty sequence. Note that not all types allow this value - either set the returnType to a type that does, e.g., by adding the ? suffix, or define a more appropriate defaultValue that is allowed by the returnType.

The setter returns a Promise that resolves when the value has been updated in XPath. This update always happens asynchronously; immediately invoking the getter after calling the setter will return the previous value.

To free up memory, the setter can be called with undefined as the value to remove the given key from the map. This will cause the getter to return the default value for future requests for that key.

As with other APIs that register XPath functions, make sure this is called before using the registered function in any XPath expressions. In particular, when using this in the selectors in a configureSxModule.js. A good pattern here is to export the setter from a JavaScript module, and import that module in the configureSxModule.js.

Example

JavaScript

const setExternalValue = addExternalValue(
		'http://app',
		'getMyExternalValue',
		'xs:string',
		'xs:string',
		'default-message'
);

myNotifier.addCallback(() => {
		// The setter is asynchronous and returns a promise to indicate when the value has been updated
		setMyExternalValue('my-key', myManager.getNewValue()).then(() => {
			// The getter will now return the new value
		});
});

// Wherever you want to use the value
const value = evaluateXPathToString(
		'Q{http://app}getMyExternalValue("my-key")',
		null,
		domFacade
)

// The getter can safely be used in an observed query, which will update when the setter is used
const observer = indexManager.observeQueryResults(
		'Q{http://app}getMyExternalValue("my-key")',
		null,
		{ expectedResultType: evaluateXPath.STRING_TYPE }
);

// This also works in a React component
const value = useXPath(
		'Q{http://app}getMyExternalValue("my-key")',
		null,
		{ expectedResultType: XPATH_RETURN_TYPES.STRING_TYPE }
);

See the Custom XPath/XQuery invalidation guide for more examples.

NOTE: This method does not lend itself to pulling in external data when it is first requested -- instead, it is designed for pushing in external data before a query that uses it is executed.

In complex cases where you need to set external data based on XML nodes (e.g. retrieving data from your CMS based on the elements that refer to it in a loaded document) please contact our support team.

Arguments

  1. namespaceURI

    (Required)

    Type: String

    The namespace used to register the getter function in XPath.

  2. localName

    (Required)

    Type: String

    The local name used to register the getter function in XPath.

  3. argumentType

    (Required)

    Type: String

    The XPath type of the key argument, must be an atomizable type.

  4. returnType

    (Required)

    Type: String

    The XPath type of the return value.

  5. defaultValue

    (Required)

    Type: any

    The value returned from the getter for keys for which no value has been set.

    Default value

Returns

Type: Function

Arguments

Returns