Skip to main content
Version: 4.1

Inspector

The plugin implements an editor and viewer of Cell model properties.

To learn more about the plugin, check out the Property Editor and Viewer section.

constructor​

constructor(opt: Inspector.Options);

The Inspector constructor accepts several parameters:

cell​

cell?: mvc.Model;

[optional] The object whose model properties the Inspector will be showing to the user for viewing and editing. In this case, the Inspector retrieves the properties of the provided Cell.

info

Either this parameter or cellView is required. The two options are mutually exclusive.

cellView​

cellView?: dia.CellView;

[optional] The object whose model properties the Inspector will be showing to the user for viewing and editing. In this case, the Inspector retrieves the properties of the CellView's associated Cell (cellView.model).

info

Either this parameter or cell is required. The two options are mutually exclusive.

container​

container?: mvc.$Element;

[optional] A DOM Element (or a CSS selector identifying one) that should serve as the container into which the options of any select-box or color-palette input fields should be appended.

The default is null - in that case, the plugins use their respective default target values (as specified in the API reference: ui.SelectBox.options.target, ui.ColorPalette.options.target).

focusField()​

focusField?: (opt: { [key: string]: any }, path: string, element: HTMLElement, inspector: Inspector) => void;

[optional] A callback function that is called by the Inspector whenever it is trying to focus an input field (e.g. via inspector.focusField()).

This function allows you to specify the focus behavior of custom input field types.

The same function is used for all input field definitions; you need to disambiguate between different cases on your own (e.g. via a switch block).

The callback function is provided with the following arguments, which you may use in your logic:

  • opt is the inputConfig object provided within the Inspector's inputs object as a definition of the current input field.
  • path is a string containing the path to the definition of the current input field within the Inspector's inputs object, separated by slashes ('/').
  • element the rendered HTMLElement of this field (i.e. the value returned by renderFieldContent() callback)
  • inspector is a reference to the current Inspector instance (for context).

getFieldValue()​

getFieldValue?: (attribute: HTMLElement, type: string, inspector: Inspector) => any;

[optional] A callback function that is called by the Inspector whenever user input is detected in an input field. It is expected to return an object with a single property:

  • value is the value read from the field (to be saved on the Cell model).

In other words, when used together with the renderFieldContent() option, this option allows you to define custom input field types.

The same function is used for all input field definitions; you need to disambiguate between different cases on your own (e.g. via a switch block). If the callback function is defined but returns undefined in some cases, the Inspector will try to understand the input field definition in question as a built-in input field type (as if this function were not provided).

The callback function is provided with the following arguments, which you may use in your logic:

groups​

groups?: any;

[optional] An object that defines the groups in the Inspector. Each group may contain any number of input fields from the Inspector.

The keys of this object are strings that uniquely identify the groups and values are groupConfig objects that contain properties for a given group:

  • [optional] closed is a boolean specifying whether the group should be closed by default (when the Inspector is first opened). Default is false (the group is open).

  • [optional] index is a number specifying the index of the group relative to other groups. It is undefined by default (groups are presented in no particular order within the Inspector).

  • [optional] label is a string specifying a label for the group. This label is displayed as a header of the group section in the accordion-like Inspector. It is the group's key by default.

  • [optional] when is an object containing conditional expressions that determine whether the group should be shown or hidden based on the value of other Cell model properties. There are no conditions by default, which means that the group is always shown. See the Property Editor and Viewer Conditional expressions section for more information.

inputs​

inputs?: any;

[optional] An object that defines the input fields in the Inspector. (An input field is in charge of setting user input on the Cell model.)

The structure of the object mimics the structure of properties of the Cell model. The keys of this object are strings that match the properties within the Cell model (possibly nested) - until the deepest-level values, which specify inputConfig objects that contain properties for a given input field.

