General Concepts

Owned by David Russo
Last updated: Aug 16, 2023 by Jessica Tomkins
3 min read



General Concepts for Integrating 3rd-Party Components

The following general concepts can be used for integrating any 3rd party widget with Profound UI. 

  • The first step is to load any needed JavaScript and CSS files onto the page. There are several ways to load the required JavaScript and CSS files.

    • If the component has a single, relatively small JavaScript file, a very easy way is to drop it into the DOCUMENT_ROOT/profoundui/userdata/custom directory or any sub-directory beneath. Profound UI will automatically load in any JS files existing in the directory tree beginning there when you launch a Rich Display File application session. If you are also using Genie for 5250 emulation sessions, you’ll want to add a <script> tag to in your skin’s “start.html” file to load in the file from the same location. CSS files can be linked in using the same techniques. If the component requires multiple files, they should not just be dropped into /custom, though, as the order of files is not always going to be what is needed. In that case, you must either customize the DOCUMENT_ROOT/profoundui/userdata/html/start.html file, or make use of Profound UI's file loading API to load the JS files in the correct order: pui.loadJS(path or config)

    • If there are multiple files the widget depends on, or if some files should be conditionally loaded, then the files can be specified in the "dependencies" option to pui.widgets.add. When using dependencies, files are only loaded on-demand, when a widget first needs them and before Profound UI tries to render the widget.

  • When using Profound UI releases including and newer than Version 6 Fix Pack 12.0, wrap the 3rd-party component in a pui.BasicWidget class, which gets automatically treated like a Profound UI native widget.

  • For older versions of Profound UI:

    • The next step is to place a Profound UI widget on screen that is rendering using the HTML element the 3rd party component needs to render into. For example, if a <div> element is required, you can use a ‘label’ or ‘output field’ widget which is exactly that. Just remove the ‘value’ property, size/position where you want on screen, and give a unique element id using the widget’s ‘id’ property.

    • The code to render the 3rd party component to the editor can then be called from the record format’s “onload” event.

    • Additional steps may be required to get the 3rd party component to submit data to the server properly. This may not apply to the component you are working with. This point applies to components that work by manipulating input controls. Profound UI will only submit data to the server for input controls it deems to have been modified by the user. This becomes a problem when the input control is modified by coding in the component, rather than the user typing into or clicking on the control. For example, imagine a date picker component. The user selects a date from a calendar pop-up and the component then writes it into a textbox. Profound UI won’t see the text box as having been changed, as the user didn’t type into it. For components that work in this way, it’s necessary to use Profound UI’s pui.set() API to set the input control value. Using the date picker example, you could call this from the date picker’s ‘onselect’ event. 

    • Another way that 3rd party components could work is by providing the data to you through an API method that returns a JavaScript string. You can get any input like that into your program by adding a hidden textbox widget to the screen with a field bound to the ‘value’ property. Then use the pui.set() API to put the data into the textbox. You could do that from the record format’s ‘onsubmit’ event.