Client-Side API

Aug 09, 2019
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

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):

Razor

razor

<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.5.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.Diagram },
        new Script { ExtensionSuite = ExtensionSuite.Gantt },
        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):

csharp

...
<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):

csharp

...
<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):

csharp

<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):

csharp

<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-Side API

Tables below list DevExpress MVC Extensions and their client-side objects:

Grid Extensions

Extension	Client Object
GridView	MVCxClientGridView
PivotGrid	MVCxClientPivotGrid
TreeList	MVCxClientTreeList

Extension	Client Object
Menu	ASPxClientMenu
NavBar	MVCxClientNavBar
PageControl	MVCxClientPageControl
PopupControl	ASPxClientPopupControl
Splitter	ASPxClientSplitter
TabControl	ASPxClientTabControl
TreeView	MVCxClientTreeView

Data Editors Extensions

Extension	Client Object
BinaryImage	ASPxClientBinaryImage
Button	ASPxClientButton
ButtonEdit	ASPxClientButtonEdit
Calendar	MVCxClientCalendar
CheckBox	ASPxClientCheckBox
CheckBoxList	ASPxClientCheckBoxList
ColorEdit	ASPxClientColorEdit
ComboBox	MVCxClientComboBox
DateEdit	ASPxClientDateEdit
DropDownEdit	ASPxClientDropDownEdit
HyperLink	ASPxClientHyperLink
Image	ASPxClientImage
Label	ASPxClientLabel
ListBox	MVCxClientListBox
Memo	ASPxClientMemo
ProgressBar	ASPxClientProgressBar
RadioButton	ASPxClientRadioButton
RadioButtonList	ASPxClientRadioButtonList
SpinEdit	ASPxClientSpinEdit
TextBox	ASPxClientTextBox
TimeEdit	ASPxClientTimeEdit
TokenBox	MVCxClientTokenBox
TrackBar	ASPxClientTrackBar

HTML Editor Extension

Extension	Client Object
HtmlEditor	MVCxClientHtmlEditor

Utilities Extensions

Extension	Client Object
CallbackPanel	MVCxClientCallbackPanel
RoundPanel	ASPxClientRoundPanel
UploadControl	MVCxClientUploadControl

Chart Extension

Extension	Client Object
Chart	MVCxClientChart

Scheduler Extension

Extension	Client Object
SchedulerControl	MVCxClientScheduler

Client-Side API

Client-Side API

Attach Scripts

Extension’s Available Client API

Access an Extension on the Client Side

Client-Side Events

Client-Side API

Grid Extensions

Navigation Extensions

Data Editors Extensions

HTML Editor Extension

Utilities Extensions

Chart Extension

Scheduler Extension