Custom Widget Response Value

For Profound UI versions starting with Version 6 Fix Pack 12.0 custom widgets can be designed to be treated as native Profound UI widgets. See pui.BasicWidget and Bidirectional Custom Properties. For earlier versions of Profound UI, see below.

When you create a custom widget, you may want to pass information from the widget to the server-side program (RPG, Node.js, etc.). Profound UI automatically passes bound field data from standard, non-custom widgets to the server-side program when the screen submits. With custom widgets, however, data in bound fields are not automatically passed to the server-side program. The reason custom widget data are not passed is because Profound UI cannot know how each custom widget stores its data¹.

To pass bound data from a custom widget into the screen response², some extra work is required to route the data.

Bind either the widget's "value" or "html" property to a field³.
Write a custom "onsubmit" function to copy data from the custom widget into the screen response data.

The data is expected to flow in this fashion when a screen responds back to the server-side program:

Custom Widget DOM tree --> custom onsubmit function --> screen response --> Profound UI Handler --> server-side program.

When a custom widget's "value" or "html" properties are bound, Profound UI will add some extra information to the custom widget's DOM tree. In the widget's main DOM element, there is an object named, "pui", containing the properties, "fieldName" and "formatName".

Your custom "onsubmit" function looks at each custom widget for pui.fieldName and pui.formatName to determine the correct field and format name for the custom widget's data. The "onsubmit" function adds data to its argument, a screen response object. The "onsubmit" function must return true (or else the response is suppressed). The "onsubmit" function is the way you tell Profound UI how to access custom data from your widget. The current record format name and bound field names should be passed to the response.

Profound UI writes the screen response object into an HTTP request and sends the HTTP request.

The HTTP server passes the HTTP request data to the server-side framework--Profound UI RPG open access handler or Profound.js.

The server-side framework reads the record format name and field name, and it passes data to the appropriate format and field in your server-side program, which has been waiting for the screen response.

¹ If a custom widget is nothing more than an <input> tag, and the argument to pui.widgets.add includes the property-value, 'tag: "input",' then Profound UI can detect the bound "value" property and automatically send it with the page response.

₂ Available in Profound UI Versions 5, Fix Pack 8.0 and later.

3 Binding to other properties, such as "user defined data", does not put "fieldName" and "formatName" in the widget's DOM object. Only "value" and "html" are supported.

Example Hard-coded "onsubmit" function

window.myCustomWidgetOnSubmit = function(response){
  response["FMTNAME.FIELDNAME"] = "someValueTakenFromYourWidgets";
  return true;    //required to return true; otherwise the response would be suppressed.
}

(The argument is passed by reference, so changes to it are preserved in the when the function returns.)

Using that function, the record format's "onsubmit" property would just be:

myCustomWidgetOnSubmit;

The above example shows the format and field names hard-coded to illustrate how the response expects the data to be formatted. To avoid hard-coding, see the example below.

Example "field type" Setter with Corresponding "onsubmit" Function

If your onsubmit function is to automatically pull the record format name and bound field name from the custom widget, it must have a way of identifying your custom widget. One approach is to set an HTML attribute on the widget's DOM element; then search for that element in the onsubmit function using "querySelectorAll".

Profound UI places the custom widget's elements inside a parent DIV element. You could add a custom attribute that can be found using querySelectorAll().

Example "field type" property setter

"field type": function(parms) {
  var id = parms.dom.id;
  parms.dom.setAttribute("myboundwidget","true");
  parms.dom.innerHTML = '<label for="'+ id +'_txt">Custom Widget Label:</label>' + '<input id="'+id+'_txt" type="text" />';
  // Store the value into the parent DIV element's DOM.
  // Note: If the widget's "value" property was bound, then evalProperty uses the value set by the server-side program. If "value" was hard-coded in Designer, then evalProperty uses that hard-coded value. 
  parms.dom.value = parms.evalProperty("value");   //Note: you could store the value almost anywhere.
}

Example "onsubmit" function

Automatically Passing Custom Widget Input Data to the Server

Rather than coding onsubmit functions for each screen, it is possible to write code to handle all screens with custom widgets. For details please see the blog post, "Painlessly Passing Custom Widget Input Data to the Server".