WidgetSubAreaByName

Type: Object

Widgets can be rendered in different positions, called Widget Areas. To place a widget in one of these areas, define a WidgetSubArea for it. By referring to the same sub-area from different configuration rules, specific widgets in an area can be overridden without affecting other widgets sharing the same area.

To define and assign widgets to one or more Widget sub-areas, set the CVK property of the widget area to an object. Each property in this object represents a widget sub-area identified by the name of the property. The value of each can be a WidgetSubArea object describing the widget(s) to place and their priority. It can also be set to null to disable the widget sub-area for nodes to which the configuration applies.

If an area ends up not containing any widgets, no space will be reserved for it.

Shorthand configuration syntax

Older releases of Fonto Editor did not use the concept of sub-areas and defined each widget area as accepting either an array of widgets or null. For backwards compatibility as well as convenience, such configuration rules are still accepted. Widgets defined this way are automatically mapped to the sub-area "main" with priority 0, so configuration can be gradually updated to the new syntax.

Example

Other

// Add a markup label to any child of a <div>
configureProperties(sxModule, 'self::element()[parent::self::div]', {
    blockHeaderLeft: {
        markupLabel: {
            widget: createMarkupLabelWidget(),
            priority: 10
        }
    }
});

// Add a custom widget on any element with a "role" attribute
configureProperties(sxModule, 'self::element()[@role]', {
    blockHeaderLeft: {
        roleEditWidget: {
            // Some kind of widget to edit the role attribute -
            // multiple widgets can be specified using an array if needed
            widget: createIconWidget('edit', {
                clickOperation: 'my-contextual-edit-operation',
                tooltipContent: 'Edit role'
            }),
            // Show this after the markup label if both apply
            priority: 0
        }
    }
});

// Override both widgets for the <special> element
// (keeping any others that may be defined elsewhere)
configureProperties(sxModule, 'self::element()[@role]', {
    blockHeaderLeft: {
        // Use a label instead of the markup label
        markupLabel: {
            widget: createLabelQueryWidget('@label'),
            priority: 10
        },
        // Hide the role edit widget
        roleEditWidget: null
    }
});

// The following two rules are equivalent - the array notation can be seen as syntactical sugar
// for the full version below. However, it is not possible to define widget sub-areas other than
// "main" using the shorthand syntax.
configureProperties(sxModule, 'self::figure', {
    blockHeaderLeft: [createMarkupLabelWidget()]
});

configureProperties(sxModule, 'self::figure', {
    blockHeaderLeft: {
        main: {
            widget: [createMarkupLabelWidget()],
            priority: 0
        }
    }
});

Note that the priority property in a WidgetSubArea is not the same as the priority used as a top-level property in the CvkOptions object. The priority of a WidgetSubArea controls the order in which that sub-area appears relative to other sub-areas configured for the same area. The CvkOptions priority controls which configuration applies when multiple rules affect the same sub-area.

Consider the following simplified example:

Other

configureProperties(sxModule, 'self::p', {
    blockBefore: { subAreaA: { widget: X, priority: 2 } },
    priority: 100
});
configureProperties(sxModule, 'self::p', {
    blockBefore: { subAreaA: { widget: Y, priority: 1 }, subAreaB: { widget: Z, priority: 3 } },
    priority: 10
});

The end result of this configuration is that widgets X and Z will be shown, because the first configuration rule "wins" from the second for subAreaA due to the rule priority. However, subAreaB only has a single rule affecting it, so that one always applies.

The widgets selected this way are then sorted by the priority set in their sub-area configuration, resulting in Z (with sub-area priority 3) being shown before X (with sub-area priority 2) in the blockBefore widget area.