Universal dialog runtime flow

This flow applies to a stand-alone universal dialog. It is very similar to panel mode, see Panel mode universal dialog for more information.

  1. An HTTP request is made, for example, https://host_name/webapp/wcs/tools/servlet/UniversalDialogView?XMLFile= common.UDSample, where common.UDSample is defined in the component's specific resources.xml file.
  2. The XML file specified in the HTTP request is parsed.
  3. Data beans defined in the XML are instantiated, and activated if they are Commerce smartDataBeans. The bean instances are added to the request attribute object, so that they can later be accessed by any JSP custom segments in the same request. See the corresponding tags in the universal dialog definition.
  4. The XML object, NLS resource bundle, locale and formName are also added to the request so that they can be shared by any custom JSP segments.
  5. Any JavaScript files included in the XML file are included in the output page. If required, you can implement any logic at page initialization as well as custom global validator functions here.
  6. Any defined global JSP custom segments are generated right after <BODY> and before any other HTML text. If required, you can implement any logic at page initialization as well as custom global validator functions here.
  7. Action buttons defined in the XML file load and display at the top of the page.
  8. All sections display, populating the HTML input form elements with the values from pre-populated beans. The exception is sections which have the enabled="false" tag, these elements do not display.
  9. Finally, a JavaScript function is generated to call any defined global level, section level and element level validators that are defined in the same XML file.
  10. At this point, an output HTML page displays with page title, page description and sections of input elements, with all pre-populated input fields populated.
  11. If defined, the optional custom init() function runs as part of the HTML page's onload event.
  12. The user completes the fields in the HTML form, and clicks the OK button to submit the form.
  13. All form data is saved into the TOP JavaScript object. This form data is saved to pre-populate the fields when this page re-displays in step 17.
  14. All form data converts into an XML string and is submitted to the controller command, which is defined in the XML as finishURL. This is to ensure the same parameter format is used across both stand-alone and panel mode, as well as other tools framework widget models.
  15. The controller command receives the request. At this point, the tools controller command layer ensures that all parameters inside the XML are already parsed and placed under the requestProperties as normal name-value-pairs.
  16. After execution, controller command may return to UniversalDialogView either successfully or with an ECApplicationError. In either case, it needs to return a message.
  17. The widget JSP page loads again after being forwarded from the controller command. Previously saved form data, in step 13, is restored in the HTML form.
  18. In the success case, it checks whether there is a custom finishHandler() function. If finishHandler() exists, a success message is passed to this function, otherwise, it displays the message and calls the top.goBack() function to go back.
  19. In an error case, it checks whether there is a custom errorHandler() function. If errorHandler() exists, it passes the error message and error code to this function, otherwise, it displays the error message.

Panel mode universal dialog

In panel mode, the universal dialog is one of the panels in a notebook. The panel runtime flow is similar to the stand-alone runtime flow described above with the following changes:

  • A notebook definition XML file is required, as with all notebooks. Each notebook panel is a section of a universal dialog.
  • The request URL has an additional parameter called section to indicate which section should be rendered in which panel.
  • All sections without an enabled="false" tag are loaded, but only the required section is visible. All sections are loaded so that all form data can be submitted to the controller command at the same time.
  • Rather than saving form data to TOP, it saves it to the parent.model object, which is the approach used by all Tools User Interface Center elements. This is transparent to page developers. In order to maintain compatibility between two modes, two convenient functions are created when saving and loading custom data, ie. getData(), putData(key, value). Page developers are strongly discouraged from using direct calls like parent.put(), parent.get() or top.put(), top.saveData().
  • Action buttons are handled by the notebook, so there is no need to define any buttons in the universal dialog's XML file.
  • A notebook's validateAllPanels() function, which is typically defined in the notebook's include Javascript file, should always return the value from validateForm() in the universal dialog panel page. The validateForm() will call all validators and display the error messages if there are any.
  • finishURL should be defined in the Notebook XML, not the universal dialog XML file.