Client-Side API

Aug 24, 2021
5 minutes to read

DevExpress ASP.NET MVC extensions provide an advanced client-side API that enables you to combine server-side and client-side functionality.

The DevExpress MVC extensions provide client-side APIs that are implemented using JavaScript. Extension-relative assemblies (DLLs) include JavaScript files that implement an extension’s client-side APIs as embedded resources.

Attach Scripts

You should attach script files that implement extensions’ client-side APIs to an application.

The DevExpress ASP.NET Project Wizard automatically attaches the JavaScript files to the application’s Site.Master page if you use a DevExpress Project Template to create an MVC application. If you do not use a DevExpress project template, you need to manually attach necessary DevExpress client script files using the ExtensionsFactory.RenderScripts extension method within a view page’s HEAD or BODY tag.

View (or Master Page) Code (ASPX):

ASPX

<body>
    ...
    <% Html.DevExpress().RenderScripts(Page,
           new Script { ExtensionSuite = ExtensionSuite.GridView },
           new Script { ExtensionSuite = ExtensionSuite.PivotGrid },
           new Script { ExtensionSuite = ExtensionSuite.HtmlEditor },
           new Script { ExtensionSuite = ExtensionSuite.Editors },
           new Script { ExtensionSuite = ExtensionSuite.NavigationAndLayout },
           new Script { ExtensionSuite = ExtensionSuite.Chart },
           new Script { ExtensionSuite = ExtensionSuite.Report },
           new Script { ExtensionSuite = ExtensionSuite.Scheduler },
           new Script { ExtensionSuite = ExtensionSuite.TreeList }
     ); %>
    ...
</body>

View (or layout View) Code (Razor):

ASPX

<head>
    ...
    <!-- 
    Attach the jQuery script if the "resources" section of an application's Web.config file contains a reference to the "ThirdParty" libraries.
    -->  
    <script src="@Url.Content("~/Scripts/jquery-3.3.1.min.js")" type="text/javascript"></script>
    <!-- The DevExpress ASP.NET MVC Extensions' scripts -->  
    @Html.DevExpress().GetScripts( 
        new Script { ExtensionSuite = ExtensionSuite.NavigationAndLayout }, 
        new Script { ExtensionSuite = ExtensionSuite.HtmlEditor }, 
        new Script { ExtensionSuite = ExtensionSuite.GridView }, 
        new Script { ExtensionSuite = ExtensionSuite.PivotGrid },
        new Script { ExtensionSuite = ExtensionSuite.Editors }, 
        new Script { ExtensionSuite = ExtensionSuite.Chart },
        new Script { ExtensionSuite = ExtensionSuite.Report },
        new Script { ExtensionSuite = ExtensionSuite.Scheduler },
        new Script { ExtensionSuite = ExtensionSuite.TreeList },
        new Script { ExtensionSuite = ExtensionSuite.Spreadsheet },
        new Script { ExtensionSuite = ExtensionSuite.RichEdit },
        new Script { ExtensionSuite = ExtensionSuite.SpellChecker }
    )
    ...
</head>

Extension’s Available Client API

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

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

Access an Extension on the Client Side

Use the SettingsBase.Name property to specify an extension’s name to access its client object.

View code (ASPX):

...
<script type="text/javascript">
    var tbValue;

    function preserveTextBoxValue(){
        tbValue = textBox1.GetText();
    }
</script>

...

        <% 
            Html.DevExpress().TextBox(
                settings => {
                    settings.Name = "textBox1";
                    settings.Text = "some text";
                }
            )
            .Render();
        %>

View code (Razor):

...
<script type="text/javascript">
    var tbValue;

    function preserveTextBoxValue(){
        tbValue = textBox1.GetText();
    }
</script>

...

        @Html.DevExpress().TextBox(
            settings => 
            {
                settings.Name = "textBox1";
                settings.Text = "some text";
            }
        ).GetHtml()

Note

Refer to the KA18687 KB article for information on how to access an extension’s client object if the SettingsBase.Name property contains special characters (for example, the “.” dot).

Client-Side Events

Each DevExpress ASP.NET MVC Extension provides a set of client-side events. Use the ClientSideEvents property at the level of the extension’s settings (Settings.ClientSideEvents) or properties (Properties.ClientSideEvents) to access the available client-side events.

Note

Register JavaScript functions at the top of the page. In this case, the browser executes these scripts before it renders the DevExpress ASP.NET MVC extensions.

The following code demonstrates how to handle an extension’s client-side events:

View code (ASPX):

    <script type="text/javascript">
        function MenuItemClick(s, e) {
            textBox1.SetText(e.item.GetText());
        } 
    </script>

...
        <% 
            Html.DevExpress().Menu(
                settings =>
                {
                    settings.Name = "menu1";
                    settings.EnableClientSideAPI = true;

                    settings.Items.Add("Visa");
                    settings.Items.Add("MasterCard");
                    settings.Items.Add("Union");
                    settings.Items.Add("American Express");
                    settings.Items.Add("Maestro");

                    settings.ClientSideEvents.ItemClick = "MenuItemClick";
                })
                .Render();
        %>
