Web Control APIs

The following sections present APIs that can be called on all web controls.

Web Control Members

Web control members are listed and described in the following table.

Member  Name

Type

Description

Default Value

Exists

Boolean

Indicates whether the control exists on the page.  This read-only property should be used with caution, as it invokes the binding process.

 

InnerText

String

Inner text of the web control.

 

InnerHtml

String

Inner HTML of the web control.

 

Class

String

Class attribute of the web control. (Several classes can be included.)

 

Name

String

Name attribute of the web control.

 

Id

String

Id attribute of the web control.

 

Web Control Methods

Web control methods are listed and described in the following table.

Method

Return Type

Description

Parameters

Find<T>

T : WebControl

Finds descendant elements of a specific web control. The method accepts a Type that is a child of WebControl. This is the return value of the method.

Keep the following principles in mind when working with this method:

Casting is done whether or not the actual result of the Find method is the correct control type.

As the method returns only a single item, verify that the selector is unique.

If no Type is passed, a generic WebControl will be returned.

String Selector: A jQuery selector  to find descendants.

int Index: Index of the control, based on the selector to return.

bool ImmediateOnly: Indicates whether the method returns any matching descendants, or only the immediate children.

FindAll<T>

WebControlsCollection<T : WebControl>

Similar to the Find method, but returns a collection of controls that can be iterated on.

String Selector: A jQuery selector  to find descendants.

bool ImmediateOnly: Indicates whether the method returns any matching descendants, or only the immediate children.

int Skip: How many controls (from the beginning) should be skipped to get the first item.

Append

reference to a web control representing the added element

Adds a web control as a child of an existing web control.

String: An HTML string representing the element to be added.

bool appendAsFirstChild: Indicates whether the element is added as the first descendant of the existing web control. If the value is false, the element is added as the last descendant of the existing control.

Append<T>

reference to a web control representing the type of added element

Similar to the Append method, but adds a specific web control (button, textbox, etc.).

String: An HTML string representing the element to be added.

bool appendAsFirstChild: Indicates whether the element is added as the first descendant of the existing web control. If the value is false, the element is added as the last descendant of the existing control.

click

 

Triggers a click on the web control.

 

Focus

 

Sets focus to the control.

 

Blur

 

Removes focus from the control.

 

KeyDown

 

Simulates a keydown event.

 

KeyUp

 

Simulates a keyup event.

 

KeyPress

 

Simulates a keypress event.

 

MouseUp

 

Triggers a mouse up on the web control.

 

Mouse
Down

 

Triggers a mouse down on the web control.

 

Get
Attribute

string

If this attribute exists on the control, the method will return any attribute value.

String attribute: The attribute for which to get a value.

Set
Attribute

 

Sets an attribute on the web control. Any attribute may be set.

String attribute: The attribute for which to set a value.

String value: The value of the attribute to set.

GetStyleProperty

string

Returns a specific CSS style property (e.g., backgroundColor). To view a list of valid properties, go to http://www.w3schools.com/cssref/.

If an invalid property is used, the method will throw an exception.

String property

SetStyleProperty

 

Sets a specific CSS style property on the web control. To view a list of valid properties, go to http://www.w3schools.com/cssref/.

String property: The style property to set.

String value: The value of the property.

WaitFor
Appear

boolean

Blocks the code for a given time and waits for the control to become available. If the control is available, the method will return true. Otherwise, it will return false.

TimeSpan Timeout: The time to wait for the control to appear.

Execute
Script

simple types

Executes a JavaScript function of the control.
The generated code will be:
<code for finding control>.<scriptToExecute>

Note: When using this method, write your script with care. If the script involves exiting the webpage (through refresh, navigation, etc.), the script executes but a TimeOut  exception is then thrown, as the script cannot be checked.

scriptToExecute: The JavaScript code to execute in the control context.

executeOnNative: By default, the control is a jQuery object and the script will be executed on it. (You can execute jQuery methods as well.)
Set this property to true if you need to execute script on the native HTML element.

ScrollToView

 

Scrolls the control into view on the web page.

 

Bind

 

Binds to any event on a web control. This method allows you to register events that are not exposed by other JIA APIs.

As the technique of binding to events varies according to browser, a flag is used to indicate the relevant technique.

eventName: Name of the event to bind.

handler: A callback function to be triggered when the event is fired.

eventDataCollectionJavaScript: JavaScript to be executed when the event is fired, to collect event-related data

dataProcess: A process function to handle the collected data. By default, the data is returned as a string.

useAttach: A flag indicating whether the bind should be done with attachEvent or addEventListener.

Unbind

 

Unbinds to any event on a web control. As the technique of unbinding to events varies according to browser, a flag is used to indicate the relevant technique.

eventName: Name of the event to unbind.

useAttach: A flag indicating whether the bind should be done with attachEvent or addEventListener.

Web Control Events

Web control events are listed and described in the following table.

Event Name

Arguments

Description

Clicked

 

Fires when the control is clicked.

OnAppear

 

Fires once when the control is added to the DOM. If the control is already on the DOM, the event will never fire.