The following is a list of inputConfig options which are shared by all input fields. Some input field types may recognize additional options - those are listed inside their entries within the Input field types section.

  • [optional] attrs is an object of the form <selector>: { <attributeName>: <attributeValue>, ... }, which allows you to set arbitrary HTML attributes on the HTML code generated for this input field. This is useful if you want to mark certain input fields (e.g. via an additional className) or to store some additional content in them (e.g. in order to display a tooltip).

  • [optional] defaultValue specifies the value displayed in the input field when the corresponding Cell property is undefined. It can either be a primitive value or a callback function with the signature (cell: dia.Cell, path: string) => any, which dynamically returns the default value.

  • [optional] group is a string matching a key of the Inspector's groups object, indicating that the input field belongs to the specified group. It is undefined by default (no group membership). See the Property Editor and Viewer Groups section for more information.

  • [optional] index is a number indicating the index of the input field within its group (if one is specified). It is undefined by default (input fields are presented in no particular order within the group). See the Property Editor and Viewer Groups section for more information.

  • [optional] label is a string specifying the label that the input field should have in the Inspector. It is the input field's path by default.

  • [optional] overwrite is a boolean switching whether a value entered into the input field should overwrite the current contents of the Cell (true) or be merged with the previous contents (false). The default is false. Example resolution:

    // `overwrite: false` (default)
    // - previous value of Cell model property:
    { existingProperty: 'value1' }
    // - user input:
    { newProperty: 'value2' }
    // => new value of Cell model property:
    { newProperty: 'value2', existingProperty: 'value1' }

    // `overwrite: true`
    // - previous value of Cell model property:
    { existingProperty: 'value1' }
    // - user input:
    { newProperty: 'value2' }
    // => new value of Cell model property:
    { newProperty: 'value2' }

  • [required] type is a string specifying the type of the input field. See the Input field types section for a list of supported types and their additional inputConfig options.

  • [optional] valueRegExp is a string specifying a regular expression that is used to interpret (and set) a value on the Cell. The default is undefined (no modification of values). Example resolution:

    // `valueRegExp: '(prefix: )(.*)()'`
    // - old value of Cell model property:
    'prefix: Hello World!'
    // => value presented in the input field:
    'Hello World!'
    // - user input:
    'test'
    // => new value of Cell model property:
    'prefix: test'

    Throws the error Inspector: defaultValue must be present when valueRegExp is used if an undefined value is encountered. You should use this option in combination with the defaultValue option to ensure that undefined is never encountered as a value.

  • [optional] when is an object containing conditional expressions that determine whether the input field should be shown or hidden based on the value of other Cell model properties. See the Property Editor and Viewer Conditional expressions section for more information. There are no conditions by default, which means that the input field is always shown.

    Conditional expressions are objects with the following properties:

    • [required] one property whose key identifies the operator of the expression, and whose value depends on the type of the operator (primitive, unary, multiary, custom primitive)
    • [optional] options property which is an object that modifies the evaluation of the expression:
      • [optional] dependencies is an array of string paths pointing to Cell model properties whose values are necessary for the evaluation of the expression (relevant for custom operators),
      • [optional] otherwise is an object that modifies what happens when the expression evaluates to false:
        • [optional] unset is a boolean which determines whether the input field should be cleared (or reverted to its defaultValue) when it is hidden by Inspector (true), or should remember its user-submitted content and present it again whenever the input field becomes visible (false). The default is false.

live​

live?: boolean;

[optional] Should the Inspector update the Cell properties immediately (i.e. in reaction to an onchange event triggered on a form input)? The default is true.

multiOpenGroups​

multiOpenGroups?: boolean;

[optional] Is the user allowed to have multiple groups opened in the Inspector at the same time? The default is true.

If you are looking for the classical accordion type of Inspector (only one group open at a time), set this option to false.

operators​

operators?: { [operatorName: string]: Operator };

[optional] An object that allows you to define custom primitive operators for use in conditional expressions.

The keys of this object are strings that uniquely identify the custom operators and values are callback functions which are expected to return true when the custom operator's condition is met and false when it is not. The callback function is provided with the following arguments which you may use in your logic:

  • cell is a reference to the Cell modified by the current Inspector instance.
  • value is the value of the property at the path provided by the first operand of the expression.
  • ...arguments is anything that was passed to the operator, spread into arguments - if a single value is passed to the operator, it becomes a single argument, but if an array is passed to the operator, its contents become individual arguments.
  • valuePath (the last argument) is a string containing the resolved path to the property specified in the first operand of the expression (wildcards replaced).

