Control Properties and Methods

The form control represents an object that holds the details for the control on the form (type, position, layout details, etc).

References to those objects can be obtained using the form.GetControl(name) method.

Control Methods

GetValue()

Return type : string

Gets the current value of the corresponding control.

Note :

Date controls return the date in ANSI format (yyyy-MM-dd and yyy-MM-dd HH:mm:ss)

Number controls return the value in US format

Lookup controls return the value in the ID;#TITLE format

MultiLookup controls return the value in the ID1;#TITLE1;#ID2;#TITLE2;#... format

Example :

Code

var value = form.GetControl("c_Status").GetValue();

if (value != "Open")

form.GetControl("c_Priority").SetValue("Normal");

SetValue(value)

Return type : None

Used to set the value to a specific control.

The value must be provided in the same format with that used by the control when it returns its value (using the GetValue method)

Example :

Code

var customer = form.GetControl("c_Customer");

form.GetControl("c_Title").SetValue("The Customer is " + customer);

GetValue_Name()

Return type : string

It is used for lookup controls and returns the TITLE part or its ID;#TITLE formatted value

Example :

Code

var a = form.GetControl("c_Category").GetValue();

// returns "1;#CategoryA"

var b = form.GetControl("c_Category").GetValue_Name();

// returns "CategoryA"

GetValue_Value()

Return type : string

It is used for lookup controls and returns the ID part or its ID;#TITLE formatted value

Example :

Code

var a = form.GetControl("c_Category").GetValue();

// returns "1;#CategoryA"

var b = form.GetControl("c_Category").GetValue_Value();

// returns "1"

GetValues(separator)

Return type : string

Used for multi-value controls and returns the ID part of their values separated by the specified separator.

Example :

Code

var a = form.GetControl("c_Multi").GetValue();

// returns "1;#Open;#2;#Closed"

var b = form.GetControl("c_Multi").GetValues("-");

// returns "1-2"

GetNames(separator)

Return type : string

Used for multi-value controls and returns the TITLE part of their values separated by the specified separator.

Example :

Code

var a = form.GetControl("c_Multi").GetValue();

// returns "1;#Open;#2;#Closed"

var b = form.GetControl("c_Multi").GetNames("-");

// returns "Open-Closed"

ContainsValue(value)

Return type : bool

Used for multi-value controls and returns true if the value specified is one of the selected values of the control.

Example :

Code

var control = form.GetControl("c_Multi");

var value = control.GetValue();

// returns "1;#Open;#2;#Closed"

var b = control.ContainsValue("2")

// returns true

var c = control.ContainsValue("3")

// returns false

ContainsName(value)

Return type : bool

Used for multi-value controls and returns true if the name specified is one of the selected values of the control.

Example :

Code

var control = form.GetControl("c_Multi");

var value = control.GetValue();

// returns "1;#Open;#2;#Closed"

var b = control.ContainsName("Open")

// returns true

var c = control.ContainsValue("Pending")

// returns false

SetEnable(enableFlag)

Return type : None

Used to enable or disable a control.

Example :

Code

var c = form.GetControl("c_Status");

if (c.GetValue() == "Open") form.GetControl("c_Status").SetEnable(true);

else form.GetControl("c_Status").SetEnable(false);

SetVisible(visibleFlag)

Return type : None

Used to show or hide a control on the form

Example :

Code

form.GetControl("c_Status").SetVisible(false);

ColumnTitle()

Return type : string

Returns the title of the underlying list column.

Example :

Code

var title = form.GetControl("c_Title").ColumnTitle();

ColumnDescription()

Return type : string

Returns the description of the underlying list column

Example :

Code

var desc = form.GetControl("c_Title").ColumnDescription();

GetLookupItems()

Return type: array of objects

Works only with Combobox, RadioButtons and Checkboxes controls.

Returns an array of objects, which contain the items currently residing in the selected control.

Example:

Code

var items = form.GetControl("c_Control1").GetLookupItems();

alert(pf.ObjectProperties(items));

SetObjectDataSource

Return type: None

Definition:

SetObjectDataSource(objectArray, "DisplayFieldName", "ValueFieldName")

Can be used to set static values to lookup-type controls.

Works with Combobox, RadioButtons, Checkboxes, LookupPicker, MultiLookupPicker controls.

Example:

Code

var items = [];

items.push(new cbItem("item 1","1"));

items.push(new cbItem("item 2","2"));

items.push(new cbItem("item 3","3"));

form.GetControl("c_MultiLookup").SetObjectDataSource(items, "text", "value");

function cbItem(text,value)

{

this.text=text;

this.value=value;

}

Remove

Return type: None

Definition:

Remove()

Can be used to set remove a control using script. You can use the following script in the form's Load Completed script:

Code

form.GetControl("c_Control1").Remove();

Move

Return type: None

Definition:

Move(sectionKey, row, col)

Can be used to set move a control using script to a different location(section, row and column). You can use the following script in the form's Load Completed script:

Code

form.GetControl("c_Control1").Move("t_SectionKey",0,0);

Control Events

Control specific events you can tap into and listen, by registering handler functions.

LookupLoaded

Works only with Combobox, AutoCompleteTextbox, DropDownList, RadioButtons, Checkboxes controls.

This event will fire when a lookup-type control, such as the ones mentioned above, finishes loading its respective values.

Example:

We have a Combobox control, which contains continents. Our goal is to have Europe become the pre-selected value, as soon as the control gets populated with all continent values.

Code

if (form.Loaded == false) {

var continentsControl = form.GetControl("c_ContinentsCombobox");

continentsControl.LookupLoaded.AddHandler(function (e) {

form.GetControl("c_ContinentsCombobox").SetValue("Europe");

});

}

LookupLoading

Works only with Combobox, AutoCompleteTextbox, DropDownList, RadioButtons, Checkboxes controls.

This event will fire when a lookup-type control, such as the ones mentioned above, begins loading its respective values. You can use this event in the form's Load Completed script:

Code

var rating = form.GetControl("c_RatingsControl");

rating.LookupLoading.AddHandler(function (e) {

alert("My Lookup control is Loading...");

});

DocumentUploading

Works only with a DocumentGrid control.

This event will fire as soon as you press the Upload button on the DocumentGrid control, just before the actual documents are uploaded.

Example:

Show a confirmation dialogue to the user, asking whether to upload the documents or not. If the user presses yes, the documents will be uploaded, otherwise they will not.

Code

var grid = form.GetControl("c_aDocumentGrid").InputControl;

grid.DocumentUploading.AddHandler(function (e2) {

pf.UploadValues(e2);

});

pf.UploadValues = function(e) {

var conf = confirm("Are you sure you want to upload this file?");

// documents to be loaded

alert(grid.CTRL_ADD_FILES.value);

if(conf == true){

// continues uploading files

e.Cancel = false;

e.Callback(e);

}

else

{

// cancels uploading

e.Cancel = true;

}

DocumentUploaded

Works only with a DocumentGrid control.

This event will fire, after a document gets uploaded, using the DocumentGrid control.

Example:

Code

var grid = form.GetControl("c_aDocumentGrid").InputControl;

grid.DocumentUploaded.AddHandler(function (e3) {

alert("Document Uploaded!");

});

ValueChanging

This event will fire, whenever a control's value is changed .

Notable properties:

e.OldValue, contains the value before the change happened

e.NewValue, contains the new value.

Example:

Code

form.GetControl("c_Client").ValueChanging.AddHandler(function (e) {

alert("new: " + e.NewValue + ", old: " + e.OldValue);

});