This series will explain how you can use widgets from a separate, unrelated library of widgets—PrimeUI—so that you can populate these widgets with data from a server and submit data from the widget back to the server. Not only will these widgets be usable in your production environment, you can also see them rendered in design-time in Visual Designer for drag and drop design.
This article will cover installing the PrimeUI code and connecting it to Profound UI.
The PrimeUI widget, “rating”, will be used as an example. A file at the end of the article also includes code to wrap a PrimeUI “date picker” widget.
Code from, “Painlessly Passing Custom Widget Input Data to the Server,” will be used to take input from our sample widget and help pass it to the server. You may want to review that article before digging into the code in this article.
Files must be downloaded somewhere Profound UI can access them—likely either in the “htdocs” directory for an instance of an IBM HTTP Server (by Apache) running Profound UI, or the “htdocs” directory of an instance of Profound.js. In this article we assume the files are downloaded into a directory named “primeui” in the document root of an IBM HTTP server instance. For example, if you have an instance of Profound UI named “PROFOUNDUI” that is setup under the IFS path, “/www/profoundui”, then the PrimeUI files will go into an IFS directory named “/www/profoundui/htdocs/primeui”.
Download the files from here: https://www.primefaces.org/primeui/ by clicking the download button, then click the link to the latest version’s zip file,
“primeui-4.1.15.zip” in this case.
Save the zip file to your PC. Create the “primeui” IFS directory if it doesn’t exist in the Document Root of the instance of Profound UI. (e.g. in QSH on the IBM i do “cd /www/profoundui/htdocs/” and then “mkdir primeui”). Upload the zip file into that “primeui” directory. Unzip the file into “primeui” (e.g. in QSH do “unzip primeui-4.1.15.zip”).
You should now have some files in the primeui folder, including these:
Next, download the file “prime-profound-fix.css”, linked at the end of this article, and upload it into the “htdocs/primeui” directory. This file fixes some PrimeUI CSS that clashes with Profound UI CSS.
When those files exist, then the PrimeUI library code is on the webserver ready to be used. Note that those files are not automatically loaded with sessions running Profound UI, because they are not located inside /profoundui/userdata/custom/. We do not want the PrimeUI code to load unless a screen explicitly uses those widgets. (Doing so potentially saves network bandwidth and improves the time needed to render the session at sign-on.) Some custom code included later in the article will load the PrimeUI files on-demand.
Connecting a PrimeUI Widget to Profound UI
Now that the PrimeUI files are in place, we need a way to tell Profound UI how to use some of the PrimeUI widgets. There is no automated or trivial way for connecting PrimeUI widgets into the Profound UI framework. Instead, each widget must be attached manually using Profound UI’s Custom Widget API. Basically, wrapper code must be written around each PrimeUI widget so that Profound UI can use it.
Code to wrap a Rating widget is provided further below. Also, code is provided for connecting the pieces in a uniform fashion.
As explained in the article, “Painlessly Passing Custom Widget Input Data to the Server”, in the “Create a Basic Custom Widget” section, a few steps in adding a widget to Profound UI include:
- Define properties of the widget, including “property setter” functions
- Define custom properties when necessary
Property setters are needed because of how Profound UI renders widgets: by adding an HTML element to the DOM (the page), then by reading properties stored in the Rich Display file, and by calling property setters for each property, applying the stored value to the widget.
Knowing how Profound UI works with widgets, we look at how PrimeUI widgets are setup in order to bridge the two. PrimeUI widgets have options, events, and methods, as you can read about in the PrimeUI documentation—for example, Rating. We must review a widget’s documentation and decide which PrimeUI options, events, and methods we want to make available in Profound UI. Whichever of those we decide to use will become widget properties in Profound UI, and we will write property setters for them.
Decide Which Properties to Support
As our example we use the rating widget--
--a simple input widget that allows a user to specify a non-negative integer value that represents, for example, how much they enjoyed talking to your support staff (hopefully 5 out of 5 stars).
Not every aspect of the PrimeUI widget needs to be adopted; you can implement only what you need. Implementing new properties as needed later is not problematic if the widget uses default values for those.
If we look at the page for a PrimeUI Rating widget there are two configuration options, stars and cancel:
These two seem useful; we want a developer to be able to drag and drop the widget onto the canvas and choose the number of stars and whether there is a cancel button with a few clicks. So, we will keep those in mind.
There are also two events, “rate” and “oncancel”:
Finally, there are methods:
These methods change or return the state of a Prime UI rating widget. Some will not be used; some can be used as Profound UI properties; our wrapper code will need others:
- cancel: because we will already provide a way to clear the rating—by clicking on the cancel button—we will skip this
- getValue: when a page is submitted to the server, Profound UI will need to know chosen values, so our wrapper code will need this
- setValue: when a page is loaded from the server the rating widget should display a saved value, so our wrapper code needs this
- enable and disable: looking at other input widgets in Profound UI you can see a “disabled” property. So, we could support a “disabled” property in a rating widget by wrapping the enable and disable methods. (This demonstrates using a built-in Profound UI property rather than defining a new property.)
- option: these methods can be ignored, because our widget will only be setup when the screen is rendered, and none of its properties will be changed by APIs.