registerNodeStatus

Type: Function

How to get registerNodeStatus?

JavaScript

import registerNodeStatus from 'fontoxml-families/src/registerNodeStatus.js'

Registers a node status component.

Use the StatusQuery CVK option to match certain statuses with a node.

See below for several examples of using this API, including one using the StatusQuery CVK option.

Use this API in an install.js file.

Using the default component

JavaScript

// The simplest option is to only specify a label to use with a certain id.
registerNodeStatus('needs-review', 'Review');

// Or you can customize the default status badge component with some props:
registerNodeStatus('needs-review', 'Review', {
    componentProps: {
        // These props are defined by the default component. Source code below.
        label: 'Review',
        backgroundColor: 'state-message-error-color',
        clickOperation: 'scroll-node-into-view',
        tooltipContent: 'This document needs review.'
    }
});

Combining with CVK's statusQuery

Also see the StatusQuery CVK option for more info.

JavaScript

// A powerful option is to register one (or more) node statuses:
registerNodeStatus('needs-review', 'Review');

// And then only show that particular node status for elements where the `statusQuery` returns
// the id of the registered node status.
// Note, like any CVK related API, this line should be in a configureSxModule.js file instead of
// an install.js where the call to registerNodeStatus() belongs.

// It is possible to have a node in multiple statuses. Just return multiple strings to do so:
configureProperties(sxModule, 'self::topic', {
statusQuery: `(
if (title = "review") then "needs-review" else (),
if (name(.) = "topic") then "topic-status" else ()
)`
})

DefaultStatusBadge component source code

This is the source code from the default status badge component, this is used if you do not specify any options, or only the componentProps option.Below this are instructions for using a custom badge component if you want to change anything else.

JavaScript

import PropTypes from 'prop-types';
import React, { useCallback, useMemo } from 'react';

import useOperation from 'fontoxml-fx/src/useOperation.js';

import { Flex, Label } from 'fds/components';
import { applyCss, color } from 'fds/system';

const baseStyles = applyCss({
	padding: '10px 4px',
	borderRadius: '2px',
	height: '1rem'
});


function DefaultStatusBadge({
	backgroundColor,
	clickOperation,
	label,
	tooltipContent,
	contextNodeId,
	hierarchyNodeId
}) {
	const operationData = useMemo(() => ({ contextNodeId, hierarchyNodeId }), [
		contextNodeId,
		hierarchyNodeId
	]);

	const { executeOperation } = useOperation(clickOperation, operationData);
	const handleClick = useCallback(
		event => {
			if (!clickOperation) {
				return;
			}

			event.stopPropagation();
			event.preventDefault();
			executeOperation();
		},
		[clickOperation, executeOperation]
	);

	return (
		<Flex
			applyCss={baseStyles}
			alignItems="center"
			flex="none"
			style={{ backgroundColor: color(backgroundColor) }}
			onClick={handleClick}
		>
			<Label size="s" tooltipContent={tooltipContent} colorName="masthead-text-color">
				{label}
			</Label>
		</Flex>
	);
}

DefaultStatusBadge.defaultProps = {
	backgroundColor: 'text-color',
	clickOperation: null
};

DefaultStatusBadge.propTypes = {
	backgroundColor: PropTypes.string,
	clickOperation: PropTypes.string,
	label: PropTypes.string.isRequired,
	tooltipContent: PropTypes.string,
	contextNodeId: PropTypes.string,
	hierarchyNodeId: PropTypes.string,
};

export default DefaultStatusBadge;

Note that the contextNodeId and hierarchyNodeId properties are injected into the (default or custom) component automatically when it is rendered by Fonto. For the rest of the properties, you need to set a default value in the component default properties, or pass a value for them through the component properties. See an example of its usage:

JavaScript

registerNodeStatus( 'needs-review', 'Review', {
	component: DefaultStatusBadge,
	componentProps: {
		// Note that we are not forced to specify backgroundColor nor clickOperation props, as they
	// are set as defaultProps yet.
	label: 'Default status badge',
		tooltipContent: 'Default status badge component'
	}
});

Using a custom component

If you create and then specify a custom component with the component option, you can pass it any props you want using the componentProps. The contextNodeId and hierarchyNodeId are automatically injected for you as well.

JavaScript

registerNodeStatus( 'needs-review', 'Review', {
	component: DefaultStatusBadge,
	componentProps: {
		backgroundColor: 'text-color',
		label: 'Default status badge'
	}
});

Grouping statuses

The filter UI displays all statuses so that a user can filter hierarchy nodes to only show the ones with a given status.

Statuses in this filter can be grouped using a groupName parameter:

JavaScript

registerNodeStatus( 'needs-review', 'Review', {
	component: DefaultStatusBadge,
	groupName: 'Worklow'
});

Hiding statuses from the filter UI

If a status is just used to visualize some aspect of a document, but users are not expected to filter on them, the hideInFilter option can be used to hide the status from the filter.

JavaScript

registerNodeStatus( 'needs-review', 'Review', {
	component: DefaultStatusBadge,
	hideInFilter: true
});

Arguments

  1. id

    (Required)

    Type: String

    The identifier of the status.

  2. label

    (Required)

    Type: String

    The display label of the node status.

  3. options

    (Optional)

    The node status options.

    Default value