dxBase

Namespace: Wisej.Web.Ext.DevExtreme

Assembly: Wisej.Web.Ext.DevExtreme (4.1.0.0)

Control
- Widget
  - dxBase

The dxBase class is the foundation of all DevExtreme visual controls.

C#
VB.NET

public abstract class dxBase : Widget

Public MustInherit Class dxBase
    Inherits Widget

Each derived control wraps one DevExtreme jQuery widget. The Options object is passed to the widget when it is created and every time it changes, Instance invokes the methods and attaches to the events of the widget, WidgetEvents and WidgetFunctions add JavaScript code that runs in the browser.

The scripts and style sheets to load, the default theme and the DevExtreme license key are read from the Wisej.Web.Ext.DevExtreme.json configuration file, which is searched in the root folder of the application first and then in the embedded resources. An exception is thrown when the file cannot be found.

Example:

The following example creates a data grid, changes its options, calls one of its methods and handles one of its events.

var grid = new dxDataGrid(new
{
	dataSource = customers,
	keyExpr = "id",
	selection = new { mode = "single" }
});
grid.Dock = DockStyle.Fill;
this.Controls.Add(grid);

// first level options are updated automatically,
// call Update() after changing a nested option.
grid.Options.showBorders = true;
grid.Options.selection.mode = "multiple";
grid.Update();

// call a method of the DevExtreme widget.
grid.Instance.searchByText("Berlin");

// handle an event fired by the DevExtreme widget.
grid.Instance.onRowClick += new WidgetEventHandler((s, e) =>
{
	AlertBox.Show($"Clicked row {e.Data.rowIndex}");
});

Constructors

dxBase(className, options)

Constructs a new instance of the dxBase class.

Name	Type	Description
className	String	Class name of the widget. It is the name of the DevExtreme jQuery plugin that creates the widget, i.e. "dxChart".
options	Object	Configuration options for the widget. See Options for the accepted values.

Throws:

ArgumentNullException className is null or empty.

Example:

The following example shows how a derived class wraps the DevExtreme dxButton widget.

public class dxButton : dxBase
{
	public dxButton(object options) : base("dxButton", options)
	{
	}
}

var button = new dxButton(new { text = "Save", type = "success" });
this.Controls.Add(button);

dxBase(className, options, html)

Constructs a new instance of the dxBase class.

Name	Type	Description
className	String	Class name of the widget. It is the name of the DevExtreme jQuery plugin that creates the widget, i.e. "dxChart".
options	Object	Configuration options for the widget. See Options for the accepted values.
html	String	Container HTML. See the widget's documentation to determine if it needs a custom HTML container. When specified, the widget is created on the first element defined in the HTML.

Throws:

ArgumentNullException className is null or empty.

Example:

The following example shows how a derived class creates the DevExtreme dxTextArea widget on a custom container element.

public class dxTextArea : dxBase
{
	public dxTextArea(object options)
		: base("dxTextArea", options, "<div class=\"notes-editor\"></div>")
	{
	}
}

var notes = new dxTextArea(new { placeholder = "Notes", maxLength = 200 });
this.Controls.Add(notes);

dxBase(className, options, events)

Constructs a new instance of the dxBase class.

Name	Type	Description
className	String	Class name of the widget. It is the name of the DevExtreme jQuery plugin that creates the widget, i.e. "dxChart".
options	Object	Configuration options for the widget. See Options for the accepted values.
events	String[]	List of wired events. The specified events can be attached to the Instance property. Use the names of the events fired by the DevExtreme widget, i.e. "click" or "valueChanged".

Throws:

ArgumentNullException className is null or empty.

Example:

The following example shows how a derived class wires the click event of the DevExtreme dxButton widget and how the application receives it.

public class dxButton : dxBase
{
	public dxButton(object options) : base("dxButton", options, new[] { "click" })
	{
	}
}

var button = new dxButton(new { text = "Save", type = "success" });
button.WidgetEvent += (s, e) =>
{
	if (e.Type == "click")
		AlertBox.Show("Saved.");
};
this.Controls.Add(button);

dxBase(className, options, html, events)

Constructs a new instance of the dxBase class.

Name	Type	Description
className	String	Class name of the widget. It is the name of the DevExtreme jQuery plugin that creates the widget, i.e. "dxChart".
options	Object	Configuration options for the widget. See Options for the accepted values.
html	String	Container HTML. See the widget's documentation to determine if it needs a custom HTML container. When specified, the widget is created on the first element defined in the HTML.
events	String[]	List of wired events. The specified events can be attached to the Instance property. Use the names of the events fired by the DevExtreme widget, i.e. "click" or "valueChanged".

Throws:

ArgumentNullException className is null or empty.

Example:

The following example shows how a derived class creates the DevExtreme dxTextBox widget on a custom container element and wires its valueChanged event.

public class dxTextBox : dxBase
{
	public dxTextBox(object options)
		: base("dxTextBox", options, "<div class=\"search-box\"></div>", new[] { "valueChanged" })
	{
	}
}