renderFieldContent()​

renderFieldContent?: (opt: { [key: string]: any }, path: string, value: any, inspector: Inspector) => mvc.$HTMLElement;

[optional] A callback function that is called by the Inspector whenever it needs to render an input field. It is expected to return the content as an HTMLElement or a DOM Element.

In other words, this function allows you to define custom input field types.

The same function is used for all input field definitions; you need to disambiguate between different cases on your own (e.g. via a switch block). If the function is defined but returns undefined in some cases, the Inspector will try to understand the input field definition in question as a built-in input field type (as if this function were not provided).

The callback function is provided with the following arguments, which you may use in your logic:

  • opt is the inputConfig object provided within the Inspector's inputs object as a definition of the current input field.
  • path is a string containing the path to the definition of the current input field within the Inspector's inputs object, separated by slashes ('/').
  • value is the value read from the Cell property at the corresponding path at the time of rendering of the current input field. It takes the current input field definition's inputConfig.defaultValue and inputConfig.valueRegExp into account (if any are specified).
  • inspector is a reference to the current Inspector instance (for context).

renderLabel()​

renderLabel?: (opt: { [key: string]: any }, path: string, inspector: Inspector) => mvc.$HTMLElement;

[optional] A callback function that is called by the Inspector whenever it needs to render the label of an input field. It is expected to return the content as an HTMLElement or a DOM Element.

This function allows you to specify custom input field labels.

