Client-Side Functionality

• Sep 15, 2023
• 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.

Run Demo: Dock and Popups - Client-Side Functionality

ASPX

<dx:ASPxDockManager runat="server" ID="dockManager" ClientInstanceName="manager" />

JS

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 the ClientVisible property to define the control’s initial visibility state. Then use the client SetVisible 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 the ClientEnabled property to define the control’s initial availability state. Then, use the client SetEnabled 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.