ScenarioObserver

Method summary

Methods

bindAutoForm ( options ) → {ScenarioObserver}

Bind an AutoForm DOM element that matches the formId property in the options argument.

Parameters:

Name	Type	Description
options	ScenarioObserver~BindAutoFormOptions	AutoForm binding options

Returns:

Type	Description
ScenarioObserver

Back to Top

bindAutoTable ( options ) → {ScenarioObserver}

Bind an AutoTable DOM element that matches the tableId property in the options argument. The options and overrides objects passed in should match the AutoTable constructor arguments except where it is expecting Scenario objects you can pass scenario id and they will get resolved.

Parameters:

Name	Type	Description
options	ScenarioObserver~BindAutoTableOptions	AutoTable binding options

Returns:

Type	Description
ScenarioObserver

Back to Top

bindAutoText ( options ) → {ScenarioObserver}

Bind AutoText elements from the DOM that match the selector property in the options argument. Alternatively, if a string arguments is passed in the this acts as the selector.

Parameters:

Name	Type	Description
options	ScenarioObserver~BindAutoTextOptions | string	AutoText binding options object or the the selector is a string

Returns:

Type	Description
ScenarioObserver

Back to Top

bindImageAttachments ( options ) → {ScenarioObserver}

Bind IMG elements marked with the 'data-attachment-filename' attribute, to display image attachments in the page.

Parameters:

Name	Type	Description
options	ScenarioObserver~BindImageAttachmentOptions | jQuery | string	an image attachment binding options object, a jQuery selector or a CSS selector string

Returns:

Type	Description
ScenarioObserver

Back to Top

dispose ( )

This stops the event listener for the configured scenarios and entities. The notify callback or bound auto components related to this scenario observer will not receive any further updates.

Back to Top

filter ( entity, callback ) → {ScenarioObserver}

Apply a filter to an InsightArray. The filtering is done on the server-side and the client will only have access to elements matching the specified index filters.

Parameters:

Name	Type	Description
entity	string	the entity name to filter on
callback	ScenarioObserver~FilterCallback	the filter to apply

Returns:

Type	Description
ScenarioObserver

Example

insight.getView()
    .withFirstScenario()
    .withViewProperties('selectedDay')
    .withEntities('SUPPLY')
    .filter('SUPPLY', function (viewProperties) {
        // Array filter: filters the 'DAY' index of the array by the value of a view property called
        // 'selectedDay' and filters the 'REGION' index of the array by hard-coded values.
        return {
            'DAY': [viewProperties.get('selectedDay')],
            'REGION': ['SOUTH', 'WEST']
        }
    })
    .notify(function (scenario) {})
    .start();

Back to Top

isDisposed ( ) → {boolean}

Check if the scenario observer is disposed.

Returns:

Type	Description
boolean	Whether this scenario observer is disposed

Back to Top

notify ( callback ) → {ScenarioObserver}

Add a function to be called when there are data changes, depending on what has been subscribed to.

Parameters:

Name	Type	Description
callback	NotifyCallback	the callback to invoke

Returns:

Type	Description
ScenarioObserver

Back to Top

once ( callback ) → {ScenarioObserver}

Add a function to be called once with the requested data and then dispose this observer. once() and notify() are mutually exclusive.

Parameters:

Name	Type	Description
callback	NotifyCallback	the callback to invoke

Returns:

Type	Description
ScenarioObserver

Back to Top

start ( ) → {ScenarioObserver}

This tells the system to go and fetch the configured scenarios and entities and return their values. Also it starts listening for change events on those scenarios and entities.

Returns:

Type	Description
ScenarioObserver

Back to Top

withAttachments ( options ) → {ScenarioObserver}

Registers this observer to be notified whenever the scenario or app attachments change.

The argument to this function can be one of the following:

• An array of tags to observe.
• A single tag to observe.
• A configuration object (of type WithAttachmentsOptions) indicating which tags to observe and whether to observe scenario or app attachments.

Parameters:

Name	Type	Description
options	ScenarioObserver~WithAttachmentsOptions

Returns:

Type	Description
ScenarioObserver

Example

insight.ready(function () {
     var view = insight.getView();
     view
             .withFirstScenario()
             .withAttachments({tags: ['tagA', 'tagB'], app: true, scenario: true})
             .notify(function (scenario) {
                 // code to access attachments here...
             });
            });

Back to Top

withEntities ( entities ) → {ScenarioObserver}

Specify the entities this scenario observer is interested in.

Parameters:

Name	Type	Description
entities	string | Array.<string>	the entities to observe

Returns:

Type	Description
ScenarioObserver

Back to Top

withExecutionStatus ( ) → {ScenarioObserver}

Registers this observer to be notified whenever the scenario execution status changes. Retrieve the execution status from the scenario(s) using Scenario#getExecutionStatus.

