Custom Control Methods

Control methods are most often used in the rules editor to execute a control's method. Note that control methods are not the same as Control Events: Events are something that you can define a rule for and are usually driven by user input (for example: when the control is Clicked or Changed) while methods are something that the control can do (for example: refresh the control's content or call some background task on the control).

To define the list of available methods for a control, you need to add entries to the control definition XML file. You can define multiple methods by adding <Method> nodes. See the screenshot below, where we have defined a single method called MyControlCustomMethod1.

As you can see in the sample above, you may define whether the method returns a value with the ResultType value. (If the method does not return a value, set ResultType to None.)

You may also define multiple input parameters for the method. In the sample, we have defined a single parameter called Parameter1. The parameter is not required (set by the IsRequired node) and supports an input data type of Text, as specified in the DataType attribute.

When you are configuring the control method in the Rule editor, the method parameters are exposed on the Input Mappings screen while the method ResultType is exposed on the Output Mappings screen. The screenshots below illustrate these relationships.

Method Parameters are exposed as input mappings

Method returns are exposed as output mappings

The underlying .js method that actually performs the Method

The runtime implementation of the control method is usually done in the control's JavaScript file. When you define methods for the control in the control type definition file, you should also define an <ExecuteMethod> node. This node points to a JavaScript function that will fire when the control method is called at runtime.

The control's .js file contains the JavaScript method. This is a single entry-point method that will probably need to interrogate the Method name and determine the input parameters before breaking into a specific implementation of the method.

Consider the screenshot below, illustrating an example of the execute method. This method accepts an input parameter called objInfo which contains the method name, input parameters and the control ID of the control that the Method was called against. When the execute method runs at runtime, we determine the name of the method that was called and investigate the input parameters that were passed into the method. In the sample below, we are just showing an alert textbox with this information for demonstration purposes. Of course, in a real-world scenario you would probably do something a little more complex.