var search = new dxTextBox(new { placeholder = "Search...", showClearButton = true });
search.WidgetEvent += (s, e) =>
{
	if (e.Type == "valueChanged")
		AlertBox.Show($"Searching for {e.Data.value}");
};
this.Controls.Add(search);

Properties

Culture

CultureInfo: Returns or sets the culture for all the DevExtreme widgets in the session.

The default value is CurrentCulture. Setting the property to null restores the default.

The two-letter language code of the culture selects the locale of the DevExtreme widgets and replaces the %locale% placeholder in the package URLs defined in the configuration file, which is used to load the DevExtreme localized messages. The name of the culture replaces the %culture% placeholder.

The value is stored in the current session. Changing it recreates all the DevExtreme widgets that exist in the session.

Example:

The following example displays all the DevExtreme widgets in the session in German.

dxBase.Culture = new CultureInfo("de-DE");

Options

Object: Returns or sets the configuration options passed to the DevExtreme widget.

The property accepts an anonymous object, any other serializable object or a JSON string. The value is converted to a dynamic object, so the fields can always be read and changed after the assignment, including the nested ones. The names of the fields are the names of the options documented by DevExtreme for the wrapped widget.

Changes to first level fields are detected automatically. After changing a nested field call Update to update the widget.

A string value in the format "(args)=>name" or "()=>name()" is replaced on the client with the function with the same name defined in WidgetFunctions, or with its return value.

Example:

The following example assigns the options using an anonymous object and using a JSON string, then changes some of them.

this.dxChart1.Options = new
{
	title = new { text = "Sales" },
	series = new { argumentField = "month", valueField = "total", type = "bar" }
};

this.dxSwitch1.Options = "{\"value\": true, \"switchedOnText\": \"YES\", \"switchedOffText\": \"NO\"}";

// first level field: the widget is updated automatically.
this.dxChart1.Options.dataSource = sales;

// nested field: call Update().
this.dxChart1.Options.title.text = "Sales 2026";
this.dxChart1.Update();

Theme

String: Returns or sets the theme for all the DevExtreme widgets in the session.

The value is the name of a DevExtreme theme, i.e. "light", "dark" or "material.blue.light". It replaces the %theme% placeholder in the package URLs defined in the configuration file; with the default configuration the theme file is located using the "dx.{name}.css" pattern in the /css folder of the selected source.

If the value is not set or reset to null or to an empty string, it loads the theme specified in the configuration file.

The value is stored in the current session. Changing it updates all the DevExtreme widgets that exist in the session.

Example:

The following example switches all the DevExtreme widgets in the session to the dark material theme and then restores the theme defined in the configuration file.

dxBase.Theme = "material.blue.dark";

// restore the default theme.
dxBase.Theme = null;

WidgetEvents

WidgetEventHandler[]: Returns or sets the JavaScript handlers attached to the events of the DevExtreme widget on the client. (Default: null)

Each WidgetEventHandler is assigned to the option of the widget that has the same name as the handler, i.e. "onValueChanged", when the widget is created on the client. Assign this property before the control is displayed.

The handler runs in the browser and receives the event data in the e argument. To notify the server, call e.container.fireWidgetEvent(type, data) and handle the WidgetEvent event.

Example:

The following example attaches a JavaScript handler to the onValueChanged option of a switch and forwards the new value to the server.

this.dxSwitch1.WidgetEvents = new[]
{
	new dxBase.WidgetEventHandler
	{
		Name = "onValueChanged",
		Source = "e.container.fireWidgetEvent('switched', { value: e.value });"
	}
};
this.dxSwitch1.WidgetEvent += (s, e) =>
{
	if (e.Type == "switched")
	{
		bool value = e.Data.value;
		AlertBox.Show(value ? "On" : "Off");
	}
};

WidgetFunctions

WidgetFunction[]: Returns or sets the JavaScript functions added to the widget on the client. (Default: null)

Each WidgetFunction defines the name and the body of a function. The functions are used in two ways:

They are added to the client widget and can be invoked from the server using Call. Inside the function, this refers to the Wisej.NET widget, this.widget refers to the DevExtreme widget and the values passed by the caller are available in arguments.

They can be assigned to the options that expect a JavaScript function or an object created in JavaScript. Set the option in Options to a string in one of these formats, without spaces: "(arg1,arg2)=>name" assigns the function to the option using the specified argument names; "()=>name()" or "()=>name(1,'a')" calls the function when the options are applied and assigns the returned value to the option.

Example:

The following example uses a function to format the labels of a gauge and a function called from the server.

this.dxCircularGauge1.WidgetFunctions = new[]
{
	new dxBase.WidgetFunction
	{
		Name = "formatLabel",
		Source = "return arg.valueText + ' km/h';"
	},
	new dxBase.WidgetFunction
	{
		Name = "setSpeed",
		Source = "this.widget.value(arguments[0]);"
	}
};
this.dxCircularGauge1.Options.scale = new
{
	startValue = 0,
	endValue = 200,
	label = new { customizeText = "(arg)=>formatLabel" }
};

// later, call the "setSpeed" function.
this.dxCircularGauge1.Call("setSpeed", 120);

Methods

Dispose(disposing)

Disposes of resources.

