Property Types – Mx8

Introduction

In order to be configurable, pluggable widgets use a widget properties definition which describes the properties available to pluggable widgets. To see examples of pluggable widgets in action, see How To Build Pluggable Widgets.

The common structure of a property definition is as follows:

<property key="propertyKey" type="propertyType">
	<caption>My Property</caption>
	<description>This is my property</description>
</property>

XML Attributes

Key (required)

This defines the prop key in the client component props which are supplied to the widget client component. Each property must have a unique key which can contain letters of all cases, digits, or underscores. However, a key attribute cannot start with a digit.

Type (required)

This defines a property’s type. A type must be one of the following:

• Static Types
  • string
  • boolean
  • integer
  • decimal
  • enumeration
• Component Types
  • icon
  • image
  • widgets
• Dynamic Types
  • expression
  • textTemplate
  • action
  • attribute
  • object
  • file
  • datasource

XML Elements

<caption> (required) — This defines the property name visible for the user (not the end-user) while configuring the widget in Studio Pro.

<description> (required) — This is a description which explains a property’s purpose.

Static Types

Static types are made to pass values configured in Studio Pro to the widget. They do not depend on any dynamic data. Static properties are passed to the widget client component as simple primitive values.

String

The string property type is represented as a simple text input in Studio Pro. It is passed as a string prop to a client component.

XML Attributes

Studio Pro UI

When the property is defined as follows:

<property key="myString" type="string">
	<caption>My string</caption>
	<description>My string setting</description>
</property>

Then the Studio Pro UI for the property appears like this:

When the property is defined as follows:

<property key="myStringMultiline" type="string" multiline="true">
	<caption>My string multiline</caption>
	<description>My string multiline setting</description>
</property>

Then the Studio Pro UI for the property appears like this:

Boolean

Properties of type Boolean are represented as a toggle in Studio Pro. They are passed as boolean props to a client component.

XML Attributes

Studio Pro UI

When the property is defined as follows:

<property key="myBoolean" type="boolean" defaultValue="false">
	<caption>My boolean</caption>
	<description>My boolean setting</description>
</property>

Then the Studio Pro UI for the property appears like this:

Integer

Integer is represented as a number input in Studio Pro. It is passed as a number prop to a client component.

XML Attributes

Studio Pro UI

When the property is defined as follows:

<property key="myInteger" type="integer" defaultValue="1000">
	<caption>My integer</caption>
	<description>My integer setting</description>
</property>

Then the Studio Pro UI for the property appears like this:

Decimal

Properties of type decimal are represented as a number input in Studio Pro. They are passed as a Big prop to a client component.

XML Attributes

Studio Pro UI

When the property is defined as follows:

<property key="myDecimal" type="decimal" defaultValue="50.4">
	<caption>My decimal</caption>
	<description>My decimal setting</description>
</property>

Then the Studio Pro UI for the property appears like this:

Enumeration

The enumeration property type allows a user to select one out of multiple options defined in the XML. The key of a selected enumeration element is passed as string prop to a client component.

XML Attributes

XML Elements

<enumerationValues> (required) — One <enumerationValues> element must be declared with multiple <enumerationValue> elements inside in order to define possible enumeration values. A key attribute is required for every enumeration value as well as a caption. Enter enumeration values like this:

<enumerationValue key="myEnumOption">My enum option caption</enumerationValue>

The key of a selected element will be passed to the client component. key should not be changed since it is used to identify options used in an app.

Studio Pro UI

When the property is defined as follows:

	<property key="myEnumeration" type="enumeration" defaultValue="red">
		<caption>My enumeration</caption>
		<description>My enumeration setting</description>
		<enumerationValues>
			<enumerationValue key="red">Red</enumerationValue>
			<enumerationValue key="green">Green</enumerationValue>
			<enumerationValue key="blue">Blue</enumerationValue>
		</enumerationValues>
	</property>

Then the Studio Pro UI for the property appears like this:

Component Types

Icon

Properties of type icon allows a user to configure an icon similar to one used by a button. It is passed as DynamicValue<IconValue> prop to a client component. For more information, see the IconValue section of Client APIs Available to Pluggable Widgets.

XML Attributes

Studio Pro UI

When the component is defined as follows:

<property key="cardIcon" type="icon" required="false">
	<caption>Icon</caption>
	<description>Card icon</description>
</property>

