Creating a new instance of a user component

The source JavaScript file provides the code required to define how the framework creates a new instance of the user component.

The framework calls the MG.app.UserComponent.define framework function, passes it the name of the user component and the factory function used to create a new instance of the JavaScript object that implements the user component.

MG.app.UserComponent.define({
   name: "component",
   factory: function(init, context) {
      return new UserComponentImplementation(init, context);
   }
});

component is the name of the user component, for example, MGSlider. This value must match the name in the .component file.

The factory function is called with these two parameters:

init: An optional initialization string as specified for the component in the designer property grid.
context: An object that provides functions for calling back into the framework from the user component.
This object provides these functions:
- firePrimaryEvent(): Fires the primary event specified in the component properties.
- setValue(newValue): Called by the user component when the value is changed.
- getList(callback): Gets the list for the user component based on the list source defined in the component’s properties. The callback function is called with the list contents as an array of strings.
- getCaption(): Gets the caption text associated with the user component as specified in the component properties.
- getJustification(): Gets the effective text justification setting inherited or specified in the component properties. Valid values are L, R, and C for left, right, and center.
- getMaxLength(): Gets the effective maximum length inherited or specified in the component properties.
- getTooltip(): Gets the tooltip string associated with the user component.
- getBoolTrueValue(): Gets the string value that corresponds to True for binary components, such as check boxes.
- getBoolFalseValue(): Gets the string value that corresponds to False for binary components, such as check boxes.
- getImageSrc(): Gets the URL of the image file associated with the user component.
- getThemeClass(): Gets the name of the theme class associated with the user component in the component properties.
- getThemeStyle(): Gets the effective theme attribute overrides for the user component. This function is used by the user component to modify the framework theme.
  The object returned by this function have zero or more of these fields:
  - Background: <color>
  - Foreground: <solid-color>
  - DisabledForeground: <solid-color>
  - DisabledBackground: <color>
  - RequiredForeground: <solid-color>
  - RequiredBackground: <color>
  - HoverForeground: <solid-color>
  - HoverBackground: <color>
  - TBDForeground: <solid-color>
  - TBDBackground: <color>
  - FontFamily: <font-list>
  - FontSize: <font-size>
  - FontBold: true|false
  - FontItalic: true|false
  where:
  - <solid-color> is an HTML color specified as rgb(n,n,n) or rgba(n,n,n,n).
  - <color> is either a <solid-color>, or if a gradient is specified as an HTML gradient: linear-gradient(<solid-color>, <solid-color>).
  - DisabledForeground and DisabledBackground are read-only fields.
- hourglass(): Shows an hourglass and locks the user interface (UI).
- endHourglass(): Hides the hourglass and unlocks the UI.
Note: hourglass() and endHourglass() can be nested. Ensure that for each hourglass() call, there must be one balancing endHourglass() call.

The factory function returns a JavaScript object that implements the user component. The framework expects the user component to implement these functions:

Note: If a function is not implemented by the user component object, the framework skips calling the function.


Function	Definition
`getHtml()`	This function is called by the framework to get the HTML fragment used to render the user component. To render a button, this function returns a value similar to this example: `<input type='button' value='Push Me' />` Note: This function is optional. Certain types of components may not have a persistent UI element and may not implement this function.
`getValue()`	This function is called by the framework to get the current value of the user component.
`onValueChanged(newValue)`	This function is called by the framework when the value for this component has changed, whether it is bound to a property or a variable whose value has changed, or the value was changed by a script.
`onReadOnlyChanged(readOnly)`	This function is called by the framework when the component’s read-only state changes. If a user component accepts a user input, it should implement this function and disable input when the parameter is True.
`onVisibleChanged(visible)`	This function is called by the framework when the component becomes visible or hidden. The user component container is hidden automatically by the framework, so it is not generally necessary for the user component to do anything when this is called. But, it may be useful in some scenarios.
`onCaptionChanged(caption)`	This function is called by the framework when the component’s caption changes. The developer should add an implementation for this function if they want to handle dynamic caption changes.
`onFormReady()`	This function is called by the framework to signal that form initialization is complete. Before this function is called, the user component should not call any of these context functions: `setValue()` `getList()` `firePrimaryEvent()`
`endEdit()`	This function is called by the framework to indicate that it is about to synchronize any changes in progress with the server. Most controls do not need to implement this function, but it may be useful in some scenarios.
`destroy()`	This function is called by the framework when the user component is removed from a form, or when a form is closed.
`onLoaded(rootEl)`	This function is called by the framework after the DOM elements for this component have been created and added to the document. The parameter is the root element corresponding to the first element specified in the string returned by the `getHtml()` function. Note: If the `getHtml()` function is not implemented or returns an empty string, the rootEl parameter will be undefined.