Client-Side API
- 6 minutes to read
The majority of DevExpress ASP.NET MVC extensions offer an advanced client-side API. This enables you to develop more efficient web applications by combining server-side and client-side processing.
The client-side API exposed by DevExpress extensions is implemented using JavaScript - an object oriented programming language which is interpreted by client browsers. JavaScript files that implement the client API are embedded as resource files into extension-relative assemblies (DLLs).
Attaching Scripts
To work properly, the DevExpress Extensions require the script files implementing their client API to be attached.
If you create your MVC web application using a DevExpress Project Template, the code that attaches the required JavaScript files is automatically added to the application’s Site.Master page. If you don’t use the 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. Typically, this can be done within the Site.Master page to attach scripts centrally in a single location.
View (or Master Page) Code (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):
<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>
Client API Availability for an Extension
If you write custom client code using the public client-side API provided by a DevExpress MVC extension, make sure that the EnableClientSideAPI property (available as an extension settings object’s EnableClientSideAPI or Properties.EnableClientSideAPI for data editors) is set to true. Enabling this property guarantees that the service JavaScript code that implements the extension’s client API will be sent to the client browser when a web application that uses the extension is run. This makes the extension’s client-side API available for developers.
Some DevExpress MVC Extensions provide the public client-side API, but do not expose the EnableClientSideAPI property. This means that client-side API is always available for these extensions on the client.
Note that an extension’s client API becomes available automatically if any of its client-side events (available via the ClientSideEvents property of extension settings) is handled.
How to Access an Extension on the Client
An extension client object can be accessed on the client using the extension name defined using the SettingsBase.Name property.
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
If the SettingsBase.Name property contains special characters, use the approach described in the following Knowledge Base Article to access the client-side programmatic object.
KA18687: How to use the ClientInstanceName and Name properties when they contain special characters
Client-Side Events
DevExpress MVC Extensions expose a number of client events, allowing you to promptly respond to end-user manipulations without server processing.
Extension specific client events can be accessed using the ClientSideEvents property. It is available through an extension setting object (such as MenuSettingsBase.ClientSideEvents) or through the properties object related to a settings object (such as Properties.ClientSideEvents which is TextBoxSettings.Properties -> TextBoxProperties.ClientSideEvents for TextBox) for data editors.
The following code demonstrates how client events can be handled - by implementing a separate function (for the Menu’s ItemClick event) or directly within the markup (for the Button’s Click event).
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()
See Also: Client-Side Events of DevExpress ASP.NET Controls
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 |
|---|---|---|
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxPivotGrid.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxTreeList.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxHtmlEditor.Scripts | ||
Navigation Extensions: |
|
|
DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
Data Editors Extensions: |
|
|
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
:DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
Utilities Extensions: |
|
|
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
DevExpress.Web.Scripts | ||
DevExpress.Web.MVC.Scripts, DevExpress.Web.Scripts | ||
Chart Extension: |
|
|
DevExpress.Web.MVC.Scripts, DevExpress.XtraCharts.Web.Scripts | ||
Report Extension: |
|
|
DevExpress.Web.MVC.Scripts, DevExpress.XtraReports.Web.Scripts | ||
Scheduler Extension: |
|
|
DevExpress.Web.MVC.Scripts, DevExpress.Web.ASPxScheduler.Scripts |