Build Widgets with XML

Requirements

This document assumes you have a basic understanding of XML and Mendix Studio Pro. For more information on XML, visit W3 Schools - XML.

Start of the Widget XML

An XML file always starts with the XML version and encoding declaration. These are standard and should be present in every XML file. Mendix Studio Pro uses the widget XML file to create the property input fields, which show up when you add your widget to a form. Our widget declaration XML starts at the <widget> element. This is the root element that will contain all our settings for this widget.

Widget Element

Attributes

Child elements

Inside the widget element are 4 child elements.

<widget id="HelloWorld.widget.HelloWorld" needsEntityContext="true" xmlns="http://www.mendix.com/widget/1.0/">
  <name>HelloWorld</name>
  <description>The description of this widget.</description>
  <icon><!-- Base64 icon here --></icon>
  <properties>
   <!-- Define the widget properties here -->
  </properties>
</widget>

Property element

Any properties you define in your widget XML file can be set using Mendix Studio Pro and they will be passed to your JavaScript file, so you can use them in your widget.

Child elements

Every property element contains at least the following 3 child elements.

Attributes

All property elements define at least 2 attributes: key and type. The value of key is the name of the property in your widget, so use a descriptive name. The value of type refers to the type of the property, for example “string” or “integer”. Based on the type of the property, you may have to define additional attributes and/or child elements.

Other possible attributes are:

The different property types and their respective required attributes are discussed below.

Property Types

Every property requires the key and type attribute.

Any property can have the isDefault or required attribute.

Attribute

A property of type Attribute is always related to an entity: it uses the entityContext if it is set on true, otherwise an entityProperty is required. It enables the user in Mendix Studio Pro to select one of the attributes of the related entity (optionally over an association).

<property key="backgroundColor" type="attribute" entityProperty="color">
 <caption>Background Color</caption>
 <category>Data source</category>
 <description></description>
 <attributeTypes>
   <attributeType name="String" />
 </attributeTypes>
</property>

An attribute property has an extra required child element: a list of attributeTypes that define what type of attributes are accepted. This could be any of the following:

• AutoNumber
• Binary
• Boolean
• Date and time
• Decimal
• Enumeration
• Hashed String
• Integer
• Long
• String

Boolean

A property of type Boolean requires the attribute defaultValue.

<property key="isVisible" type="boolean" defaultValue="true">
 <caption>Visibility</caption>
 <category>Data source</category>
 <description>Whether the widget is initially visible.</description>
</property>

What it looks like in Mendix Studio Pro:

Entity

A property of the type Entity allows the user to configure a non-persistable entity in Mendix Studio Pro. This entity can then be used in your JavaScript to retrieve all the necessary information.

<property key="color" type="entity" isPath="optional" allowNonPersistableEntities="true" pathType="reference">
 <caption>Color</caption>
 <category>Data source</category>
 <description>The Color entity to use.</description>
</property>

EntityConstraint

The EntityConstraint lets you put a constraint on either the entity you specify with entityProperty or, if needsEntityContext is set to true and no entityProperty is defined, to the entity passed as context.

<property key="constraint" type="entityConstraint" entityProperty="color">
 <caption>Color constraint</caption>
 <category>Data source</category>
 <description>The XPath constraint on the entity.</description>
</property>

Enumeration

The enumeration property has an extra required child element: a list of enumerationValues. An enumerationValue contains a key attribute and a caption within their tag.

This presents the user with a drop-down list of options, based on the captions in Mendix Studio Pro. The keys will reach your widget’s JavaScript as an enumeration.

It requires a default value to be set, which should correspond with one of the enumerationValue keys.

    <property key="colorEnum" type="enumeration" defaultValue="xff0000">
      <caption>Textcolor</caption>
      <category>Appearance</category>
      <description>The textcolor of the message in the widget</description>
      <enumerationValues>
        <enumerationValue key="xff0000">Red</enumerationValue>
        <enumerationValue key="x000000">Black</enumerationValue>
        <enumerationValue key="xffffff">White</enumerationValue>
      </enumerationValues>
    </property>