Then the Studio Pro UI for the component appears like this:

Image

Image allows a user to configure a static image from an image collection. It also allows a user to configure an image from an object that is a specialization of System.Image. It is passed as an DynamicValue<ImageValue> prop to a client component (for more information, see the ImageValue section of Client APIs Available to Pluggable Widgets). See the Images Reference Guide for more information about supported image formats.

XML Attributes

Studio Pro UI

When the component is defined as follows:

<property key="bgImage" type="image" required="false">
	<caption>Background Image</caption>
	<description>Image shown blurred in a background</description>
</property>

Then the Studio Pro UI for the component appears like this:

Widgets

The widgets property allows a user to place multiple widgets inside a pluggable widget, similar to the content of a container widget. It is passed as a ReactNode prop to a client component if a dataSource attribute is not specified or if an attribute is specified, but the data source is not configured by the user. Otherwise it is passed as a ListWidgetValue. For more information, see the Datasource section below.

XML Attributes

Studio Pro UI

When the component is defined without the dataSource attribute as follows:

<property key="content" type="widgets" required="false">
	<caption>Content</caption>
	<description>Content of a box</description>
</property>

Then the Studio Pro UI for the component appears like this:

Using the DataSource Attribute

When the component is defined with the dataSource attribute, assuming myDataSource is key of a datasource property defined elsewhere for this widget:

<property key="content" type="widgets" required="false" dataSource="myDataSource">
	<caption>Content</caption>
	<description>Widgets using data source</description>
</property>

Then the Studio Pro UI for the component appears like this:

Dynamic Types

Expression

The expression property allows a user to configure an expression.

If a dataSource attribute is not specified, or if a dataSource attribute is specified but the data source is not configured by the user, the client will receive a DynamicValue<T> where T depends on the expression’s return type.

When a dataSource attribute is specified and configured by the user, it is passed as a ListExpressionValue<T> where T depends on the expression’s return type. For more information, see the Datasource section below.

XML Attributes

XML Elements

<returnType> (required) — An expression property must contain a <returnType> element in order to define allowed return types for the expression. The Mendix Platform will ensure the that configured expression returns the correct data type.

Studio Pro UI

When the property is defined as follows:

<property key="progressBarColor" type="expression" defaultValue="'red'">
	<caption>Color</caption>
	<description>Progress bar CSS color</description>
	<returnType type="String" />
</property>

Then the Studio Pro UI for the property appears like this:

TextTemplate

The TextTemplate property allows a user to configure a translatable text template similar to the Caption of a text widget.

If a dataSource attribute is not specified, or if a dataSource attribute is specified but the data source is not configured by the user, the interpolated string will be passed to the client component as DynamicValue<string>.

When a dataSource attribute is specified and configured by the user, it is passed as a ListExpressionValue<string>. For more information, see the Datasource section below.

XML Attributes

XML Elements

<translations> — Allows a user to set a default value for text templates for different languages using <translation> elements with a lang attribute representing ISO 639 code of the language. Available languages are listed in the Languages Tab in Studio Pro.

Studio Pro UI

When the property is defined as follows:

<property key="myBlockTitle" type="textTemplate">
	<caption>Input title</caption>
	<description>Title for the color input</description>
	<translations>
		<translation lang="en_US">Color</translation>
		<translation lang="nl_NL">Kleur</translation>
		<translation lang="uk_UA">Колір</translation>
	</translations>
</property>

Then the Studio Pro UI for the property appears like this:

Action

The action property type allows a user to configure an action which can do things like call nanoflows, save changes, and open pages.

If a dataSource attribute is not specified, or if a dataSource attribute is specified but the data source is not configured by the user, the client will receive an ActionValue representing the action or undefined if the Do nothing action was selected.

When a dataSource attribute is specified and configured by the user, it is passed as a ListActionValue. For more information, see the Datasource section below.

XML Attributes

Studio Pro UI

When the property is defined as follows:

<property key="buttonAction" type="action">
	<caption>On click</caption>
	<description>Action to be performed when button is clicked</description>
</property>

Then the Studio Pro UI for the property appears like this:

Attribute

The attribute property type allows a widget to work directly with entities’ attributes, both reading and writing attributes. Depending on the widget’s purposes, a widget should define attribute types it supports.

