General guidelines for creating new widgets

<< Click to Display Table of Contents >>

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

General guidelines for creating new widgets


When creating a new widget, make sure to fully understand its purpose, keep the coding best practices, and its business value. This section provides some guidelines to keep in mind for the creation of a new Widget. Through these guidelines, the Widget is created following coding best practices, and having a high business value and robustness.


Coding best practices

When coding the Widget, follow best JS and CSS practices as determined by Bizagi Ltda.

Tips and guidelines are mentioned here.


Business value guidelines

When designing a Widget, make sure you consider the following guidelines, which add business value:


1. Localize the widget

Make sure that the widget's name and its category are localized.




2. Define customizable properties

Properties in a Widget will allow you to access business information of your process data model. When creating a property that is going to be displayed in runtime by the Widget (i.e. a label), make sure that is customizable. For instance, these properties should support localization, so that the labels can be set in any language and support Unicode characters.




3. Properties in Bizagi Studio

Properties should follow these considerations:

Properties should be as grouped as possible in tabs. To create a new one, click Layout in the properties section and add a new tab.




The Visible, Editable and Required properties should always be displayed in the Basic tab.

If there is a boolean property which needs to be set to true, in order for other properties to make sense, then such boolean property should come first, followed immediately by those other depending on it. For example in order for a property to be required, it must be editable; also, for a property to be editable, it must be visible. Thus, the order of these three properties should be visible - editable - required.




4. Icons for the Studio

The previewing icon should be a flat-design icon, and the forms designer control's icon (small4.png) should use 16x16 dimensions.




5. Create once, execute anywhere

The Widget Editor allows you to define the styles of the widget for every device. That is, for desktop, tablets, and smartphones.




6. Widget design preview

The forms designer follows a what-you-see-is-what-you-get principle, and as so, a Widget should reflect in design time what it would depict in runtime. Also, keep in mind that the editor provides a simulation feature, where you will be able so see your widget in action.




7. Buttons styling

The Widget's buttons should use Bizagi's default button styling. For instance, using classes which allow it to have same color, shading, font-size, and general styling such as inputs using ui-bizagi-button ui-button-text  ui-button ui-widget ui-state-default ui-corner-all.


8.  Licensing considerations

When using a jQuery plugin or third-party library, it is advisable that you use one that is MIT licensed (or similar types of licenses) in order for the Widget to be easily distributable and reusable by Bizagi projects.

Types of licenses for plugins or libraries which are not advisable are those which fall into the Strong copyleft category such as GNU, GPL or AGPL.

Others which can be used but demand that no modifications are done to the plugin, are those which fall into the Weak copyleft category such as LGPL, EPL (Eclipse Public License) or MPL



At this point, it is expected to already have an agreement on:

The friendly name of the Widget.

The icon it should use.

How it behaves overall, or what it's main purpose is (when editable or read-only).


Making the Widget publicly available

Once the Widget has been developed, make sure you explicitly clarify:

The list of properties configurable by the Widget, what each property does and if which predefined set of values it uses if applicable to that property.

Any third-party service that is employed.

oIf so, state if credentials or API keys are needed, or if internet connectivity to a particular site is needed (include the URL of the service).

If the Widget is meant to be used solely as editable, solely as read-only, or can be used as both.

If the Widget relies solely on the public API or if it uses RESTful services or information which is encapsulated by Bizagi itself as a product.