Creating a User Control component

A User Control component is a container for a Web User Control that might or might not include a .NET assembly. User Controls are used to add custom user interface elements to forms.

This topic presents the recommended basic process to create a user control. The specifics will depend on the user control you are creating. There are other ways to create user controls that are not covered by this topic.
Note: This generalized process is for a user control that is functional in both the Windows (smart) client and the web client.
  1. Create an HTML web page to host and display the user control.
    You can use whatever HTML-related assets you want in the file. These assets can include JavaScript files, image files, CSS files, DLL assemblies, and so on.
    For ease in importing them into Service Management later, it is a good idea to organize all the assets you want to import into a single folder/directory, if you can.
    Note: It is possible to reference scripts, style sheets, images, or just about any asset stored on another server. For example, to include the jQuery JavaScript library without importing it into Service Management, you could use a URL reference such as this in your user control web page: https://code.jquery.com/jquery-3.1.1.min.js.
  2. In Service Management, import your HTML page and associated files/resources, using the Edit Web User Control Assets dialog box.
    See Importing Web User Control Assets.
  3. Open or create the form where you want to create your user control component, and go into Design Mode.
  4. In the Toolbox, select User Control and draw the component on the form where you want it to appear.
  5. In the Web section of the Edit User Control References dialog box, from the Control URL drop-down list, select the HTML file that hosts your user control.
  6. Verify that the Use Web Control and Web User Control Asset options are both selected.
  7. Click OK.
  8. Do whatever else that might be required to integrate the user control with the data from the form.
    This might include data binding, form scripting, or whatever else is necessary to push and pull data between the form and the user control.

    For calls from the form to the user control, you can use the PostUserControlMessage scripting API and/or a form event handler with the response type Invoke User Control.

    For calls from the user control back to the form, you can use JavaScript API methods such as WSForm.getCompValue, WSForm.setCompValue, WSForm.getVarValue, WSForm.setVarValue, WSForm.invoke, WSForm.generate, WSForm.subscribe, WSForm.UserControl.registerListener, MG.onReady, and MG.generateServerEvent.

  9. Save the form, close it, and reopen it.
  10. Test the user control for correct operation.