• View
• Edit
• History
• Print

Input

Overview

An accessor may define any number of inputs in the body of its setup() function using

• input(<string> name, [options]): Create an input with the specified name and options.

For example:

The input() function takes one or two arguments, a name (a required string, recommended to be camelCase with a leading lower-case character) and an object giving any of the options:

The name is required to be distinct from other inputs, outputs, and parameters. It may match the name of an input in a base accessor (specified by either extend() or implement()), in which case the options will override those specified in the base.

Getting Inputs

The current value of an input may be retrieved in the accessor's JavaScript code using the get() function, as in the following example:

The get() function takes one argument, the input name (as a string). If the input definition includes a value option, then get() will not return null unless the accessor has specifically been sent a null. If you call get() before the accessor host has provided any input value, then the returned value will be that given in the value option. Subsequently, the returned value will be the most recent value provided by the accessor host.

If no value option is given, then get() will return null if called before the host has provided an input. In addition, get() may return null if there is no current input value provided by the host. This enables the host to fire the accessor while providing some and not all of the inputs. Thus, it is good programming practice to test the return value of get() for null if no value attribute is provided.

Sending to Inputs

An accessor may use the send() function to send values to its own inputs. Typically, this would be done in a callback function that is triggered by some external event. It could also be done in accessor that extends another accessor and wishes to set the value of an input in the base accessor. A side effect of sending a value to its own input port is to trigger an input handler given using addInputHandler().

For example, suppose that the following line is executed in a callback:

This will send the string "127.0.0.1" to the bridgeIPAddress input. After the callback function has completed execution, the accessor host will call any input handler that has been registered for this port using addInputHandler(). In the body of the handler, the accessor can call get() to retrieve the value of the input.

If an accessor sends a value to its own input in an input handler or in the fire() function, the updated value of that input will not be available until the next reaction. An input value remains constant throughout a reaction.

If you send a null value to an input, then get() on that input will return null on the next invocation, even if a value attribute is given for that input.

Setting the Default Value of an Input

As shown above, if a 'value' option is given when defining an input, then the input will have a default value. You can change that default value (or add one to an input that did not previously have one) using the setDefault() function. For example:

Unlike using send(), however, this will not trigger execution of any input handler. Also unlike send(), the host may treat this new default value as a persistent value, to become a permanent default, even in future executions of the same swarmlet.

Setting the default in this way can be useful in an accessors that extends another, but wishes to change the default value provided by the base accessor.

See Also

• Output
• Parameter

Back to accessor specification