module:bajaux/commands/Command

module:bajaux/commands/Command

new (require("bajaux/commands/Command"))(params, invokeFunctionopt)

Description:

  • A Command is essentially an asynchronous function with a nicely formatted
    display name attached.

Source:
Example
new Command("baja.Format compatible display name", function () {
  alert("I'm a command!");
});

new Command("Format compatible display name", function () {
  return new Promise(function (resolve, reject) {
    setTimeout(function () {
      wobble.foo();
      resolve;
    }, 1000);
  });
});

new Command({
  displayName: "I'll be converted to a Format: %lexicon(baja:january)%",
  description: "I'll be converted to a Format too: %lexicon(baja:true)%",
  func: function () {
    alert("I'm a command!");
  }
});

new Command({
  module: "myModule", // Create a Command that gets its displayName, description                  
  lex: "myCommand",   // and icon from a module's lexicon.
  func: function () {
    alert("I'm a command!");
  }
});

new Command({
  undoable: () => {
    return promptUser('Are you sure you want to make this change?')
      .then((userSaidYes) => {
        if (!userSaidYes) { return; }

        // redoText/undoText may be strings, getters, or async getters
        // canRedo/canUndo may be booleans, getters, or async getters
        return {
          redo: () => console.log('perform the work of the command'),
          undo: () => console.log('revert/back out the work of the command'),
          redoText: () => 'Text describing what the command will do',
          undoText: () => 'Text describing what undoing the command will do',
          canRedo: () => true, // true if doing the work of the command is allowed
          canUndo: () => true // true if reverting the work of the command is allowed
        }
      });
});
Parameters:
Name Type Attributes Description
params String | Object

An Object Literal or the display name for
the Command.

Properties
Name Type Attributes Description
displayName String

The display name format
for the Command. This format will be used in
toDisplayName. This can also be the first argument, in which
case func must be the second.
func function <optional>

The function this command will execute. The
function can return a promise if it's going to be invoked asynchronously.
As of Niagara 4.11 this can be omitted if creating an undoable function.
undoable module:bajaux/commands/Command~Undoable | function <optional>

As
of Niagara 4.11, any necessary configuration to make this command undoable.
This can be either an undoable directly, or a function that resolves to one.
Please note that an undoable() function itself should not do the actual
work - the redo() function of the returned undoable should do the work.
Note that any asynchronous functions may be declared as synchronous when
passed to the constructor, for simplicity.
description String <optional>

A description of the
Command. This format will be used in toDescription.
enabled Boolean <optional>

The enabled state of the Command.
Defaults to true.
flags Number <optional>

The Command flags. Defaults to
Command.flags.ALL.
icon String <optional>

The Command Icon. This can also be a
String encoding an icon will be created from.
invokeFunction function <optional>

the function to invoke, if using the two-argument
constructor

Interfaces

Undoable

Members

(static) USER_DEFINED_1 :number

Description:

  • Reserved for use by Command subclasses.

Source:

Reserved for use by Command subclasses.

Type:
  • number

(static) USER_DEFINED_2 :number

Description:

  • Reserved for use by Command subclasses.

Source:

Reserved for use by Command subclasses.

Type:
  • number

(static) USER_DEFINED_3 :number

Description:

  • Reserved for use by Command subclasses.

Source:

Reserved for use by Command subclasses.

Type:
  • number

(static) USER_DEFINED_4 :number

Description:

  • Reserved for use by Command subclasses.

Source:

Reserved for use by Command subclasses.

Type:
  • number

(static) flags

Description:

  • Namespace containing numbers for comparing flag bits. C&P'ed directly
    from MgrController in workbench module.

Source:

Namespace containing numbers for comparing flag bits. C&P'ed directly
from MgrController in workbench module.

(static) flags.ALL :number

Description:

  • Match all flags.

Source:

Match all flags.

Type:
  • number

(static) flags.MENU_BAR :number

Description:

  • Makes the command be available in the main menu. Not typically used in web profiles, but will
    signal to Workbench (through bajaux interop) that the command should appear in the Workbench
    menu.

Source:

Makes the command be available in the main menu. Not typically used in web profiles, but will
signal to Workbench (through bajaux interop) that the command should appear in the Workbench
menu.

Type:
  • number

(static) flags.NONE :number

Description:

  • Match no flags.

Source:

Match no flags.

Type:
  • number

(static) flags.TOOL_BAR :number

Description:

  • Makes the command be available in the main toolbar.

Source:

Makes the command be available in the main toolbar.

Type:
  • number

Methods

defaultNotifyUser(err, paramsopt) → {Promise}

Description:

  • Provides a default way of notifying the user about a Command invocation
    failure. Shows a dialog with details about the error.

    You might override this at runtime with your own error dialog handler.

Source:
Since:
  • Niagara 4.12
Parameters:
Name Type Attributes Description
err Error | *
params object <optional>
Properties
Name Type Attributes Description
messageSummary string <optional>

any additional information you
would like to include in the error dialog
Returns:
Type
Promise

getAccelerator() → {Object}

Description:

  • Return the accelerator for the Command or null if
    nothing is defined.

Source:
See:
Returns:

The accelerator or null if nothing is defined.

Type
Object

getDescriptionFormat() → {String}

Description:

  • Get the unformatted description of the command.

Source:
Returns:
Type
String

getDisplayNameFormat() → {String}

Description:

  • Return the format display name of the command.

Source:
Returns:
Type
String

getFlags() → {Number}

Description:

  • Get this command's flags.

Source:
Returns:
Type
Number

getFunction() → {function}

Description:

  • Return the raw function associated with this command.

Source:
Returns:
Type
function

getIcon() → {String}

Description:

  • Return the Command's icon URI

Source:
Returns:
Type
String

getId()

Description:

  • Return a unique numerical id for the Command.

    This is id unique to every Command object created.

Source:

hasFlags(flags) → {Boolean}

Description:

  • Check to see if this command's flags match any of the bits of the
    input flags.

Source:
Parameters:
Name Type Description
flags Number

The flags to check against
Returns:
Type
Boolean

invoke() → {Promise}

Description:

  • Invoke the Command. Triggers a bajaux:invokecommand or
    bajaux:failcommand event, as appropriate.

    Arguments can be passed into invoke() that will be passed into the
    function's Command Handler.

Source:
Returns:

A promise object that will be resolved (or rejected)
once the Command's function handler has finished invoking.

Type
Promise

invokeFromEvent(e) → {Promise|*}

Description:

  • If your Command optionally implements this function, then CommandButton
    will call it on click instead of simply calling invoke. Use this in case
    your Command needs to respond differently based on where on the screen the
    user is pointing.

Source:
Since:
  • Niagara 4.11
Parameters:
Name Type Description
e JQuery.Event

the DOM event triggered by the user's request to
invoke this function
Returns:
Type
Promise | *

isCommand()

Description:

  • Always returns true.

Source:

isEnabled() → {Boolean}

Description:

  • Gets this command's enabled status.

Source:
Returns:
Type
Boolean

isLoading() → {Boolean}

Description:

  • Return true if the Command is still loading.

Source:
Returns:

true if still loading.

Type
Boolean

isToggleCommand()

Description:

  • Always returns false.

Source:

isUndoable() → {boolean}

Source:
Since:
  • Niagara 4.11
Returns:

true if this command is undoable

Type
boolean

jq(jqDomopt) → {JQuery}

Description:

  • If a jQuery DOM argument is specified, this will set the DOM.
    If not specified then no DOM will be set.
    This method will always return the jQuery DOM associated with this Command.

Source:
Parameters:
Name Type Attributes Description
jqDom JQuery <optional>

If specified, this will set the jQuery DOM.
Returns:

A jQuery DOM object for firing events on.

Type
JQuery

loading() → {Promise}

Description:

  • Return the loading promise for the Command.

    The returned promise will be resolved once the Command
    has finished loading.

Source:
Returns:

The promise used for loading a Command.

Type
Promise

merge(cmd) → {module:bajaux/commands/Command}

Description:

  • Attempt to merge this command with another command, and return a new
    Command that does both tasks. If the two commands are mutually
    incompatible, return a falsy value.

Source:
Example

Here is an example to show the basic concept. Commands that simply add two numbers together can easily be merged together thanks to the associative property. 

var AddCommand = function AddCommand(inc) {
  this.$inc = inc;
  Command.call(this, {
    displayName: 'Add ' + inc + ' to the given number',
    func: function (num) { return num + inc; }
  });
};
AddCommand.prototype = Object.create(Command.prototype);

AddCommand.prototype.merge = function (cmd) {
  if (cmd instanceof AddCommand) {
    return new AddCommand(this.$inc + cmd.$inc);
  }
};

var addOneCommand = new AddCommand(1),
    addFiveCommand = new AddCommand(5),
    addSixCommand = addOneCommand.merge(addFiveCommand);
addSixCommand.invoke(10)
  .then(function (result) {
    console.log('is 16? ', result === 16);
  });
Parameters:
Name Type Description
cmd module:bajaux/commands/Command
Returns:
Type
module:bajaux/commands/Command

off(eventopt, handleropt)

Description:

  • Unregister a function callback handler for the specified event.

Source:
Parameters:
Name Type Attributes Description
event String <optional>

The name of the event to unregister.
If name isn't specified, all events for the Command will be unregistered.
handler function <optional>

The function to unregister. If
not specified, all handlers for the event will be unregistered.

on(event, handler)

Description:

  • Register a function callback handler for the specified event.

Source:
Parameters:
Name Type Description
event String

The event id to register the function for.
handler function

The event handler to be called when the event is fired.

setAccelerator(acc)

Description:

  • Set the accelerator information for the Command.

Source:
See:
Parameters:
Name Type Description
acc Object | String | Number | null | undefined

The accelerator keyboard information. This can
be a keyCode number, a character (i.e. 'a') or an Object that contains the accelerator information.
If no accelerator should be used the null/undefined should be specified.

Properties
Name Type Attributes Description
keyCode String | Number

The key code of the accelerator. This can be a character
code number or a character (i.e. 'a').
ctrl Boolean <optional>

true if the control key needs to be pressed.
shift Boolean <optional>

true if the shift key needs to be pressed.
alt Boolean <optional>

true if the alt key needs to be pressed.
meta Boolean <optional>

true if a meta key needs to be pressed.

setDescriptionFormat(description)

Description:

  • Set the description format of the command. Triggers a
    bajaux:changecommand event.

Source:
Parameters:
Name Type Description
description String

the command description - supports baja Format
syntax

setDisplayNameFormat(displayName)

Description:

  • Set the display name format of the command. Triggers a
    bajaux:changecommand event.

Source:
Parameters:
Name Type Description
displayName String

display name - supports baja Format syntax

setEnabled(enabled)

Description:

  • Sets this command's enabled status. Triggers a
    bajaux:changecommand event.

Source:
Parameters:
Name Type Description
enabled Boolean

setFlags(flags)

Description:

  • Set this command's flags.

Source:
Parameters:
Name Type Description
flags Number

setFunction(func)

Description:

  • Set the Command's function handler.

Source:
Parameters:
Name Type Description
func function

The new function handler for the command.

setIcon(icon)

Description:

  • Sets the icon for this Command. Triggers a bajaux:changecommand event.

Source:
Parameters:
Name Type Description
icon String

The Command's icon (either a URI or a module:// ORD string)

toDescription() → {Promise}

Description:

  • Access the Command's description.

    In order to access the description, a promise will be returned
    that will be resolved once the command has been loaded and
    the description has been found.

Source:
Returns:

Promise to be resolved with the description

Type
Promise

toDisplayName() → {Promise}

Description:

  • Access the Command's display name.

    In order to access the display name, a promise will be returned
    that will be resolved once the command has been loaded and
    the display name has been found.

Source:
Returns:

Promise to be resolved with the display name

Type
Promise

trigger(name)

Description:

  • Triggers an event from this Command.

Source:
Parameters:
Name Type Description
name String

visit(func)

Description:

  • Visit this Command with the specified function.

Source:
Parameters:
Name Type Description
func function

Will be invoked with this
Command passed in as an argument.

(static) isUndoable(undoable) → {boolean}

Source:
Since:
  • Niagara 4.11
Parameters:
Name Type Description
undoable module:bajaux/commands/Command | module:bajaux/commands/Command~Undoable
Returns:

true if the given parameter is an undoable Command, or
is an Undoable object

Type
boolean