API for Widgets

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Define Forms > Extending or customizing Forms > Creating Widgets > Widget structure >

API for Widgets

Overview

To create a Widget, edit the [device]\[myWidget].js file by writing your own code in the functions to implement (i.e, getEditableControl(), getReadOnlyControl() and renderComplex()).

The following information provides a quick guide to the functions you may directly use in your implementation.

For more information about the [device]\[myWidget].js file, refer to Widget structure.

 

Methods to retrieve information from the Widget

These methods are provided by the this object reference.

Keep in mind that all properties can be accessed by using: this.properties.[your_property] (when these properties are not set explicitly as asynchronous).

 

 

METHOD

DESCRIPTION

getPropertyValue(string propertyName)

Returns the promise of a jQuery deferred object (https://api.jquery.com/promise/).

You may use it to obtain values from a Widget property which was set as asynchronous (async=true).

Use of this promise will require that you define a function at .done().

 

NOTE:
Recall that in a Widget you may have properties of the rule type.

Rule-type properties allow you to execute a business rule in Bizagi from the Widget, through this method, as described at Defining properties.

getServerResourceURL(string relativeURL)

Returns the promise of a jQuery deferred object (https://api.jquery.com/promise/).

You may use it to obtain a string having the full path of a auxiliary file placed inside the Widget.

ready()

Returns the promise of a jQuery deferred object (https://api.jquery.com/promise/).

You may use it to execute a function ensuring that the Bizagi has finished displaying the Widget.

getValue()

Returns the current value held in the Xpath of that Widget (if using an Xpath).

It is helpful when rendering the Widget so that you consider if that Xpath has a value already set/stored.

 

Notice that to set the value into the Xpath, you may similarly use setValue(string value).

getDisplayValue()

Returns a string having the display value for that attribute (recall that when not defined explicitly in the form, it will take the value as set in the data model).

getControl()

Returns a jQuery object ($) having the complete HTML of the Widget.

 

 

Methods to obtain information from other resources

These should help out when wanting to display other information or use formatting.

 

METHOD

DESCRIPTION

getRenderValue(string Xpath)

Returns the value held in an Xpath within that same form (it is required that such Xpath is included as a native control within the Bizagi form).

The specified Xpath is set as "Entity.Attribute".

bizagi.localization.getResource(string resourceName)

Returns a resource object which haves localization definitions.

Possible resources are (by their names):

dateFormat

timeFormat

numericFormat

 

When using "numericFormat", you may access its internal properties, which are:

symbol: the symbol used for currency values.

decimalSymbol: the symbol used for decimals represented in float and real values.

digitGroupSymbol: the symbol used to group values (by thousands).

 

Methods to trigger changes in the Widget

These should help out when wanting to apply overall changes.

 

METHOD

DESCRIPTION

changeColor (string color, boolean isLabelFormat)

Changes the color to a specified one in HEX format, of all characters (text) held within the Widget (span, label, h1, etc).

Its use requires:

That other CSS styles of your own are not affecting such texts.

That setting isLabelFormat to true considers that the display type for such control is set to "both" (otherwise the label is actually not shown).

changeBackgroundColor (string color)

Changes the background color to a specified one in HEX format, of the background of the entire Widget (the parent div to that one you defined representing your Widget).

Its use requires:

That other CSS styles of your own are not affecting such texts.

changeFontBold (boolean bold, boolean isLabelFormat)

Changes the font weight to bold or to normal (true to toggle bold, false to revert back to normal), of all characters (text) held within the Widget (span, label, h1, etc).

Its use requires:

That other CSS styles of your own are not affecting such texts.

That setting isLabelFormat to true considers that the display type for such control is set to "both" (otherwise the label is actually not shown).

changeVisibility(boolean visible)

Changes the visibility of the Widget.

True to display it, or false to hide it.

changeEditability(boolean editable)

Changes the editability of the Widget.

True to enable it, or false to set it as read-only.

 

 

Utility and validations

Consider the following which may come in handy for diverse purposes:

 

METHOD

DESCRIPTION

navigator.onLine()

Evaluates if the accessing client has connectivity to Internet (in which case it returns true). Otherwise, it returns false.

Useful when integrating with Web or REST services at the cloud.

bizagi.util.isIE()

Evaluates if the accessing client is an Internet Explorer browser  (in which case it returns true). Otherwise, it returns false.

Similarly, we recommend using: util.isIE8(), util.isIE9(), util.isIE10().

bizagi.util.parseBoolean (string booleanProperty)

Parses the value of a boolean property (to return true or false).

getMode()

Returns string with the word "design" when rendered in the forms designer, and returns "execution" when at the Work portal's runtime so that you can define a simple presentation when in the forms designer.

 

Trace methods

Consider these ideally instead of using the JS alert() function:

 

METHOD

DESCRIPTION

bizagi.log (string trace)

Records at the log shown when using http://[your_server]/[your_project]/defaultdebug.aspx

Most useful in the Simulation module, to print a custom message.

console.log(string trace)

Records at the javascript console provided by browsers such as Google Chrome or Mozilla Firefox (those supporting Webkit).

console.error(string trace)

Most useful in the Simulation module, to print a custom message under the Error category of messages.

console.warn(string trace)

Most useful in the Simulation module, to print a custom message under the Warning category of messages.

console.time(), console.timeEnd()

Most useful in the Simulation module, to print a custom message under the Information category of messages.

 

 

Common and useful jQuery and Javascript methods

You may use any methods provided by jQuery and Javascript in your implementation.

We list a few useful ones which should help you to cover common requirements.

Full information about jQuery's method can be reviewed at: http://api.jquery.com/.

 

METHOD

DESCRIPTION

setTimeout(function toExecute, int milliseconds)

A javascript method that allows you to execute a function after an amount of milliseconds have passed by.

[object].addClass(string className)

A jQuery method for any object, so that you may dynamically assign a CSS class to your HTML element.

Its CSS class is expected to be defined at the CSS Stylesheet.

[object].removeClass(string className)

A jQuery method for any object, so that you may dynamically remove a currently assigned CSS class from your HTML element.

[object].attr()

A jQuery method for any object, so that you may get (or set, by sending a parameter) the value of an HTML attribute.

[object].append(string content)

A jQuery method to append HTML content into any object.

[object].appendTo([object myObject])

A jQuery method for any object to be inserted into the myObject object.

 

 

Common and useful predefined events (used by jQuery)

You may define any custom functions to be executed when certain events happen to your HTML elements.

We list a few useful predefined events provided by jQuery's notation, to help you to cover common requirements.

Note that all events will receive:

A first parameter which is an Object through which parameters are passed.

A second parameter which is a function() definition so that this function is executed whenever the event happens.

 

Full information about jQuery's events can be reviewed at: http://api.jquery.com/category/events/.

 

EVENT

DESCRIPTION

[object].click()

When the object is clicked on.

[object].hover()

When the mouse pointer hovers over the object.

[object].focusout()

When the object loses focus (usually for inputs).

[object].focus()

When the object has focus (usually for inputs).

[object].keypress()

When any key is pressed (usually for inputs).

[object].change()

When the value changes and focus is usually moved out to another object.

 

Common and useful CCS selectors

Recommended and common CSS definitions are based on the principle of being very specific and avoid affecting other elements on a general level, which you do not want to affect.

The more specific you can define classes and CSS styles, the better.

 

CSS SELECTOR

DESCRIPTION

.[class]

Replace [class] with the name of the class and styles will apply to elements using that class.

#[id]

Replace [id] with the ID of a specific element, and styles will apply to that element.

.[class] [element]

Replace [class] with the name of the class. Replace [element] with any HTML element such as p, a, input, button, label, span, etc, so that styles will apply to such elements inside of a parent element using the above class.

.[class1] .[class2]

Similar to the above, this time having to replace [class1] with the name of the class of a parent element, and replace [class2] with the name of the class of inner elements, so that styles apply to those inner elements.

.[class] + [element]

Replace [class] with the name of the class. Replace [element] with any HTML element such as p, a, input, button, label, span, etc, so that styles will apply to such elements placed immediately after that one using the above class.

 

For a starting reference on CSS selectors, you may refer to third-party documentation such as https://www.w3schools.com/cssref/css_selectors.asp.

 

Important

Consider these notes when using the API for Widgets:
 

1. You may use the this reference to use properties and methods.

 

2. You may rely on the Widget Editor's functions help to use and search the API.

While editing a js file, you may locate a specific function and insert its code:

 

WidgetEditor_API

 

3. At any time, you may use the IntelliSense feature by pressing CTRL + space bar:

 

UIExplained_Intellisense