Module: Commands

Overview

An extension can register a Commands Module by defining a getCommandsModule method. The Commands Module allows us to register one or more commands scoped to specific contexts. Commands have several unique characteristics that make them tremendously powerful:

• Multiple implementations for the same command can be defined
• Only the correct command's implementation will be run, dependent on the application's "context"
• Commands can be called from extensions, modules, and the consuming application

Here is a simple example commands module:

export default {
  id: 'example-commands-module',

  /**
   * @param {object} params
   * @param {ServicesManager} params.servicesManager
   * @param {CommandsManager} params.commandsManager
   */
  getCommandsModule({ servicesManager, commandsManager }) {
    return {
      definitions: {
        sayHello: {
          commandFn: ({ words }) => {
            console.log(words);
          },
          options: { words: 'Hello!' },
        },
      },
      defaultContext: 'VIEWER',
    };
  },
};

Each definition returned by the Commands Module is registered to the ExtensionManager's CommandsManager.

Command Definitions

The command definition consists of a named command (myCommandName below) and a commandFn. The command name is used to call the command, and the commandFn is the "command" that is actioned.

myCommandName: {
    commandFn: ({ viewports, other, options }) => { },
    storeContexts: ['viewports'],
    options: { words: 'Just kidding! Goodbye!' },
    context: 'ACTIVE_VIEWPORT::CORNERSTONE',
}

Property	Type	Description
commandFn	func	The function to call when command is run. Receives options and storeContexts.
storeContexts	string[]	(optional) Expected state objects to be passed in as props. Located using getAppState fn defined at CommandsManager's instantiation.
options	object	(optional) Arguments to pass at the time of calling to the commandFn
context	string[] or string	(optional) Overrides the defaultContext. Let's us know if command is currently "available" to be run.

Command Behavior

I have many similar commands. How can I share their commandFn and make it reusable?

This is where storeContexts and options come in. We use these in our setToolActive command. storeContexts helps us identify our activeViewport, and options allow us to pass in the name of a tool we would like to set as active.

If there are multiple valid commands for the application's active contexts

• What happens: all commands are run
• When to use: A clearData command that cleans up state for multiple extensions

If no commands are valid for the application's active contexts

• What happens: a warning is printed to the console
• When to use: a hotkey (like "invert") that doesn't make sense for the current viewport (PDF or HTML)

CommandsManager

The CommandsManager is a class defined in the @ohif/core project. A single instance of it should be defined in the consuming application, and it should be used when constructing the ExtensionManager.

Instantiating

When we instantiate the CommandsManager, we need to pass it two methods:

• getAppState - Should return the application's state when called
• getActiveContexts - Should return the application's active contexts when called

These methods are used internally to help determine which commands are currently valid, and how to provide them with any state they may need at the time they are called.

const commandsManager = new CommandsManager({
  getAppState,
  getActiveContexts,
});

Public API

If you would like to run a command in the consuming app or an extension, you can use one of the following methods:

// Returns all commands for a given context
commandsManager.getContext('string');

// Attempts to run a command
commandsManager.runCommand('speak', { command: 'hello' });

// Run command, but override the active contexts
commandsManager.runCommand('speak', { command: 'hello' }, ['VIEWER']);

The ExtensionManager handles registering commands and creating contexts, so most consumer's won't need these methods. If you find yourself using these, ask yourself "why can't I register these commands via an extension?"

// Used by the `ExtensionManager` to register new commands
commandsManager.registerCommand('context', 'name', commandDefinition);

// Creates a new context; clears the context if it already exists
commandsManager.createContext('string');

Contexts

It is up to the consuming application to define what contexts are possible, and which ones are currently active. As extensions depend heavily on these, we will likely publish guidance around creating contexts, and ways to override extension defined contexts in the near future. If you would like to discuss potential changes to how contexts work, please don't hesitate to create new GitHub issue.

Some additional information on Contexts can be found here.