flow | Documentation

Flow.js Initialization

To use Flow.js in your project, simply call Flow.initialize() in your user interface. In the basic case, Flow.initialize() can be called without any arguments. While Flow.js needs to know the account, project, and model you are using, by default these values are extracted from the URL of Epicenter project and by the use of data-f-model in your <body> tag. See more on the basics of using Flow.js in your project..

However, sometimes you want to be explicit in your initialization call, and there are also some additional parameters that let you customize your use of Flow.js.

Parameters

The parameters for initializing Flow.js include:

channel Configuration details for the channel Flow.js uses in connecting with underlying APIs.
channel.strategy The run creation strategy describes when to create new runs when an end user visits this page. The default is new-if-persisted, which creates a new run when the end user is idle for longer than your project's Model Session Timeout (configured in your project's Settings), but otherwise uses the current run.. See more on Run Strategies.
channel.run Configuration details for each run created.
channel.run.account The User ID or Team ID for this project. By default, taken from the URL where the user interface is hosted, so you only need to supply this is you are running your project's user interface on your own server.
channel.run.project The Project ID for this project.
channel.run.model Name of the primary model file for this project. By default, taken from data-f-model in your HTML <body> tag.
channel.run.variables Configuration options for the variables being listened to on this channel.
channel.run.variables.silent Provides granular control over when user interface updates happen for changes on this channel. See below for possible values.
channel.run.variables.autoFetch Options for fetching variables from the API as they're being subscribed. See Variables Channel for details.
channel.run.operations Configuration options for the operations being listened to on this channel. Currently there is only one configuration option: silent.
channel.run.operations.silent Provides granular control over when user interface updates happen for changes on this channel. See below for possible values.
channel.run.server Object with additional server configuration, defaults to host: 'api.forio.com'.
channel.run.transport An object which takes all of the jquery.ajax options at http://api.jquery.com/jQuery.ajax/.
dom Configuration options for the DOM where this instance of Flow.js is created.
dom.root The root HTML element being managed by the Flow.js DOM Manager. Defaults to body.
dom.autoBind If true (default), automatically parse variables added to the DOM after this Flow.initialize() call. Note, this does not work in IE versions < 11.

The silent configuration option for the run.variables and run.operations is a flag for providing more granular control over when user interface updates happen for changes on this channel. Values can be:

false: Always update the UI for any changes (variables updated, operations called) on this channel. This is the default behavior.
true: Never update the UI for any on changes (variables updated, operations called) on this channel.
Array of variables or operations for which the UI should not be updated. For example, variables: { silent: [ 'price', 'sales' ] } means this channel is silent (no updates for the UI) when the variables 'price' or 'sales' change, and the UI is always updated for any changes to other variables. This is useful if you know that changing 'price' or 'sales' does not impact anything else in the UI directly, for instance.
except: With array of variables or operations for which the UI should be updated. For example, variables { silent: { except: [ 'price', 'sales' ] } } is the converse of the above. The UI is always updated when anything on this channel changes except when the variables 'price' or 'sales' are updated.

Although Flow.js provides a bi-directional binding between the model and the user interface, the silent configuration option applies only for the binding from the model to the user interface; updates in the user interface (including calls to operations) are still sent to the model.

The Flow.initialize() call is based on the Epicenter.js Run Service from the API Adapters. See those pages for additional information on parameters.

The Flow.initialize() call returns a promise, which is resolved when initialization is complete.

Example

 Flow.initialize({
     channel: {
         strategy: 'new-if-persisted',
         run: {
             model: 'supply-chain-game.py',
             account: 'acme-simulations',
             project: 'supply-chain-game',
             server: { host: 'api.forio.com' },
             variables: { silent: ['price', 'sales'] },
             operations: { silent: false },
             transport: {
                 beforeSend: function() { $('body').addClass('loading'); },
                 complete: function() { $('body').removeClass('loading'); }
             }
         }
     }
 }).then(function() {
     // code that depends on initialization
 });