Client-Side Functionality

• Mar 05, 2024
• 4 minutes to read

The DevExpress ASP.NET MVC Extensions include an advanced client-side API that is implemented with JavaScript and allows you to combine server-side and client-side functionality.

Refer to the following section for more information about DevExpress MVC Extensions and their client counterpart objects: Included Components.

Attach Required Script Files

If you create an MVC application based on a DevExpress Project Template, the template automatically attaches the necessary JavaScript files to the application.

If you do not use a DevExpress project template, you need to manually attach the required client script files to your application. Refer to the following section for more information: Manual Integration into an Existing Project.

Access an Extension on the Client Side

The Name property specifies a name that you can use to access the control’s client object in code.

Razor

<script>
    function preserveTextBoxValue(){
        var tbValue = textBox1.GetText();
        // ...
    }
</script>
<!-- ... -->
@Html.DevExpress().TextBox( settings => {
    settings.Name = "textBox1";
    settings.Text = "some text";
}).GetHtml()

Special Characters in the Name

If the Name 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.

@Html.DevExpress().TextBox(settings => {  
    settings.Name = "SomeType.SomeProp";  
}).GetHtml()  

var txt = ASPxClientControl.GetControlCollection().GetByName("SomeType.SomeProp");  
txt.SetText("Some Text");  

Enable an Extension’s Client API

Set an extension’s EnableClientSideAPI property (accessed through {ExtensionName}Settings.EnableClientSideAPI or {ExtensionName}Settings.Properties.EnableClientSideAPI) to true to make the extension’s client-side API available for developers. If a DevExpress MVC Extension does not provide the EnableClientSideAPI property, the client API is always available for this extension on the client side.

An extension’s client-side API is automatically available if you handle any of its client-side events.

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.