...
        <% 
            Html.DevExpress().TextBox(
                settings => {
                    settings.Name = "textBox1";
                    settings.Properties.EnableClientSideAPI = true;
                }
            )
            .Bind(Model.Email)
            .Render();
        %>
...
        <% 
            Html.DevExpress().Button(
                settings => {
                    settings.Name = "btnClear";

                    settings.Text = "Clear Text";
                    settings.ClientSideEvents.Click = "function(s, e){ textBox1.SetText(''); }";
                }
            )
            .Render();
        %>

View code (Razor):

    <script type="text/javascript">
        function MenuItemClick(s, e) {
            textBox1.SetText(e.item.GetText());
        } 
    </script>

...
        @Html.DevExpress().Menu(
            settings =>
            {
                settings.Name = "menu1";
                settings.EnableClientSideAPI = true;

                settings.Items.Add("Visa");
                settings.Items.Add("MasterCard");
                settings.Items.Add("Union");
                settings.Items.Add("American Express");
                settings.Items.Add("Maestro");

                settings.ClientSideEvents.ItemClick = "MenuItemClick";
            }).GetHtml()

...
        @Html.DevExpress().TextBox(
            settings => {
                settings.Name = "textBox1";
                settings.Properties.EnableClientSideAPI = true;
            }).Bind(Model.Email)
            .GetHtml()
...
        @Html.DevExpress().Button(
            settings => {
                settings.Name = "btnClear";

                settings.Text = "Clear Text";
                settings.ClientSideEvents.Click = "function(s, e){ textBox1.SetText(''); }";
            }).GetHtml()

Client API Implementation

The table below lists the DevExpress MVC Extensions together with their client counterpart objects and the corresponding namespaces that implement their client-side functionalities.

Extension Name	Client Object	Client Namespace
GridView	MVCxClientGridView	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
PivotGrid	MVCxClientPivotGrid	DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxPivotGrid.Scripts
TreeList	MVCxClientTreeList	DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxTreeList.Scripts
HtmlEditor	MVCxClientHtmlEditor	DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxHtmlEditor.Scripts
Navigation Extensions:
Menu	ASPxClientMenu	DevExpress.Web.Scripts
NavBar	MVCxClientNavBar	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
PageControl	MVCxClientPageControl	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
PopupControl	ASPxClientPopupControl	DevExpress.Web.Scripts
Splitter	ASPxClientSplitter	DevExpress.Web.Scripts
TabControl	ASPxClientTabControl	DevExpress.Web.Scripts
TreeView	MVCxClientTreeView	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
Data Editors Extensions:
BinaryImage	ASPxClientBinaryImage	DevExpress.Web.Scripts
Button	ASPxClientButton	DevExpress.Web.Scripts
ButtonEdit	ASPxClientButtonEdit	DevExpress.Web.Scripts
Calendar	MVCxClientCalendar	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
CheckBox	ASPxClientCheckBox	DevExpress.Web.Scripts
CheckBoxList	ASPxClientCheckBoxList	DevExpress.Web.Scripts
ColorEdit	ASPxClientColorEdit	DevExpress.Web.Scripts
ComboBox	MVCxClientComboBox	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
DateEdit	ASPxClientDateEdit	DevExpress.Web.Scripts
DropDownEdit	ASPxClientDropDownEdit	DevExpress.Web.Scripts
HyperLink	ASPxClientHyperLink	DevExpress.Web.Scripts
Image	ASPxClientImage	DevExpress.Web.Scripts
Label	ASPxClientLabel	DevExpress.Web.Scripts
ListBox	MVCxClientListBox	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
Memo	ASPxClientMemo	DevExpress.Web.Scripts
ProgressBar	ASPxClientProgressBar	DevExpress.Web.Scripts
RadioButton	ASPxClientRadioButton	DevExpress.Web.Scripts
RadioButtonList	ASPxClientRadioButtonList	:DevExpress.Web.Scripts
SpinEdit	ASPxClientSpinEdit	DevExpress.Web.Scripts
TextBox	ASPxClientTextBox	DevExpress.Web.Scripts
TimeEdit	ASPxClientTimeEdit	DevExpress.Web.Scripts
TokenBox	MVCxClientTokenBox	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
TrackBar	ASPxClientTrackBar	DevExpress.Web.Scripts
Utilities Extensions:
CallbackPanel	MVCxClientCallbackPanel	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
RoundPanel	ASPxClientRoundPanel	DevExpress.Web.Scripts
UploadControl	MVCxClientUploadControl	DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts
Chart Extension:
Chart	MVCxClientChart	DevExpress.Web.MVC.Scripts, DevExpress.XtraCharts.Web.Scripts
Report Extension:
DocumentViewer	MVCxClientDocumentViewer	DevExpress.Web.MVC.Scripts, DevExpress.XtraReports.Web.Scripts
Scheduler Extension:
SchedulerControl	MVCxClientScheduler	DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxScheduler.Scripts

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Attach Scripts

Extension’s Available Client API

Access an Extension on the Client Side

Client-Side Events

Client API Implementation