Module Import for RBPM

0 Likes
over 3 years ago

The module IATools was initially created to simplify creation and usage of tab interfaces in User Application/RBPM. Its usage is simple - either embed the code inline in a form's script tab or save it in a web server's URL and point to it as an external resource. After that call the initial setup and start building and linking the different form elements into the desired tabs.

The module also comes with a sample workflow export that demonstrate the tab UI capabilities (with a simple, non-production CSS example for the tabs) as well as its picklist management capabilities.

Just go to https://github.com/fchierad/IAtools, download the desired file ( IAtools.js for lab/dev/ease of debugging, IAtools.min.js for production usage) and we can start. For this post I will be using the sample workflow provided with the library to explain its basic features, look at the libraries README.md file for further documentation on its functions.

The first step to use the library is to create a workflow, then a form and go to the Scripts tab. Click the sign and paste the contents of the selected library (will be using IAtools.min.js for this post).

Request Form Script Tag screen shot Request Form Script



 

This will create an ECMAScript object in the global scope named IAtools, and all the functions/APIs we will use are part of said object.

Since the library needs to be initialized with the RBPM framework objects to be able to work properly, next order of business is to add a form-wide onload event that passes these objects to the scripts, then capture them and pass the same to the library's init() function:

 

Form events section Form events section



Calling init() inside form_onload() Calling init() inside form_onload()



 

The tab UI functionality returns the HTML for the tabs to be inserted into a form's HTML field, and can be initialized in many ways. First we will create a function to instantiate the tab factory module, and with that instance we can append the information necessary for the different tabs and which fields will be inside them. Our end goal for this example is to have something like the images below, that we can then use CSS to provide proper theme and desired appearance. By default the library applies the CSS classes 'navbar', 'navitem', 'navactive' .in the tab control. We can change their actual names per instance by using the function setCSSClassName() .

 

3 Tabs from this example, please change the CSS so that they look in the way you desire! 3 Tabs from this example, please change the CSS so that they look in the way you desire!



 

First step in our function that will return the tab HTML exported functions to enable its behavior is to create a variable that holds a reference to the tabFactory API set. Then we can call the function addTab(id, name, order, fieldlist, cb) with its different parameters to add in-memory the tabs we want to create:

 

instantiating tabCtrlFactopry and adding the tabs to it.

 

The first parameter is the tab's ID, the second parameter is the Display name seeing in the UI, the third parameter is a number to force a certain order to the tabs (it does not have to be the insert order.

After that we have a few different approaches to work with the tabs - we can provide the names of the fields per tab, as they appear in Designer, and later setup these fields to react to certain events that will handle their visibility, that would use the 4th parameter that accepts an array. We could leave the array empty ( pass [] as the parameter) and instead provide a callback function to be executed when the tab is selected/de-selected. When the callback function is called 2 parameters will be passed to the same - the tab's ID and a string parameter. When a tab becomes active the second callback parameter is 'enter', when it becomes inactive the second callback parameter is 'leave'. Lastly we could mix both approaches, using one for visibility and the other for additional effects we want to occur when the tabs change.

For this example the approach chosen is to pass an array of field names to the addTab function. This approach has the advantage of self-documenting what the code is doing. This also means we need to setup events to handle the visibility of the form fields that will be switched as we click on the different tabs. The module does provide a function to make that task simpler - fieldVisibility(). To use the same just add an event to the form field with the code IAtools.fieldVisibility( event, field ); as shown below:

 

Adding visibility event to form field Adding visibility event to form field



 

All fields that will be part of a tab need their own visibility event. It is possible to have multiple fields with the same event, I just happen to prefer to have fine-grained control per field. After linking the visibility events on the necessary form fields we can let the tab control know their names and which fields they correspond to:

 

Linking field names to event names in the tab control Linking field names to event names in the tab control



 

Now if we already have the proper CSS to style the tabs with the desired appearance we can call getTabHTML() and set its return value on a form string-HTML field. Since in this example we don' t have any CSS aside form what comes with RBPM itself, we will use getSampleCSS() to obtain very simple, basic styling for the tabs (the one seen in the screen shot further above).

 

wrapping up and returning the auto-generated HTML. wrapping up and returning the auto-generated HTML.



 

On the background the function getTabHTML() both generates the HTML and exports the necessary JavaScript functions so that the tabs can work correctly as configured in the initialization we've performed inside our wrapper function. In this example we called the wrapper function also getTabHTML(), in reality it can have any name you desire. Please don' t confuse the wrapper function that we created in the script tab with the IAtools API function of the same name.

It is possible to initialize the contents of the HTML field in many ways, for this example instead of calling the function from inside the field's own "HTML Content" property it was chosen to set it up during form initialization along with other tasks:

 

HTML field initialization with Tab control HTML HTML field initialization with Tab control HTML



 

The library has also a few function to facilitate moving data between picklists, will leave as an exercise to the reader to import the sample work flow, play with the tabs and picklists then check the script's comments on how/why they are setup this way.

Labels:

Collateral
How To-Best Practice
Comment List
Anonymous
Related Discussions
Recommended