If a dataSource attribute is not specified, or if a dataSource attribute is specified but the data source is not configured by the user, the client will receive an EditableValue<T> where T depends on a configured <attributeType>. For more information, see the EditableValue section of Client APIs Available to Pluggable Widgets.

When a dataSource attribute is specified and configured by the user, it is passed as a ListAttributeValue. For more information, see the Datasource section below.

XML

XML Elements

<attributeTypes> (required) — This element encapsulates <attributeType> elements which declare supported attribute types available while configuring the attribute property in Studio Pro.

<attributeType> (required one or more) — this element defines the allowed attribute type in the name attribute.

Studio Pro UI

When the property is defined as follows:

<property key="percentage" type="attribute" onChange="onPercentageChange">
	<caption>Percentage</caption>
	<description>Progress percentage</description>
	<attributeTypes>
		<attributeType name="Decimal"/>
		<attributeType name="Integer"/>
	</attributeTypes>
</property>
    
<property key="onPercentageChange" type="action">
	<caption>On change</caption>
	<description/>
</property>

Then the Studio Pro UI for the property appears like this:

Object

The object property type allows to create an arbitrary list of properties.

XML Attributes

XML Elements

<properties> (required) — This encapsulates the list or properties to be configured. For more information on property groups, see the Property Groups section of Pluggable Widgets API. Properties must be grouped by <propertyGroup> elements. Nested object properties are not supported.

Studio Pro UI

When the property is defined as follows:

<property key="myObject" type="object" isList="true">
	<caption>My object list</caption>
	<description/>
	<properties>
		<propertyGroup caption="Object list group">
			<property key="myObjectBool" type="boolean" defaultValue="true">
				<caption>My boolean</caption>
				<description>My boolean setting</description>
			</property>
			<property key="myObjectAction" type="action">
				<caption>My action</caption>
				<description>My action setting</description>
			</property>
		</propertyGroup>
	</properties>
</property>

Then the Studio Pro UI for the property appears like this:

File

The file property type allows a user to configure a file from an object that is a specialization of System.File. It is passed as a DynamicValue<FileValue> prop to a client component.

XML Attributes

Studio Pro UI

When the property is defined as follows:

<property key="file" type="file" required="false">
	<caption>File</caption>
	<description>Sample text file</description>
</property>

Then the Studio Pro UI for the property appears like this:

Datasource

The datasource property allows widgets to work with object lists. The client component will receive value prop of type ListValue and may be used with action, attribute, expression, text template and widgets properties. See Data Sources for available data source types.

XML Attributes

Studio Pro UI

When the property is defined as follows:

<property key="data" type="datasource" isList="true" required="false">
	<caption>Data source</caption>
	<description />
</property>

Then the Studio Pro UI for the property appears like this:

System Properties

System properties is a way for a pluggable widget to adopt extended widget functionality provided by Mendix Platform. System properties should be defined as <systemProperty> elements. The only property XML attribute <systemProperty> requires is key attribute, which defines a system property’s type. The following values are allowed:

• Label
• Name
• TabIndex
• Visibility
• Editability

Label

Label property allows a pluggable widget to have labeling functionality similar to a core input widget. This allows a user to set a label, a label position, and a label width. If a widget has a label configured, its client component will automatically be wrapped into a correct markup.

<systemProperty key="Label"/>

Name

Every widget have a name by default. This property can be used to control position of the widget name input. If this property is not specified, input will be placed in Common tab. A widget’s name is also used for locating it during automated tests. For that purpose in web apps, a widget name is automatically appended to a class prop a component receives, and in native mobile apps is passed as a separate name prop.

<systemProperty key="Name"/>

TabIndex

The TabIndex property allows pluggable widgets to implement the Tab index setting similar to a core input widget. Every selectable or input-like widget should opt for this to provide a consistent developing experience and an accessible app for an end-user. A widget’s tab index, when it is not zero, is passed to a client component in a tabIndex prop.

<systemProperty key="TabIndex"/>

Visibility

Every pluggable widget can be conditionally hidden. This property can be used to control a position of the widget visibility inputs.

<systemProperty key="Visibility"/>

Editability

The editability property allows a pluggable widget to have an editable configuration similar to a core input widget. When a widget is marked as read-only or conditionally editable with condition being false, all editable values its client component receives will have readOnly flag.

<systemProperty key="Editability"/>

Read More

• Pluggable Widgets API
• Client APIs Available to Pluggable Widgets (Mendix 8)
• Build Pluggable Widgets