Simulation Development

Commands

A h:command is a globally accessible function. They can be accessed through the command pattern "path-to-command::function". Commands can be passed arguments when invoked. Commands can be thought of as global event listeners. When you invoke a command, you are dispatching a global event that the command is responding to.

Commands are declared in their own file. Like models, the path determines the location of the command. One or more commands can be declared in a single file. The organization of command is up to you.

If you are not familiar with creating a h:function, you should review the functions tutorial.

There are two parts to a command, the declaration (h:command) and the execution (h:exec).

Declaring a command

Open sandbox/commands/chat.xml. There you will see an example of a command. You will notice the namespace declaration:

<commands xmlns="http://certiport.com/hammer/sdk/commands"></commands>

Hammer uses this information to know this file represents a strings XML file. The xmlns is required by Hammer. It it is not declared will throw an error if it is missing.

Within this file, commands are declared with the following syntax:

<h:command name="{String}">
    Actions here...
</h:command>

A h:command can access a data object using {{ }} binding braces.

. See the section below to learn how to pass a data object.

Executing a command

To invoke a h:command, use h:exec.

<h:exec command="path/to/command::function">
    { myProp: myValue }
</h:exec>

The properties passed can be accessed directly using {{ myProp }}.

timer Exercise: Execute a command

In this exercise you will execute the command commands/chat::send located in sandbox/commands/chat.xml. This command accepts top properties name and message. It will open an alert box when it is invoked.

Launch in your browser http://localhost:8080/sandbox/#/tutorials/commands/command_start. It should open a page with "Commands Tutorial" displayed.

Open sandbox/slides/tutorials/commands/command_start.html in seed-exam in your editor.

We add the line that invokes the command inside the send function.

<h:function name="send" args="name, message">
    <h:exec command="commands/chat::send">
        {
        name: "{{name}}",
        message: "{{message}}"
        }
    </h:exec>
</h:function>

You will see that the function takes two arguments. We use those arguments to create a data object to pass to the command. The command consumes those properties and displays an alert box.

Refresh the page and click on the button to see the alert box.