Build Widgets with XML
1 Requirements
This document assumes you have a basic understanding of XML and Mendix Studio Pro. For more information on XML, visit W3 Schools - XML.
2 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.
3 Widget Element
3.1 Attributes
Attribute | Description |
---|---|
id | The id is where your widget is located. The path to the js file, starting at the root folder, separated by dots. Note that this is case-sensitive. |
needsEntityContext | This Boolean determines whether your widget requires an object to be passed as the EntityContext and is required. If this is set to “true”, the widget can only be used within a dataview or a templategrid. If set to “false”, the widget can be used anywhere, but won’t have an object passed to it automatically. |
offlineCapable | This Boolean determines whether your widget can be used on pages that are accessible through the offline profile. If this attribute is not set, or set to “false”, the widget cannot be used offline. If set to “true”, the widget can be used offline. Keep in mind that there are a number of restrictions when working offline. Calling a microflows or fetching data using XPath are examples of features that are not supported offline. For more information, see the Ensuring Your App Is Offline-First section of Offline First. |
xmlns | The XML namespace used by the widget. The value of this attribute is the same for every widget. <widget id="HelloWorld.widget.helloworld" needsEntityContext="true" xmlns="http://www.mendix.com/widget/1.0/"> |
3.2 Child elements
Inside the widget element are 4 child elements.
Element | Description |
---|---|
Name | The name property is what your widget will be called in Mendix Studio Pro. It will also be used to name the different instances of your widget by adding a number to the end of it each time it is used in a form. |
Description | The description determines the mouse-over tooltip over your widget in the Custom Widgets toolbar. |
Icon | Every element or widget in Studio Pro has its own icon. Your new widget’s icon can be defined with this property. It is a Base64 representation of the image, so that it can be used in an XML file. |
Properties | The individual property elements will be grouped inside the “properties” element as in the code snippet below. |
|
|
4 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.
4.1 Child elements
Every property element contains at least the following 3 child elements.
Element | Description |
---|---|
Caption | This element is used to add the name of the property. This is how it will show up in the Properties list in Mendix Studio Pro. |
Category | This element defines in what category this property will be shown in the Properties list in Mendix Studio Pro. Common categories are “Behavior”, “Appearance” and “Data source”. |
Description | This element is used to add a useful description of the property, so the end-user knows what it’s for. |
4.2 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:
Attribute | Description |
---|---|
isList | Only used for the Object property type. |
entityProperty | Assigns an entity to a property. This should point to the key attribute of the entity to which it is related. This could also be relative (like "../entityName" ) when the attribute is inside an object list: <property key="key" type="object" isList="true"> |
allowNonPersistableEntities | Allows the selection of a non-persistable entity. (By default this is false.) |
defaultValue | The default value that a property starts with when it is created. |
required | Specifies if the property is a required field or not. Defaults to “True” if not present. |
isDefault | Marks a property as the default property that is selected when the widget is selected. |
multiline | Makes the string input multiple lines, which is useful for long texts. |
parameterIsList | Requires the parameter of a microflow to be a list of the type defined in the entityProperty. |
isPath | (“no”, “optional”, “yes”) The path for an attribute or entity property, it can be either “no”, “optional” or “yes”, where “no” is the default value if the property is left out. The “optional” means that the attribute/entity can be either the current entity (or an attribute of the current entity) or an entity (or attribute) over a 1-deep association. |
pathType | (“reference”, “referenceSet”) This defines what sort of reference should be shown for an entity/attribute over an association, either a “reference” or a “referenceSet”. |
The different property types and their respective required attributes are discussed below.
5 Property Types
Every property requires the key and type attribute.
Any property can have the isDefault or required attribute.
5.1 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).
|
|
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
5.2 Boolean
A property of type Boolean requires the attribute defaultValue.
|
|
What it looks like in Mendix Studio Pro:
5.2.1 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.
|
|
5.2.2 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.
|
|
5.2.3 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.
|
|
What it looks like in Mendix Studio Pro:
5.2.4 Form
The form property lets you pass a form to the widget. If needsEntityContext is set to “true”, it automatically receives the object context.
|
|
5.2.5 Image
The image property lets the user select an image from Mendix Studio Pro’s images to pass it to the widget.
|
|
5.2.6 Integer
The integer property lets you to pass an integer to the widget. This property requires the attribute defaultValue.
|
|
5.2.7 Microflow
The Microflow property allows a user to select a microflow in Mendix Studio Pro. There are three options:
- 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).
- If needsEntityContext is set to false and no entityProperty attribute is specified, the microflow will have no input parameters.
- If the entityProperty attribute is specified, the selected microflow is required to have this entity as an input parameter.
|
|
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
5.2.8 Nanoflow
The Nanoflow property allows a user to select a nanoflow in Mendix Studio Pro. There are three options:
- 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).
- If needsEntityContext is set to false and no entityProperty attribute is specified, the nanoflow will have no input parameters.
- If the entityProperty attribute is specified, the selected nanoflow is required to have this entity as an input parameter.
|
|
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
5.2.9 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”.
|
|
What it looks like in Mendix Studio Pro:
5.2.10 String
The string property lets you to pass a string to the widget.
|
|
5.2.11 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
|
|
What it looks like in Mendix Studio Pro: