Overview
To create a Widget, consider that its implementation will vary significantly according to the objective and expected behavior of the Widget.
Creating Widgets is done by using the Widget Editor and as described at Creating Widgets.
What to consider beforehand
The following aspects and questions should be considered when planning to create a Widget:
1. Editable and non-editable behavior
A Widget should behave different when set as read-only and when not set as so. According to this, consider:
•How should the Widget be displayed and what will it allow the user to do exactly, when set as editable?
•How should the Widget be displayed when set as read-only? What advantages will it provide when read-only when compared to using the default controls in Bizagi?
Notice that it is possible that you do not want to implement a Widget to be both editable and read-only. Some Widgets' potential could be aimed exclusively at capturing information (e.g., a web cam Widget), while others could be useful only to display read-only information (e.g. a chart).
2. Devices and browsers
Thanks to the powerful design capabilities in Bizagi's, any Widget in the UI is able to be displayed on any device.
However, you should ask yourself the following, depending on the limitations and functionality for each device/browser, if what you wish to accomplish is possible or if it adds value. Consider:
•Will the Widget be available when accessed from all devices (desktop, tablet, smartphone), or only from a specific one?
•When available from all devices, will there be slight changes in the width or appearance of the Widget (i.e, when displayed in smartphones, width sizes should be optimal)?
•Will the Widget be available when accessed from all browsers and browser versions? If so, keep in mind that the functions/APIs you use, need to be supported in such possibilities.
Notice that it is also possible that some Widgets make more sense for some devices (e.g. such as a web cam which is designed to capture photos). Given that mobile and tablet devices usually already offer a built-in capability to take photos, such Widget is most helpful when used in a desktop.
3. Plugins and third-party libraries/services
A Widget may rely on jQuery plugins or your own libraries or external services (including cloud-based ones).
Consider the following:
•Are you planning on reusing a specific plugin?
•Will the Widget rely on an additional JS library or services?
Note that for services, you will need to acknowledge if this needs internet connectivity or any other special access considerations (keys, tokens, credentials in general).
•Does the plugin require a specific jQuery version?
If you need a specific jQuery version other than the one bundled within Bizagi, you will need to use and understand how to use namespaces for jQuery functions and make sure that you can include jQuery into the libraries without generating conflicts.
4. Configurable parameters and XPath
A Widget needs configurable parameters so that it is as reusable as possible in different processes and different stages of a process as well.
It also will likely need and use one or more XPath definitions so that it can be bound to any process while using its business data.
Consider the following:
•Which parameters will the Widget need?
•Which should be configurable properties in design, and which shouldn't?
•Will the Widget specifically need a Bizagi XPath parameter (either to retrieve or to save information into the data model)? If so, will it need more than 1 Bizagi XPath?
Note that a collection represents 1 XPath in Bizagi, but it implies a different treatment than for "simple" Xpaths (i.e, string, integer, etc).
If you need specific information from your project, you may rely on having a business rule as a property.
5. Context and special considerations
When creating a Widget for Bizagi, it will have important underlying differences in its definition depending on 2 possible contexts: when used inside a table or not.
Widgets used inside a table are referred to as column Widgets and entail a higher complexity than those used on the outside of the table (in other words, placed right in the main form).
Consider the following:
•Are there any special considerations for its use?
Special considerations may imply the fact that your Widget will be extending an existing control provided by Bizagi.
For instance, this may mean for Widgets which manipulate records of a collection (add, edit, or delete them), that you are extending a table.
And therefore, your Widget will demand that you also include the table as a control within the same Bizagi form (i.e,. a requisite of your Widget).
•Is the Widget planned to be shown inside of a table or not?
If you need to cover up both scenarios, you will need 2 different Widgets though most of the code you may reuse.
|
Before you start creating Widgets, it is really important to make sure that the HTML and jQuery code you want to implement, already works. This means that separately from Bizagi, you should already have a demo.html page presenting what you want to do in a fully functional status. |
Suggested steps on a high level
When moving forward and actually creating the Widget with the Widget Editor, consider the following suggested steps.
Note that as a general guideline, the idea is for you to start little by little and implement functionality in your Widget incrementally.
1. Define your Widget as a control in your form, or to be inside of a table
This is a mandatory first step prompted when creating the Widget.
2. Include needed jQuery plugins or libraries, if applicable
Do this first to make sure that plugins are not causing conflicts at this point.
You should be able to simulate the default Widget template while having the JS plugins included.
You may then also include CSS while ensuring that you are not adding CSS styles that affect general elements or the UI overall (not affecting <body>, all <p> etc).
3. Define the basic properties that your Widget will use
Define the basic property such as XPath, and those you consider strictly needed.
Make sure you periodically simulate your WIdget to make sure everything is going OK.
4. Implement the look and feel for the simpler scenario
Most likely the simpler scenario is the one to display the Widget as read-only (if applicable).
By implementing this scenario, simply make sure that your Widget draws HTML appropriately within the getReadOnlyControl() function.
5. Implement the behavior
Implement the renderComplex() function to trigger the behavior in your Widget so that it actually does what it is designed to do.
Make sure you can simulate it.
While ensuring it runs OK, consider adding scenarios to the simulation data to cover more than one combination regarding its configuration.
At this point you may also proceed to implement the look and feel for the other scenario if applicable (most likely the getEditableControl()).
6. Tune it and include additional enhancements
At this point you may include additional properties for higher customization or configuration possibilities.
It is encouraged to divide the code so that you implement separately what the Widget does while being previewed in the forms designer (should be simpler than in runtime).
You may also enhance its styling add icons, and finally replicate changes to mobile and tablet support if planned to within your Widget's scope.
Last Updated 1/6/2022 11:29:56 AM