variables channel

Channels are ways for Flow.js to talk to external APIs -- primarily the underlying Epicenter APIs.

The primary use cases for the Variables Channel are:

publish: Update a model variable.
subscribe: Receive notifications when a model variable is updated.

For example, use publish() to update a model variable:

 Flow.channel.operations.publish('myVariable', newValue);

For reference, an equivalent call using Flow.js custom HTML attributes is:

 <input type="text" data-f-bind="myVariable" value="newValue"></input>

where the new value is input by the user.

You can also use subscribe() and a callback function to listen and react when the model variable has been updated:

 Flow.channel.operations.subscribe('myVariable',
     function() { console.log('called!'); } );

To use the Variables Channel, simply initialize Flow.js in your project.

Configuration Options

silent

String

Determine when to update state. Defaults to false: always trigger updates.

Possible options are:

true: Never trigger any updates. Use this if you know your model state won't change based on other variables.
false: Always trigger updates.
[array of variable names]: Variables in this array will not trigger updates; everything else will.
{ except: [array of variable names] }: Variables in this array will trigger updates; nothing else will.

To set, pass this into the Flow.initialize() call in the channel.run.variables field:

 Flow.initialize({
     channel: {
         run: {
             model: 'myModel.py',
             account: 'acme-simulations',
             project: 'supply-chain-game',
             variables: { silent: true }
         }
     }
 });

To override for a specific call to the Variables Channel, pass this as the final options parameter:

  Flow.channel.variables.publish('myVariable', newValue, { silent: true });

autoFetch

Object

Allows you to automatically fetch variables from the API as they're being subscribed. If this is set to enable: false you'll need to explicitly call refresh() to get data and notify your listeners.

The properties of this object include:

autoFetch.enable Boolean Enable auto-fetch behavior. If set to false during instantiation there's no way to enable this again. Defaults to true.
autoFetch.start Boolean If auto-fetch is enabled, control when to start fetching. Typically you'd want to start right away, but if you want to wait till something else happens (like an operation or user action) set to false and control using the startAutoFetch() function. Defaults to true.
autoFetch.debounce Number Milliseconds to wait between calls to subscribe() before calling fetch(). See http://drupalmotion.com/article/debounce-and-throttle-visual-explanation for an explanation of how debouncing works. Defaults to 200.

readOnly

Boolean

Allow using the channel for reading data (subscribing), but disallow calls to publish. Defaults to false: allow both subscribing and publishing. If a function is provided, the function should return a Boolean value to override.

Methods

refresh

Force a check for updates on the channel, and notify all listeners.

Parameters

changeList: Object|Array Key-value pairs of changed variables.
force: Boolean Ignore all silent options and force refresh.
options: Object (Optional) Overrides for the default channel options.

Return Value

promise: Promise on completion

notify

Alert each subscriber about the variable and its new value.

Example

 Flow.channel.operations.notify('myVariable', newValue);

Parameters

topics: String|Array Names of variables.
value: String|Number|Array|Object New values for the variables.

Return Value

publish

Update the variables with new values, and alert subscribers.

Example

 Flow.channel.variables.publish('myVariable', newValue);
 Flow.channel.variables.publish({ myVar1: newVal1, myVar2: newVal2 });

Parameters

variable: String|Object String with name of variable. Alternatively, object in form { variableName: value }.
value: String|Number|Array|Object (Optional) Value of the variable, if previous argument was a string.
options: Object (Optional) Overrides for the default channel options. Supported options: { silent: Boolean } and { batch: Boolean }.

Return Value

$promise: Promise to complete the update.

Subscribe to changes on a channel: Ask for notification when variables are updated.

Example

 Flow.channel.variables.subscribe('myVariable',
     function() { console.log('called!'); });

 Flow.channel.variables.subscribe(['price', 'cost'],
     function() {
         // this function called only once, with { price: X, cost: Y }
     },
     { batch: true });

 Flow.channel.variables.subscribe(['price', 'cost'],
     function() {
         // this function called twice, once with { price: X }
         // and again with { cost: Y }
     },
     { batch: false });

Parameters

topics: String|Array The names of the variables.
subscriber: Object|Function The object or function being notified. Often this is a callback function. If this is not a function, a trigger method is called if available; if not, event is triggered on $(object).
options: Object (Optional) Overrides for the default channel options.
options.silent: Boolean Determine when to update state.
options.batch: Boolean If you are subscribing to multiple variables, by default the callback function is called once for each item to which you subscribe: batch: false. When batch is set to true, the callback function is only called once, no matter how many items you are subscribing to.

Return Value

String: An identifying token for this subscription. Required as a parameter when unsubscribing.

unsubscribe

Stop receiving notifications for all subscriptions referenced by this token.

Parameters

token: String The identifying token for this subscription. (Created and returned by the subscribe() call.)

Return Value

unsubscribeAll

Stop receiving notifications for all subscriptions. No parameters.

Return Value