Client-Side Functionality
- 4 minutes to read
The DevExpress ASP.NET controls include an advanced client-side API that is implemented with JavaScript and allows you to combine server-side and client-side functionality.
A server object’s client-side equivalent includes the ASPxClient
prefix in its name (for instance, ASPxClientGridView for ASPxGridView).
#Access a Control on the Client Side
The ClientInstanceName
property specifies a name that you can use to access the control’s client object in code.
<dx:ASPxDockManager runat="server" ID="dockManager" ClientInstanceName="manager" />
var panel = manager.GetPanelByUID('MyPanel');
panel.Dock(manager.GetZoneByUID('MyZone'),0);
#Special Characters in Client Instance Name
If the ClientInstanceName
property contains special characters, for instance, the dot (.
), you cannot access a client object by this name. Call the GetByName(name) method to retrieve the client-side object instead.
<dx:ASPxTextBox ... ClientInstanceName="SomeType.SomeProp" />
var txt = ASPxClientControl.GetControlCollection().GetByName("SomeType.SomeProp");
txt.SetText("Some Text");
#Enable a Control’s Client API
Set a control’s EnableClientSideAPI
property to true
to make the control’s client-side API available for developers. If a control does not have the EnableClientSideAPI
property, the client API is always available for this control on the client side.
A control’s client-side API is automatically available if you handle any of its client-side events or specify its ClientInstanceName
property.
#The Difference Between the Enabled / Visible and ClientEnabled / ClientVisible Properties
When a server Enabled
property is set to false
, client scripts are not rendered for the control. An attempt to access the control causes the following exception: The 'ReferenceError: 'X' is not defined' error message appears when the Control.Enabled property is set to false.
Instead, set the ClientEnabled
property to false
to specify the initial control state on the server. In this case, the control is disabled, but its client scripts are rendered. You can call the SetEnabled
method to dynamically change the control’s availability on the client side.
Note that values of disabled inputs are not submitted.
The same logic is applied to the Visible
and ClientVisible
properties.
When a server Visible
property is set to false
, a control is not rendered on a page. An attempt to access the control causes the following exception: The 'Microsoft JScript runtime error: 'X' is undefined' error message appears when the Control.Visible property is set to false.
Instead, set the ClientVisible
property to false
to specify the initial control state on the server. In this case, the control is not visible, but it is rendered on a page. You can call the SetVisible
method to dynamically change the control visibility on the client side.
Note that if a container control is not rendered, nested controls are not rendered either. The individual nested control returns false
for the Visible
property even if you have explicitly set it to true
.
#Reasons Why the Client API Can be Disabled
The Client API Can be Disabled in the Following Cases:
- If a web control’s server-side Visible property is set to
false
, it is impossible to interact with the control on the client side because the control is not rendered on the web page. Use theClientVisible
property to define the control’s initial visibility state. Then use the clientSetVisible
method to change the control’s visibility dynamically. - If a web control is disabled on the server (that is, the server-side Enabled property is set to
false
), it is impossible to manage its availability state on the client side. Use theClientEnabled
property to define the control’s initial availability state. Then, use the clientSetEnabled
method to change the control’s availability dynamically. A client-side API member does not work if its corresponding element is not initialized on the server side.
For instance, if an item image is not specified on the server side, the image element is not rendered on the client side. In this particular instance, the item’s
SetItemImage
method is not in effect.- Some control styles (for instance, a disabled style) are sent to the client side with the API service’s JavaScript code. If a client-side API is disabled, styles are not applied.