Creating a UserControl component

A UserControl 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 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 web client and the Windows client.
  1. Create an HTML web page to host and display the user control.
    See Creating HTML web pages.

    You can use any HTML-related assets. These assets can include JavaScript files, image files, CSS files, DLL assemblies, and so on.

    Optionally, organize all the assets to be imported into a single folder or directory.

    Note: You can reference scripts, style sheets, images, or any assets stored in another server. For example, to include the jQuery JavaScript library without importing it into Mongoose, you can use a URL reference such as this in your user control web page: https://code.jquery.com/jquery-3.1.1.min.js.
  2. Import your HTML page and associated files or resources.
    See Importing Web User Control Assets.
  3. Open or create the form where you want to create your user control component.
  4. Go into the designer (Web Designer in the web client, Design Mode in the Windows client) .
  5. In the Toolbox, select Framework Components > UserControl.
  6. Drag the component to the form and drop it where you want the component to appear.
  7. In the Edit User Control References, perform these steps:
    1. Select the Use Web Control check box.
    2. In the Control URL field, select the HTML file that hosts your user control.
    3. Select the Web User Control Asset option.
    4. Click OK.
  8. Perform the other steps required to integrate the user control with the data from the form.
    This might include data binding, form scripting, or other steps 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 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. Click Save.
  10. Close the form.
  11. Unload global objects.
  12. Reopen the form.
  13. Test the user control for correct operation.