What it looks like in Mendix Studio Pro:

Form

The form property lets you pass a form to the widget. If needsEntityContext is set to “true”, it automatically receives the object context.

<property key="helpForm" type="form">
 <caption>Help Form</caption>
 <category>Behaviour</category>
 <description>Form to open</description>
</property>

Image

The image property lets the user select an image from Mendix Studio Pro’s images to pass it to the widget.

<property key="picture" type="image">
 <caption>Picture</caption>
 <category>Data Source</category>
 <description>Select an image to add.</description>
</property>

Integer

The integer property lets you to pass an integer to the widget. This property requires the attribute defaultValue.

<property key="height" type="integer" defaultValue="1">
 <caption>Height</caption>
 <category>Appearance</category>
 <description>The height of the widget</description>
</property>

Microflow

The Microflow property allows a user to select a microflow in Mendix Studio Pro. There are three options:

1. If needsEntityContext is set to “true”, the selected microflow is required to have the context entity as an input parameter (as this will automatically be passed into it).
2. If needsEntityContext is set to false and no entityProperty attribute is specified, the microflow will have no input parameters.
3. If the entityProperty attribute is specified, the selected microflow is required to have this entity as an input parameter.

<property key="messageMicroflow" type="microflow" required="false">
 <caption>Message Microflow</caption>
 <category>Data source</category>
 <description>Return value: the message to show.</description>
 <returnType type="String" />
</property>

The Microflow property has an extra required child element: returnType. Use this to set what type of value you return. Studio Pro will then enforce this on the microflow that is assigned.

Possible return types are shown below:

• Void
• Boolean
• Integer
• Date and time
• String
• Object

Nanoflow

The Nanoflow property allows a user to select a nanoflow in Mendix Studio Pro. There are three options:

1. If needsEntityContext is set to “true”, the selected nanoflow is required to have the context entity as an input parameter (as this will automatically be passed into it).
2. If needsEntityContext is set to false and no entityProperty attribute is specified, the nanoflow will have no input parameters.
3. If the entityProperty attribute is specified, the selected nanoflow is required to have this entity as an input parameter.

<property key="validationNanoflow" type="nanoflow" required="false" needsEntityContext="true">
 <caption>Validation Nanoflow</caption>
 <category>Behavior</category>
 <description>Return value: whether the given object is validated successfully</description>
 <returnType type="Boolean" />
</property>

The Nanoflow property has an extra required child element: returnType. Use this to set what type of value you return. Studio Pro will then enforce this on the nanoflow that is assigned.

Possible return types:

• Void
• Boolean
• Integer
• Date and time
• String
• Object

Object

The object property is an array of packaged sub-properties. It packages multiple other properties into an object, of which multiple can be passed to the widget. It always requires the isList attribute, which needs to be set to “true”.

<property key="collection" type="object" isList="true">
 <caption>Collection</caption>
 <category>Appearance</category>
 <description>Add the properties to show in your collection</description>
 <properties>
	<!-- Define the sub-properties here -->
	<property key="number" type="integer" defaultValue="1">
     <caption>Number</caption>
     <category>Data source</category>
     <description>Give us a number</description>
    </property>
    <property key="text" type="string">
     <caption>Text</caption>
     <category>Data source</category>
     <description>And a text!</description>
    </property>
 </properties>
</property>

What it looks like in Mendix Studio Pro:

String

The string property lets you to pass a string to the widget.

<property key="message" type="string">
 <caption>Message</caption>
 <category>Data source</category>
 <description>A hardcoded message</description>
</property>

TranslatableString

The translatableString property is similar to a normal string property, except you can add translated versions of the default value for different languages. To achieve this, the translatableString property has an extra required child element: a list of translations. The Mendix Studio Pro language will match the assigned value.

<property key="translatableMessage" type="translatableString">
 <caption>Message</caption>
 <category>Data source</category>
 <description>A hardcoded message</description>
 <translations>
  <translation lang="en_US">Add your message here.</translation>
  <translation lang="nl_NL">Vul hier je bericht in.</translation>
 </translations>
</property>

What it looks like in Mendix Studio Pro: