Command pattern

The command pattern encapsulates interface actions into reusable objects, which separates logic for executing an action from concrete widgets and objects into its testable unit. One command can have several UI objects that cause the command pattern to execute.

The command base class is epi/shell/command/_Command.

Methods

The command base has a public execute method that executes the action if canExecute is true. You can explicitly call this, but the interface objects associated with the command typically call it.

The command base also has two protected methods you should override by implementing classes.

• It calls_execute after checking that the command is executable. In this method, define the command's execution logic.
• It calls _onModelChange when you set the model on the command. It updates the state of canExecute based on the new model object.

Stateful

Commands are stateful so that you can watch for changes to their properties. For example, you can watch canExecute, which allows the display state (such as enabled or disabled) of interface objects, which represent the command to be updated when canExecute changes. Also, you can set the model on which the command executes or determines its state using set("model", value), which calls the protected _onModelChange method on the command, which updates the state of canExecute for the new model.

📘

Note

A stateless protocol does not require the server to retain session information or status about each communications partner for the duration of multiple requests. In contrast, a protocol which requires keeping of the internal state on the server is known as a stateful protocol. Source: Wikipedia

Example

See below for a sample command implementation.

define([
    "dojo/_base/declare",
    "epi/dependency",
    "epi/shell/command/_Command"
  ],
  function (declare, dependency, _Command) {
    return declare([_Command], {
      constructor: function () {
        // summary:
        //   Constructs the object and sets up a reference to the content data store.
        // tags:
        //   public

        var registry = dependency.resolve("epi.storeregistry");
        this.store = registry.get("epi.cms.contentdata");
      },
      _execute: function () {
        // summary:
        //   Executes this command assuming canExecute has been checked.
        // tags:
        //   protected

        var model = this.model;
        model.isCommonDraft = true;
        return this.store.put(model);
      },
      _onModelChange: function () {
        // summary:
        //   Updates canExecute after the model has been updated.
        // tags:
        //   protected

        var model = this.model,
          canExecute = model && !model.isCommonDraft;
        this.set("canExecute", canExecute);
      }
    });
  }
);

Command providers and consumers

A provider and consumer pattern extends the principle of separating concerns to where you use the commands.

A widget or object that provides commands should not be responsible for displaying them; commands need to display elsewhere in the interface. For example, the page tree has commands such as create page, translate page, and so on, but the page tree should not be responsible for displaying these because it does not indicate where or how they should be displayed.

Instead, the generic component Chrome, in which the page tree resides, displays the commands. However, the page tree has no reference for the component chrome. You need a generic method to get the commands from the page tree to the component Chrome.

The epi/shell/command/_CommandProviderMixin> and epi/shell/command/_CommandConsumerMixin classes link the command's source and where they should be displayed. The provider has a list of commands, and the consumer has a list of command providers and displays the commands for those providers.