jQuery SPA Framework - Markup Components - Command
A markup component used to define markup options for a command.
The dxCommand markup component allows you to define a view-related action in an abstract way. Add a div element to the root of the view markup with the data-bind attribute set to dxCommand. Use the configuration options of the dxCommand component to define an action in an abstract way. These options include the handler performed when executing the command, the title, the icon, and the enabled and visible states.
<div data-options="dxView: { name: 'index', title: 'Home' }">
<div data-bind="dxCommand: { id: 'myCommand', onExecute: '#product-details', title: 'Add' } "></div>
</div>As you can see in the code above, a command can be used for navigation. In this instance, you can set the onExecute option to a URI or to an object defining a URI. In addition, you can specify navigation options for a command - the options that have the same names as the fields of the options object passed as the second parameter to the HtmlApplication.navigate(uri, options) method.
A command's markup options can be bound to ViewModel fields. Here is an example.
<div data-options="dxView: { name: 'home', title: 'Home' }">
<div data-bind="dxCommand: { id: 'myCommand', onExecute: add, title: 'Add' } "></div>
</div>To function properly, this code snippet expects the "add" field to be present in the ViewModel.
To be displayed, a command must be registered within a command container using the application's command mapping. Depending on the command container chosen for a command in a layout and the device the application is running on, different widgets will be used to display commands. You can specify widget configuration settings directly within the dxCommand component's configuration object.
<div data-bind="dxCommand: { id: 'myCommand', onExecute: '#product-details', title: 'Add', hint: 'Add a product' } "></div>In the code above, the specified hint option will be applied if the widget that will display the command has the hint option in its configuration.
To learn more about commands and how to display them in a view, read the Add Commands to Views topic.
Configuration
| Name | Description |
|---|---|
| disabled |
Indicates whether or not the widget that displays this command is disabled. |
| elementAttr |
Specifies the attributes to be attached to the widget's root element. |
| height |
Specifies the widget's height. |
| icon |
Specifies the name of the icon shown inside the widget associated with this command. |
| id |
The identifier of the command. |
| onDisposing |
A handler for the disposing event. Executed when the widget is removed from the DOM using the remove(), empty(), or html() jQuery methods only. |
| onExecute |
Specifies an action performed when the execute() method of the command is called. |
| onInitialized |
A handler for the initialized event. Executed only once, after the widget is initialized. |
| onOptionChanged |
A handler for the optionChanged event. Executed after an option of the widget is changed. |
| renderStage |
Specifies whether the current command is rendered when a view is being rendered or after a view is shown. |
| rtlEnabled |
Switches the widget to a right-to-left representation. |
| title |
Specifies the title of the widget associated with this command. |
| type |
Specifies the type of the button, if the command is rendered as a Button widget. |
| visible |
A Boolean value specifying whether or not the widget associated with this command is visible. |
| width |
Specifies the widget's width. |
Methods
| Name | Description |
|---|---|
| beginUpdate() |
Prevents the widget from refreshing until the endUpdate() method is called. |
| defaultOptions(rule) |
Specifies the device-dependent default configuration options for this component. |
| dispose() |
Disposes of all the resources allocated to the dxCommand instance. |
| element() |
Gets the root widget element. |
| endUpdate() |
Refreshes the widget after a call of the beginUpdate() method. |
| execute() |
Executes the action associated with this command. |
| getInstance(element) |
Gets the instance of a widget found using its DOM node. |
| instance() |
Gets the widget's instance. Use it to access other methods of the widget. |
| off(eventName) |
Detaches all event handlers from a single event. |
| off(eventName, eventHandler) |
Detaches a particular event handler from a single event. |
| on(eventName, eventHandler) |
Subscribes to an event. |
| on(events) |
Subscribes to events. |
| option() |
Gets all widget options. |
| option(optionName) |
Gets the value of a single option. |
| option(optionName, optionValue) |
Updates the value of a single option. |
| option(options) |
Updates the values of several options. |
Events
| Name | Description |
|---|---|
| disposing |
Raised when the widget is removed from the DOM using the remove(), empty(), or html() jQuery methods only. |
| initialized |
Raised only once, after the widget is initialized. |
| optionChanged |
Raised after a widget option is changed. |