JavaScript

{dialog.object}getControl Method

Syntax

{dialog.object}.getControl(variableName);

Arguments

variableNamestring: The name of the control in the UX Component

Returns

resultobjectboolean: Returns the JavaScript object for the requested control. If there is no JavaScript object for the requested control, getControl() returns false.

Description

Get a pointer to a control to call methods of an object, or set properties of an object.

Discussion

Get a pointer to a control, such as a slider, date picker, List, ControlBars map, etc. so that you can call methods of the object, or set properties of the object.

Only controls that are implemented as JavaScript objects are returned.

For example, a slider control is implemented as a JavaScript object with methods that can be used manipulate the control at runtime, such as setting the slider's minimum and maximum values.

A standard HTML Textbox control on the other hand is not implemented as a JavaScript object -- it is just a standard HTML <input> control. If you call the .getControl() method on a Textbox control, the method will return false. However, if you set certain properties on the Textbox control (such as watermark, client-side formatting, mask, etc) then a special 'helper' object is created for the Textbox control, and the getControl() method will return a pointer to this helper Textbox object.

To get a pointer to a Panel or Window, you must use the {dialog.object}.getPanelObject() or {dialog.object}.getWindow() respectively. Special functions also exist for getting pointers to child and parent components. See the See Also section below.

The {dialog.object}.getControl() method returns a pointer to the JavaScript object for the control. Once you have a pointer to the object, you can call methods on the object.

For example:

//Get BUTTON_1's JavaScript object
var bObj = {dialog.object}.getControl('BUTTON_1');

if (bObj) {
    //Disable the button:
    bObj.setDisabled(true);

    //Enable the button:
    bObj.setDisabled(false);
}

If the JavaScript object doesn't exist for the requested control, getControl() will return false. You should always check the returned value of the getControl() method before using the object. This can be done by wrapping your code in an if block as shown in the example.

Calling setDisabled on a Button in a Repeating Section

If you have a button in a Repeating Section, the .getControl() method will point to all instances of the button (i.e. the button in row1, row2, etc.). If you call the button's .setDisabled() method, you will change the disabled state on the button in every row.

//disables all 'BUTTON_2' buttons in the Repeating Section:
var bObj = {dialog.object}.getControl('BUTTON_2');

if (bObj) {
    bObj.setDisabled(true);
}

If you want to call the .setDisabled() method for a specific button instance (e.g. the button in row 3), you can pass a pointer to the HTML element of the button instance as the second parameter of the button's .setDisabled() method. For example:

//Get the instance number for row 3:
var row = {dialog.object}._repeatingSectionLogicalToPhysicalRow('SECTION_1',3);

//Get a pointer the button element in row 3:
var eles = ${dialog.object}.getPointer('BUTTON_2_A5INSTANCE'+row);

var bObj = {dialog.object}.getControl('BUTTON_2');

if (eles && bObj) {
    //pass in eles as an optional argument to the .setDisabled() method
    bObj.setDisabled(true,eles);
}