Defining Elements

Basic Definition Structure

Each element has a definition which describes how it should be composed and used. If an element node is created, this definition is used to set up the edit dialog and further options.

A definition consists of a basic object shaped like the following:

{
  id: 'my-element',
  label: 'My Element',
  icon: '...',
  tags: ['tag1', 'tag2'],
  isContainer: true,
  groups: ['example', 'other'],
  allowedGroups: ['group3'],
  allowCustomCss: false,
  properties: [],
}

The following options are available:

Option	Values	Default	Description
id	string	-	Unique identifier for the element type.
label	string	-	Human readable name of the element.
icon	string	-	HTML code used as element icon. Could be a Dashicons <span> or an inline <svg>.
tags	string[]	[]	A list of keywords that help the user find the element.
isContainer	boolean	false	Whether the element can contain child elements.
groups	string[] | '*'	[]	A list of all group names which the element belongs to. Groups define which elements can be encapsulated within each other. "*" means that this element can be placed anywhere.
allowedGroups	string[] | '*'	[]	A list of all group names that are allowed to be contained by this element. Only applicable for container elements.
allowCustomCss v3.5	boolean	false	Whether the element allows defining one-off CSS for individual element instances. Requires setting a data-css-locator="[element-guid]" attribute on the element's template root.
properties	Property[]	[]	A list of objects in the property format (see Defining Properties)
dialog	boolean	true	If false, the element is not editable (has no dialog window).
restrictions v3.23	Record<string, boolean>	{}	A set of flags, restricting how the editor is allowed to interact with the element (see Restrictions).
extends	string	-	Element ID of parent element, from which should be inherited. For more, see Inheritance and Masking.
mask	Record<string, any>	-	An object containing key value pairs of the property (key) and the prefilled value (value) which should masked.

Define Properties

Properties are used to model the data stored in an instance of an element. Properties consist of at least an unique identifier id a label and an input. There are more options to specify e.g. a description or a default value etc.

The following example defines a property for a title text field:

{
  id: 'title',
  label: 'Title',
  input: {
    type: 'text'
  }
}

The following options are available for each property:

Option	Values	Default	Description
id	string	-	Identifier for the property, unique across this element's properties.
label	string	-	Human readable name for the property.
description	string	-	Description of the property.
input	object	-	An object with a type property specifying the input type. Depending on the chosen input type, further options may be needed, see the Input Types section.
defaultValue	any	-	The default value that should be used for the property.
isHidden v3.28	boolean	false	Whether the property is hidden in the property form. This option has been replaced with the more powerful isVisible in v3.28 and has therefore been deprecated.
isVisible v3.28	boolean	false	Whether the property is hidden in the property form.
groups	string[]	-	An array with group identifiers; defines which groups of users can see the property.
collapsed v3.27	boolean	false	Whether the property is collapsed in its initial state. This option is a no-op since v3.27 and has therefore been deprecated.
layout v3.27	'row' | 'column' | 'auto' | 'followup'	'auto'	How the label/description and the interactive part of the property should be arranged. Using 'auto' falls back to the layout option during registration. Using 'followup' v3.28 reduces distinction between the property and its predecessor, making them feel more cohesive.

Property Visibility

Static Visibility

To (temporarily) hide a property, you can set the isVisible option to false:

{
  id: 'my-property',
  label: 'My Property',
  isVisible: false
}

INFO

Up until v3.27, the isHidden option was used for this purpose. It has been deprecated in favor of isVisible in v3.28.

Dynamic Visibility v3.28

A property can be shown based on the value of another property in the same property form by passing conditions to the isVisible option:

{
  id: 'my-property',
  label: 'My Property',
  isVisible: [
    ['other-property', 'equals', 'foo'],
  ]
}

Condition Structure

Each condition is a 3-tuple consisting of

1. the depended-on property's ID
2. the condition name and
3. a (sometimes optional) payload.

Which particular conditions are available depends on the input type of the depended-on property. See the individual input types' documentation for more information.

Condition Grouping

For more complex scenarios, you can group conditions:

{
  type: 'all', // type can be 'all', 'some' or 'none'
  conditions: [
    // condition 1,
    // condition 2,
    // ...
  ]
}

These condition groups can also be arbitrarily nested.

INFO

The format used in the introductory example above...

isVisible: [
  ['other-property', 'equals', 'foo']
]

...is just a shorthand for the most common case, which is a condtion group of type all:

isVisible: {
  type: 'all',
  conditions: [
    ['other-property', 'equals', 'foo']
  ]
}

Group-based Visibility

You can control which user should see which property by assigning groups to the a property.

{
  id: 'my-property',
  label: 'My Property',
  groups: ['experts']
}

If the group attribute is not defined, everyone is allowed to see this property.