Skip to main content

Properties' Definitions

Overview​

Properties in a Widget allow you to:

  • Access (both to obtain and update) business information from your process data model.
  • Use configurable parameters, enabling the Widget to be a reusable UI building block across various processes and activities.

For information on how to add or edit a property, refer to the Widget Editor user interface documentation.

Property Type​

You need to define the valid data type for a property to ensure that Bizagi Studio users can configure it appropriately.

Bizagi Forms Designer automatically filters and validates that the assigned property value matches the expected data type. For instance, if a property is an XPath, only an XPath from your data model can be selected.

Some properties may require further configuration using sub-properties.

Property Type Table​

Property's Type ValueWhat It Is ForFurther Configuration
Simple Data Binding (XPath-to-simple)For string, integers, Boolean, and other simple type attributes in your data model (XPath).Choose a specific data type for the XPath: Text, Number, Boolean, Date, File upload, Image, or File Upload ECM.
Entity Data Binding (XPath-to-entity)For a pointer reference to another entity in your data model (XPath).None.
Collection Data Binding (XPath-to-collection)For a collection of records from a 1-n relationship (Bizagi collection in the data model).None.
Business Rule (rule)For a business rule's return value, calculated by the server using Bizagi rules.Ensure the rule is executed asynchronously.

Additional Property Types​

  • int: For non-XPath integer values (information not in your data model).
  • boolean: For non-XPath Boolean values (information not in your data model).

    Always define a default value when using Booleans.

  • string: For non-XPath string labels (information not in your data model).
  • localizable-string: For non-XPath string labels presented in multiple languages (information not in your data model).

Note:
Each property type is set in its internal attribute called bas-type. A property's caption (display name) can be localized. To specify if a property is required, use the required attribute (true/false). For detailed information about defining properties, refer to the Widget Structure documentation.

When defining configurable properties in a Widget, include or edit them while considering their type and capabilities.

Note:
Properties are defined in the myWidget.json file within the Widget's structure. Properties are separately defined in the JSON structure for:

  • Design: Includes its configuration.
  • Runtime: Specifies its behavior during execution. The image below demonstrates the definition of a "My property" property for design: WidgetEditor_MyProperty

Properties Use​

Refer to the pointers below to use your properties at runtime (coded in the myWidget.js implementation file).

Loading Properties and Their Values​

Loading properties for runtime access is already handled by the default starting Widget template.

You can use the following code to load properties:

var properties = self.properties;

To access the value of a specific property, use:

properties.[your_property];

Note:
The value of the main XPath property can be obtained using: self.properties.value

Default Values for Properties​

If you need to use a default value (e.g., to ensure preset information is applied), consider the following implementation in your file:

var displayName = properties.displayName || "Default display name";

In the example above, if the displayName property was not explicitly set in the forms designer, the text "Default display name" will be used as the fallback.

Asynchronous Properties (Type: "rule")​

When using properties of the type rule, it is common to access their returned values asynchronously. This is achieved by setting "async": "true" in their runtime definition.

To access such a property and its value at runtime, use:

var self = this;

self.getPropertyValue("dataRule").done(function (data) {
  bizagi.log("data", { data: data.value });
});

Notice that in this example above, our rule property is called dataRule.

Note:
The getPropertyValue(propertyName) method is a deferred object which handles a promise (for the asynchronous treatment).

For more information about this concept, refer to http://api.jquery.com/deferred.promise/.

Additional notes​

  • Recall that the XPath property (with this exact same name) will allow you to define if some values are to be bound directly to your data model. But, you may use and define more than 1 XPath (multiple bound information from the data model) per Widget. If this is your case, then, it is strictly required that the first bounded information is called XPath.
  • Properties may have sub-properties. Include sub-properties by using subproperties and having the same structure as a property.