Client-Side Functionality
- 3 minutes to read
The DevExpress ASP.NET MVC Extensions provide an advanced client-side API that enables you to combine server-side and client-side functionality.
DevExpress MVC extensions’ client APIs are implemented using JavaScript. Extension-relative assemblies (DLLs) include JavaScript files that implement an extension’s client-side APIs as embedded resources.
Refer to the following section for more information about DevExpress MVC Extensions and their client-side objects: Extension Sheet.
Attach Required Script Files
If you create an MVC application based on a DevExpress Project Template, our DevExpress ASP.NET Project Wizard automatically attaches the necessary JavaScript files to the application’s _Layout page.
If you do not use a DevExpress project template, you need to manually attach all or extension-specific DevExpress client script files to your application. Use the ExtensionsFactory.GetScripts method within a view page’s HEAD tag to attach scripts. Specify extension types through the ExtensionSuite enumeration’s values.
<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.HtmlEditor },
new Script { ExtensionSuite = ExtensionSuite.GridView },
)
</head>
Refer to the following section for more information: Manual Integration into an Existing Project.
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.
Note
A client-side API member does not work if its corresponding element is not explicitly initialized on the server side. For example, if a menu item’s image is not specified on the server side, its corresponding image element is not rendered on the client side. In this particular instance, the menu item’s SetImageUrl client method is not in effect.
Access an Extension on the Client Side
Use the SettingsBase.Name property to specify an extension’s name. Use this name to access the extension’s client object in code.
<script>
function preserveTextBoxValue(){
var tbValue = textBox1.GetText();
// ...
}
</script>
<!-- ... -->
@Html.DevExpress().TextBox( settings => {
settings.Name = "textBox1";
settings.Text = "some text";
}).GetHtml()
Refer to the following 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): KB article.
Handle 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 ([ExtensionName]Settings.ClientSideEvents) or properties ([ExtensionName]Settings.Properties.ClientSideEvents) to access the available client-side events.
The following code demonstrates how to handle client-side events of extensions (the Menu‘s ItemClick and the Button‘s Click events):
<script>
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()
Note
Register event handling 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.
Refer to the following section for more information: DevExpress ASP.NET Controls Client-Side Events.