Returns:

Type	Description
ScenarioObserver

Example

insight.getView()
  .withFirstScenario()
  .withExecutionStatus()
  .notify(function (scenario) {
    // Retrieve the current ScenarioExecutionStatus from a Scenario.
    scenario.getExecutionStatus().getJobId();
  });

Back to Top

withSummaryData ( ) → {ScenarioObserver}

Registers this observer to be notified whenever the scenario summary changes. Can be used in combination with ScenarioObserver#withEntities to get notified when either the summary data or entity data change.

Returns:

Type	Description
ScenarioObserver

Back to Top

withViewProperties ( viewProperties ) → {ScenarioObserver}

Specify the view properties this scenario observer is interested in.

Parameters:

Name	Type	Description
viewProperties	string | Array.<string>	the view properties to observe

Returns:

Type	Description
ScenarioObserver

Back to Top

Type Definitions

BindAutoFormOptions - { object }

Properties:

Name	Type	Argument	Description
formId	string		id of the DOM element to bind to
scenario	string | number	optional	the scenario id or index to use, defaults to the first scenario in the selection
loadButton	string	optional	id of the DOM element to bind the load action to
runButton	string	optional	id of the DOM element to bind the run action to
saveButton	string	optional	id of the DOM element to bind the save action to
cancelButton	string	optional	id of the DOM element to bind the cancel action to
additionalBindings	object	optional	additional binding information passed in to the AutoForm. See the AutoForm#bindForm inputs argument

BindAutoTableError ( error )

Parameters:

Name	Type	Description
error	Error	The error encountered

Back to Top

BindAutoTableOptions - { object }

Properties:

Name	Type	Argument	Default	Description
tableId	string			id of the DOM table element to bind to
scenario	string | number	optional		scenario id or index to use, defaults to the first scenario in the selection
columnOptions	Array.<AutoTable~ColumnOptions>	optional		list of column options for AutoTable. The scenario properties on columns can be specified as a scenario index or id and they will automatically be transposed into Scenario objects
indicesOptions	Object.<string, (AutoTable~IndicesOptions|Array.<AutoTable~IndicesOptions>)>	optional		map of indices options for AutoTable
overrides	object	optional		map of DataTables overrides for AutoTable
addRemoveRow	boolean	optional	false	enable the add/remove row functionality. See the AutoTable constructor
onError	ScenarioObserver~BindAutoTableError	optional		Callback if Autotable creation leads to error

BindAutoTextOptions - { object }

Properties:

Name	Type	Argument	Description
selector	string		a jQuery selector defining the DOM elements to bind to
scenario	string | number	optional	the scenario id or index to use, defaults to the first scenario in the selection

BindImageAttachmentOptions - { object }

Properties:

Name	Type	Description
selector	string	a jQuery selector or CSS selector string defining the IMG elements to bind to within the DOM

FilterCallback ( viewProperties ) → {Object.<(string|number), *>}

Filter callback to apply to the entity.

At times it is desirable to only retrieve a slice of an array, i.e. only retrieve the elements for a subset of the array's index values. This callback should return an object containing an array of values to use for each index set. If the index set is not included in the object then all values in the index set are used. The index set can either be specified by name or by ordinal. (The first index set of the array has ordinal 0.)

Parameters:

Name	Type	Description
viewProperties	MaskedViewProperties	Only allows access to the view properties that this scenario observer is listening to

Returns:

Type	Description
Object.<(string|number), *>	the filter; a map from index set name (or ordinal) to array of filter values

Example

// Array filter: filters the second index of the array by the value of a view property called 'selectedDay'
function (viewProperties) {
    return {
        1: [viewProperties.get('selectedDay')]
    }
}

// Array filter: filters the 'DAY' index of the array by the value of a view property called 'selectedDay' and
// filters the 'REGION' index of the array by hard-coded values.
function (viewProperties) {
    return {
        'DAY': [viewProperties.get('selectedDay')],
        'REGION': ['SOUTH', 'WEST']
    }
}

Back to Top

ScenarioObserverOptions - { object }

Properties:

Name	Type	Argument	Description
disposeCallback	function	optional	to be called when the observer is disposed
startCallback	function	optional	to be called when the observer is started

WithAttachmentsOptions - { object }

Properties:

Name	Type	Argument	Default	Description
tags	string | Array.<string>	optional		List of tags to observe (if not provided, all attachments will be observed)
filenames	string | Array.<string>	optional		List of filenames to observe (if not provided, all attachments will be observed)
scenario	boolean	optional	true	Whether to notify the callback when scenario attachments are changed
app	boolean	optional	true	Whether to notify the callback when app attachments are changed ScenarioObserver#withAttachments argument