Parameter	Type	Description
disposing	Boolean

Notify(message, type, displayTime)

Displays a DevExtreme toast with the given message.

Parameter	Type	Description
message	String	The text to display.
type	String	The type of message: "info", "warning", "error" or "success".
displayTime	Int32	Specifies the duration of the toast in milliseconds. The default is 500.

This method calls the DevExpress.ui.notify function in the browser: the DevExtreme library must be already loaded on the client, which happens when the first DevExtreme widget is displayed.

Example:

The following example shows a success toast for three seconds.

dxBase.Notify("The order has been saved.", "success", 3000);

OnWebRender(config)

Wire the client config to the server.

Parameter	Type	Description
config	Object

Inherited By

Name	Description
dxBullet	A bullet bar is a horizontal bar that indicates a bullet chart's primary value. The Bullet widget is useful when you need to compare a single measure to a target value.
dxCalendar	The Calendar is a widget that displays a calendar and allows an end user to select the required date within a specified date range.
dxChart	The Chart is an interactive widget that visualizes data from a local or remote storage using a great variety of series types.
dxCircularGauge	The CircularGauge is a widget that indicates values on a circular numeric scale.
dxColorBox	The ColorBox is a widget that allows an end user to enter a color or pick it out from the drop-down editor.
dxDataGrid	The DataGrid is a widget that represents data from a local or remote source in the form of a grid.
dxDateBox	The DateBox is a widget that displays a date and time in a specified format, and enables a user to pick or type in the required date/time value.
dxDiagram	The Diagram widget provides a visual interface to help you design new and modify existing diagrams.
dxDropDownButton	The DropDownButton is a button that opens a drop-down menu with a list of actions or options.
dxFileManager	The FileManager widget allows users to manage files and folders.
dxFilterBuilder	The FilterBuilder widget allows a user to build complex filter expressions with an unlimited number of filter conditions using the UI.
dxForm	The Form widget represents fields of a data object as a collection of label-editor pairs.
dxFunnel	The Funnel is a widget that visualizes a value at different stages in the form of a funnel.
dxGallery	The Gallery is a widget that displays a collection of images in a carousel.
dxGantt	The Gantt widget displays the task flow and dependencies between tasks.
dxHtmlEditor	HtmlEditor is a WYSIWYG editor that allows you to format textual and visual content and to output it in HTML or Markdown.
dxKanban	Represents a Kanban board using DevExtreme widgets.
dxLinearGauge	The LinearGauge is a widget that indicates values on a linear numeric scale.
dxList	The List is a widget that represents a collection of items in a scrollable list.
dxLookup	The Lookup is a widget that allows an end user to search for an item in a collection shown in a drop-down menu.
dxMap	The Map is an interactive widget that displays a geographic map with markers and routes.
dxMenu	The Menu widget is a panel with clickable items.
dxNavBar	The NavBar is a widget that navigates the application views.
dxPieChart	The PieChart is a widget that visualizes data as a circle divided into sectors that each represents a portion of the whole.
dxPivotGrid	The PivotGrid is a widget that allows you to display and analyze multi-dimensional data from a local storage or an OLAP cube.
dxPolarChart	The PolarChart is a widget that visualizes data in a polar coordinate system.
dxProgressBar	The ProgressBar is a widget that shows current progress.
dxRangeSelector	The RangeSelector is a widget that allows a user to select a range of values on a scale.
dxRangeSlider	The RangeSlider is a widget that allows an end user to choose a range of numeric values.
dxSankey	The Sankey is a widget that visualizes the flow magnitude between value sets.
dxScheduler	The Scheduler is a widget that represents scheduled data and allows a user to manage and edit it.
dxSparkline	The Sparkline widget is a compact chart that contains only one series.
dxSpeedDialAction	The SpeedDialAction is a button that performs a custom action. It is displayed as a floating action button or as an item of the speed dial menu opened by the floating action button.
dxSwitch	The Switch is a widget that can be in two states: "On" and "Off".
dxTileView	The TileView widget contains a collection of tiles.
dxTreeList	The TreeList is a widget that represents data from a local or remote source in the form of a multi-column tree view.
dxTreeMap	The TreeMap is a widget that displays hierarchical data by using nested rectangles.
dxTreeView	The TreeView widget is a tree-like representation of textual data.

Implements

Name	Description
IUserData
IBindableComponent
IDropTarget
IWisejComponent
IWisejControl
IWisejHandler
IWisejSerializable

Constructors​

dxBase(className, options)​

dxBase(className, options, html)​

dxBase(className, options, events)​

dxBase(className, options, html, events)​

Properties​

Culture​

Options​

Theme​

WidgetEvents​

WidgetFunctions​

Methods​

Dispose(disposing)​

Notify(message, type, displayTime)​

OnWebRender(config)​

Inherited By​

Implements​

Constructors

dxBase(className, options)

dxBase(className, options, html)

dxBase(className, options, events)

dxBase(className, options, html, events)

Properties

Culture

Options

Theme

WidgetEvents

WidgetFunctions

Methods

Dispose(disposing)

Notify(message, type, displayTime)

OnWebRender(config)

Inherited By

Implements