The same function is used for all input field definitions; you need to disambiguate between different cases on your own (e.g. via a switch block). If the function is defined but returns undefined in some cases, the Inspector will create the label in question in the usual way (i.e. according to current input field definition's inputConfig.label, as if this function were not provided).

The callback function is provided with the following arguments, which you may use in your logic:

  • opt is the inputConfig object provided within the Inspector's inputs object as a definition of the current input field.
  • path is a string containing the path to the definition of the current input field within the Inspector's inputs object, separated by slashes ('/').
  • inspector is a reference to the current Inspector instance (for context).

stateKey()​

stateKey?: (model: dia.Cell) => string;

[optional] A callback function that is expected to return a string specifying a unique identifier for saving/restoring the state of the groups (i.e. remembering which groups are opened and which ones are closed). The default function returns the id of the current Cell, which means that every Cell has its own group state. (And that Inspectors opened on different instances of the same Cell type do not remember the previously opened/closed groups.)

The callback function is provided with the following argument, which you may use in your logic:

  • cell is a reference to the Cell modified by the current Inspector instance.

One commonly used alternative function stores group state per Cell type:

function(model) { return model.get('type')}

When the above function is used as stateKey, all Inspectors opened for a type (e.g. standard.Rectangle) share the same group state.

validateInput()​

validateInput?: (input: any, path: string, type: string, inspector: Inspector) => boolean;

[optional] A callback function that is called by the Inspector to check whether user input into an input field is valid. The function is expected to return true when the input is valid and false when it is not. If false is returned, the input field value is not saved to the Cell model.

See the Property Editor and Viewer Validation section for more information.

The same function is used for all input field definitions; you need to disambiguate between different cases on your own (e.g. via a switch block).

The callback function is provided with the following arguments, which you may use in your logic:

  • input is a reference to the input field's HTMLElement (usually <input>) with which the user has interacted.
  • path is a string containing the path to the input field within the Inspector's inputs object, separated by slashes ('/').
  • type is a string containing the type of the input field.
  • inspector is a reference to the current Inspector instance (for context).

The default function checks the validity property of input:

function(input, path, type, inspector) {
    return (input.validity ? input.validity.valid : true);
}

Methods​

closeGroup()​

closeGroup(name: string): void;

Close the group identified by name.

closeGroups()​

closeGroups(): void;

Close all groups.

focusField()​

focusField(path: string): void;

Focus the input field identified by the provided slash-separated ('/') path within the Inspector's inputs object.

getGroupsState()​

getGroupsState(): string[];

Get the array of groups which are currently stored as closed in the group state. (This may differ from the currently rendered state if storeGroupsState() has not been called recently.)

openGroup()​

openGroup(name: string): void;

Open the group identified by name.

openGroups()​

openGroups(): void;

Open all groups.

refreshSource()​

refreshSource(path: string): void;

Manually refresh the source of the input field identified by the provided slash-separated ('/') path within the Inspector's inputs object. See the Property Editor and Viewer Options section (object rule) for more information.

refreshSources()​

refreshSources(): void;

Manually refresh sources of all input fields. See the Property Editor and Viewer Options section (object rule) for more information.

remove()​

remove(): this;

Remove the Inspector from the DOM. This method should be called once you are finished with using the Inspector.

render()​

render(): this;

Render the Inspector based on the options passed to the constructor function.

info

Note that this does not add the Inspector to the live DOM tree - that must be done manually by appending the Inspector DOM Element (accessible as the el property) to a live DOM Element on the page. See the Property Editor and Viewer section for more information.

restoreGroupsState()​

restoreGroupsState(): void;

Apply the stored group state (which groups were opened and which ones were closed) by opening and closing groups to match. The state information is looked up by the current return value of the stateKey() callback function.

Use together with storeGroupsState() to manually manipulate group states (useful if you do not create your Inspector via the create() method).

storeGroupsState()​

storeGroupsState(): void;

Save the current group state (which groups are opened and which ones are closed). The key for storing the state is the current return value of the stateKey() callback function.

Use together with restoreGroupsState() to manually manipulate group states (useful if you do not create your Inspector via the create() method).

toggleGroup()​

toggleGroup(name: string): void;

Toggle the group identified by name.

updateCell()​

updateCell(): void;

Manually update the Inspector's associated Cell based on the current values in the Inspector's input fields. This is especially useful if you use the Inspector with the live mode disabled.

Static methods​

close()​

static close(): void;

A helper method for closing Inspector instances which were created via the create() method.

create()​

static create(container: mvc.$HTMLElement, opt?: Inspector.CreateOptions): ui.Inspector;

A helper method for creating an instance of Inspector, where container is an DOM Element (or a CSS selector identifying one) that should serve as the container into which the Inspector should be rendered, and opt is an object specifying Inspector constructor options.

In addition to all Inspector constructor options, the opt object of the create() static method accepts three additional options:

  • [optional] storeGroupsState is a boolean specifying whether current Inspector's group state should be saved before new Inspector is created by this method. (That is, whether Inspector should remember which groups were opened and which ones were closed when it is reopened for a Cell with the same stateKey() return value.) The default is true.
  • [optional] restoreGroupsState is a boolean specifying whether previous group state should be restored for the new Inspector created by this method (if any group state had previously been saved for the current Cell's stateKey() return value). The default is true.
  • [optional] updateCellOnClose is a boolean specifying whether current Inspector input field values should be saved to the Inspector's associated cell before a new Inspector is created by this method. The default is true.

Events​

The plugin fires the following events:

render​

Triggered when the Inspector re-renders itself partially.

note

If you are adding event listeners or your own custom HTML into the Inspector, you should always do it inside the render event handler.

inspector.on('render', () => {
    // Inspector has been rendered
});

change:[path]​

Triggered when the user changes a Cell model property at [path] via an input field of the Inspector (only if the validateInput() callback function returns true).

inspector.on(`change:[path]`, (
    value: any,
    inputEl: any
) => {
    // the Cell property `[path]` was changed
})
  • value is the new value at the property path,
  • inputEl is a reference to the input field's HTMLElement (usually <input>) with which the user has interacted.

Example usage:

inspector.on(`change:myProperty`, (value, inputEl) => {
    console.log(`new value of myProperty: ${value}`);
})

close​

Triggered when the Inspector gets closed.

inspector.on('close', () => {
    // Inspector has been closed
});

Types​

The plugin uses the following types:

CreateOptions​

interface CreateOptions extends Options {
    storeGroupsState?: boolean;
    restoreGroupsState?: boolean;
    updateCellOnClose?: boolean;
}

Operator​

type Operator = (cell: dia.Cell, propertyValue: any, ...conditionValues: any[]) => boolean;

Options​

interface Options extends mvc.ViewOptions<undefined> {
    cellView?: dia.CellView;
    cell?: mvc.Model;
    live?: boolean;
    validateInput?: (input: any, path: string, type: string, inspector: Inspector) => boolean;
    groups?: any;
    inputs?: any;
    storeGroupsState?: boolean;
    restoreGroupsState?: boolean;
    updateCellOnClose?: boolean;
    renderLabel?: (opt: { [key: string]: any }, path: string, inspector: Inspector) => mvc.$HTMLElement;
    renderFieldContent?: (opt: { [key: string]: any }, path: string, value: any, inspector: Inspector) => mvc.$HTMLElement;
    focusField?: (opt: { [key: string]: any }, path: string, element: HTMLElement, inspector: Inspector) => void;
    getFieldValue?: (attribute: HTMLElement, type: string) => any;
    multiOpenGroups?: boolean;
    container?: mvc.$Element;
    stateKey?: (model: dia.Cell) => string;
    operators?: { [operatorName: string]: Operator };
}

OptionsSource​

interface OptionsSource {
    dependencies?: string[],
    source: (data: OptionsSourceData) => any[] | Promise<any[]>
}

OptionsSourceData​

interface OptionsSourceData {
    model: mvc.Model,
    inspector: Inspector,
    initialized: boolean,
    path: string,
    dependencies: { [key: string]: {
        path: string,
        changedPath: string,
        value: any
    }}
}

Built-in input field types​

This is a list of input field types recognized by default by the inputConfig.type property within the Inspector's inputs object. The Inspector constructor matches the type of each input field definition to one of those values and creates an input field accordingly. If a type is not recognized, the Inspector tries to understand it as a custom input field type.

Input fields are HTML form controls which allow the user to view and/or modify a value on the Cell model. See the Built-in input field types section for more information.

JointJS also contains mechanisms to define one's own custom input field types.

color​

Insert an HTML 5 color-type input field to the Inspector. See the Property Editor and Viewer color section for a code example.

color-palette​

Insert an instance of ColorPalette to the Inspector. See the Property Editor and Viewer color-palette section for a code example.

Additional options​

See the ColorPalette documentation for additional options, with one change:

  • [optional] options specifies the options available to the user for selection in the same way as options of the select input field type.

    Note that when using the object[] rules, you may provide objects with all properties of ui.ColorPalette.options.options. For example:

    myProperty: {
        type: 'color-palette',
        options: [
            { content: 'red', icon: 'image1.svg' },
            { content: 'blue' }
        ]
    }

  • [optional] previewMode is a boolean switching whether preview mode should be enabled on the input field. The default is false. It works the same way as previewMode of the select-box input field type.

content-editable​

Insert a content-editable div (which resizes automatically as the user types) to the Inspector. See the Property Editor and Viewer content-editable section for a code example.

Additional options​

  • [optional] html is a boolean switching how the content is interpreted - as HTML (true) or as plain text (false). The default is true (HTML).
  • [optional] readonly is a boolean determining whether the user is allowed to edit the content of the field. The default is false (user is allowed to edit).

list​

Insert a widget for adding/removing items to/from an arbitrary array. The inputs of each list item can be specified via the item property. See the Property Editor and Viewer list section for a code example.

Additional options​

  • [optional] addButtonLabel and removeButtonLabel are strings specifying the labels of the "Add list item" and "Remove list item" button, respectively. The defaults are '+' and '-'.
  • [optional] item is an object defining a nested inputs object for a generic item of the list. This allows you to specify input field definitions for properties inside array items. See the Nested structures Array properties section for more information.
  • [optional] min and max are numbers specifying the minimum and maximum allowed number of items in the array property.

number​

Insert an HTML 5 number-type input field to the Inspector. See the Property Editor and Viewer number section for a code example.

Additional options​

  • [optional] min and max are numbers specifying the minimum and maximum values that are acceptable and valid for the input field. The defaults are -Infinity and Infinity.

object​

Insert a wrapper for the inputs of specified properties of an arbitrary object (specified via the properties property). See the Property Editor and Viewer object section for a code example.

Additional options​

radio-group​

Insert an instance of RadioGroup to the Inspector. See the Property Editor and Viewer radio-group section for a code example.

Additional options​

See the RadioGroup documentation for additional options, with one change:

range​

Insert an HTML 5 range-type input field to the Inspector. See the Property Editor and Viewer range section for a code example.

Additional options​

  • [optional] min and max are numbers specifying the minimum and maximum values that are acceptable and valid for the input field. The defaults are -Infinity and Infinity.
  • [optional] step is a number specifying the granularity that the value must adhere to. The default is 1.
  • [optional] unit is a string specifying the unit displayed next to the value. The default is an empty string ('').

select​

Insert a select box to the Inspector. See the Property Editor and Viewer select section for a code example.

Additional options​

  • [optional] multiple is a boolean specifying whether multiple values can be selected at the same time. The default is false.

  • [optional] size is a number specifying (when multiple is true) how many rows of the list should be visible at one time.

  • [optional] options specifies the options available to the user for selection:

    • undefined - By default, the property has a value of empty array (no options available).

    • string[] - If specified as an array of strings, the strings are used as values for the selection. The following is an example of a select box to set the availability of a worker (via workdays property on the Cell model):

      workdays: {
          type: 'select',
          options: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
          multiple: true,
          overwrite: true,
          group: 'occupation'
      }

    • object[] - If specified as an array of objects, the objects are expected to contain two properties:

      • [required] content is the label of the option (presented to the user).
      • [optional] value is the value of the option (will be written into the model on user selection). If no value is specified, content is used as the value.

      For example:

      myProperty: {
          type: 'select',
          options: [
              { value: 'value1', content: 'option1' },
              { value: 'value2', content: 'option2' }
          ]
      }

    • string - If specified as a string, the property is interpreted as a path pointing to another property on the Cell model (as determined by the cell.prop() function). The referenced property is expected to contain an array of options which can be interpreted by one of the array rules above. The Inspector keeps track of the referenced property and refreshes the list of options of this input field whenever there is a change. Example resolution:

      // `options: 'path/to/options'`
      // => interpreted as:
      cell.prop('path/to/options')
      // => returned value (used as list of options):
      ['option1', 'option2']

    • object - If specified as an object, the property is expected to contain the following properties:

      • [optional] dependencies is an array of strings interpreted as paths to other properties on the Cell model (see above). The default is an empty array ([]).

        You may choose to leave some (or all) of your dependencies out of the dependencies array. In that case, Inspector will not keep track of changes in those properties, but you can load current values of these properties manually via the refreshSources() or refreshSource() functions inside your source() callback.

        The paths may use '${index}' wildcards to specify a path to a sibling property inside a list. These wildcards are dynamically substituted for the actual index of the item inside which the dependency is evaluated.

      • [required] source() is a callback function which is expected to return an array of options which can be interpreted as one of the array rules above (or a Promise of the same). It is provided with a single data object as an argument, which contains the following properties that may be useful for your logic:

        • model is a reference to the Cell modified by the current Inspector instance,
        • inspector is a reference to the current Inspector instance (for context),
        • initialized is a boolean recording whether the sources of this input field have been initialized (i.e. the values of this input field's dependencies have been calculated at least once - e.g. on render of the input field),
        • path is a string containing the path to the input field within the Inspector's inputs object, separated by slashes ('/').
        • dependencies is an object with the current status of all declared dependencies (see above), where the keys are items of the dependencies array, and the values are objects with the following properties:
          • path is a string containing the resolved path to the dependency on the Cell model, separated by slashes (/) and with wildcards replaced,
          • changedPath is a string containing the resolved path to the input field within the Inspector's inputs object, separated by slashes (/) and with wildcards replaced,
          • value is the resolved value of the dependency.

        The Inspector keeps track of the dependencies and calls the source() callback to refresh the list of options of this input field whenever there is a change.

      In the following example, the myArray property on the Cell is an array of objects with two properties: myValue (a string) and myOptions (an array of strings). For each item in myArray, the user is allowed to choose a myValue value in the Inspector via a radio-group input field - the options available are taken from the same item's myOptions property. Whenever the myOptions array is changed (i.e. an item is added/modified/removed), the radio-group input field for myValue is refreshed:

      const inspector = new ui.Inspector({
          cellView: cellView,
          inputs: {
              myArray: {
                  type: 'list',
                  item: {
                      type: 'object',
                      properties: {
                          myValue: {
                              type: 'radio-group',
                              options: {
                                  dependencies: ['myArray/${index}/myOptions'],
                                  source: (data) => {
                                      const { value } = data.dependencies['myArray/${index}/myOptions'];
                                      const options = value;
                                      if (Array.isArray(options)) {
                                          return options.map(name => {
                                              return { value: name, content: name };
                                          });
                                      }
                                      return [];
                                  }
                              }
                          },
                          myOptions: {
                              type: 'list',
                              item: {
                                  type: 'text'
                              }
                          }
                      }
                  }
              }
          }
      });

select-box​

Insert an instance of SelectBox to the Inspector. See the Property Editor and Viewer select-box section for a code example.

Additional options​

See the SelectBox documentation for additional options, with one change:

  • [optional] options specifies the options available to the user for selection in the same way as options of the select input field type.

    Note that when using the object[] rules, you may provide objects with all properties of ui.SelectBox.options.options. For example:

    myProperty: {
        type: 'select-box',
        options: [
            { icon: 'icon1.png', value: 'value1', content: 'option1' },
            { icon: 'icon2.png', value: 'value1', content: 'option2' }
        ]
    }

  • [optional] previewMode is a boolean switching whether preview mode should be enabled on the input field. The default is false.

    In preview mode, when the user hovers over one of the items in the input field (i.e. a SelectBox dropdown item), the Inspector changes the Cell model but triggers the change with the dry flag set to true. This enables you to react to preview changes differently from real changes, as in the following example:

    myCell.on('change:myProperty', function(cell, change, opt) {
        if (opt.dry) {
            /* do something when in preview mode */
        } else {
            sendToDatabase(JSON.stringify(graph));
        }
    });

    This is useful, for example, if your application needs to reflect the values of the hovered items in the diagram but does not want to store the change to a database.

select-button-group​

Insert an instance of SelectButtonGroup to the Inspector. See the Property Editor and Viewer select-button-group section for a code example.

Additional options​

See the SelectButtonGroup documentation for additional options, with one change:

  • [optional] options specifies the options available to the user for selection in the same way as options of the select input field type.

    Note that when using the object[] rules, you may provide objects with all properties of ui.SelectButtonGroup.options.options. For example:

    myProperty: {
        type: 'select-box',
        options: [
            {
                value: 'value1',
                content: 'option1',
                buttonWidth: 20,
                icon: 'image.png',
                iconSelected: 'image2.png',
                iconWidth: 20,
                iconHeight: 20
            }
        ]
    }

  • [optional] previewMode is a boolean switching whether preview mode should be enabled on the input field. The default is false. It works the same way as previewMode of the select-box input field type.

text​

Insert a text input field to the Inspector. See the Property Editor and Viewer text section for a code example.

textarea​

Insert a textarea input field to the Inspector. See the Property Editor and Viewer textarea section for a code example.

toggle​

Insert a toggle (a checkbox-type input field) to the Inspector. See the Property Editor and Viewer toggle section for a code example.

Built-in operators​

Operators are callback functions which define the evaluation rules of conditional expressions using values of arbitrary Cell model properties as arguments. They are uniquely identified by string identifiers.

Whenever an operator returns false, it means that the condition observed by the conditional expression is not met, and vice versa. The Inspector relies on conditional expressions defined in the inputConfig.when parameter of the inputs option (and the groupConfig.when parameter of the groups option) to switch the visibility of input fields (and whole groups) within the rendered Inspector to modify the user experience.

JointJS comes with a built-in collection of operators (primitive, unary, and multiary), which are presented below.

JointJS also contains mechanisms to define one's own custom primitive operators.

Primitive operators​

Primitive operators compare the value of a Cell model property with a fixed value.

More precisely, the value of an expression where the key is a primitive operator is an object with a single property:

  • The key is a string path pointing to a Cell model property and the value is the value with which the value of the referenced property should be compared.

For example:

{ eq: { 'size/width': 300 }}
{ lt: { 'count': 10 }}
{ in: { 'index': [0, 2, 4] }}
{ regex: { 'attrs/label/text' : 'JointJS|Rappid' }}

As a rule, the order of the two operands of a primitive operator is key first, value second. Therefore, the above example { lt: { 'count': 10 }} would be read as follows: An expression that returns true if count is less than 10.

The built-in primitive operators are listed below in order of their identifier:

eq​

Returns true if the value of the Cell model property identified by the object key equals the object value. Uses == internally.

{ eq: { 'size/width': 300 }}

equal​

Returns true if the value of the Cell model property identified by the object key equals the object value. Uses util.isEqual() internally, which supports deep comparison.

{ equal: { 'size': { 'width': 300 }}}

gt​

Returns true if the value of the Cell model property identified by the object key is greater than the object value. Uses > internally.

{ gt: { 'count': 10 }}

gte​

Returns true if the value of the Cell model property identified by the object key is greater than or equal to the object value. Uses >= internally.

{ gte: { 'count': 10 }}

in​

Returns false if the object value is not an array.

Returns true if the value of the Cell model property identified by the object key is an item in the object value. Uses array.includes() internally.

{ in: { 'index': [0, 2, 4] }}

lt​

Returns true if the value of the Cell model property identified by the object key is less than the object value. Uses < internally.

{ lt: { 'count': 10 }}

lte​

Returns true if the value of the Cell model property identified by the object key is less than or equal to the object value. Uses <= internally.

{ lte: { 'count': 10 }}

ne​

Returns true if the value of the Cell model property identified by the object key does not equal the object value. Uses != internally.

{ eq: { 'size/width': 300 }}

nin​

Returns false if the object value is not an array.

Returns true if the value of the Cell model property identified by the object key is not an item in the object value. Uses !array.includes() internally.

{ nin: { 'index': [0, 2, 4] }}

regex​

Returns true if the value of the Cell model property identified by the object key matches a regular expression described in the object value. Uses regex.test() internally.

{ regex: { 'attrs/label/text' : 'JointJS|Rappid' }}

text​

Returns false if the object value is not a string.

Returns true if the object value is an empty string ('').

Returns true if the value of the Cell model property identified by the object key converted to lowercase contains the object value as a substring. Uses string.indexOf() internally.

{ text: { 'attrs/label/text' : 'jointjs' }}

Unary operators​

Unary operators return a value based on the result of a single expression.

More precisely, the value of an expression where the key is an unary operator is a single expression. The unary operator takes the result of the provided expression and returns a result based on the value.

The following example showcases the NOT operator. It returns true when the size property is not an object with precisely one property, width, that has a value of 300:

{ not: { equal: { 'size': { 'width': 300 }}}}

Only one unary operator is built-in to JointJS:

not​

Returns the logical negation of the provided expression, i.e. !expr.

{ not: { equal: { 'size': { 'width': 300 }}}}

Multiary operators​

Multiary operators return a value based on the result of multiple expressions.

More precisely, the value of an expression where the key is a multiary operator is an array of at least one expression. The multiary operator takes the result of all the provided expressions and returns a result based on their value.

The following example showcases the AND operator. It returns true when all provided expressions are true:

{ and: [
    { gte: { 'position/x': 100 }},
    { lte: { 'position/x': 400 }},
    { gte: { 'position/y': 200 }},
    { lte: { 'position/y': 300 }}
]}

The built-in multiary operators are listed below in order of their identifier:

and​

Returns the logical conjunction of all provided expressions, i.e. expr1 && expr2 && expr3 && ....

{ and: [
    { gte: { 'position/x': 100 }},
    { lte: { 'position/x': 400 }},
    { gte: { 'position/y': 200 }},
    { lte: { 'position/y': 300 }}
]}

nor​

Returns the logical negation of the disjunction of all provided expressions, i.e. !(expr1 || expr2 || expr3 || ...).

{ nor: [
    { eq: { 'myProperty1': true }},
    { eq: { 'myProperty2': true }},
    { eq: { 'myProperty3': true }}
]}

or​

Returns the logical disjunction of all provided expressions, i.e. expr1 || expr2 || expr3 || ....

{ or: [
    { eq: { 'myProperty1': true }},
    { eq: { 'myProperty2': true }},
    { eq: { 'myProperty3': true }}
]}

Stay in the know

Be where thousands of diagramming enthusiasts meet

Star us on GitHub