State

ol-ishare/state. State

State base class

The state being tracked, and the methods by which it is updated by a given sub-class, will be particular to the application or instance type for which that class has been created, but they must adhere to the restrictions defined here.

This base class encapsulates the core mechanisms of creating and managing an abstract state object and transferring to/recalling from a Store instance.

The state is essentially a dictionary where: Keys must be strings, and are set using the static VALID_KEYS property of the class. Stores mandate that all values must be able to be cast to strings; and the state will not assign values by reference with copies that will be only of types understood by JSON (i.e. no methods, events, etc. not present in base types).

Constructor

new State(storesopt, optionsopt)

Parameters:
Name Type Attributes Default Description
stores Array.<module:ol-ishare/store~Store> <optional>

Store instances to update when state changes. The first store in the array will be used as the default from which state will be retrieved.
options Object <optional>

Core State options
option.autoStore Boolean <optional>
 true

Whether to automatically send the state to all registered Store instances. If not set, then sendToStores() must be called when an store update is required.
options.interval Number <optional>
 250

Minimum interval in milliseconds between state upates. (And therefore between automatically sending state to stores, if configured.)
options.name String <optional>

Use for disambugating instances in Arrays, etc..
options.defaults Object <optional>

Default values for any or all keys in the state

Members

keys :Array.<String>

All keys in the state

Type:

name :String

The optional name specified at instanciation or class name

Type:

state :Object

State at the time accessed

Type:

defaults :Object

Default values for the state (if any)

Type:

defaultStore :module:ol-ishare/store~Store

The Store from which to fetch states by default

Type:
  • module:ol-ishare/store~Store

(static) VALID_KEYS :Array.<String>

All the keys that the state can track.

Used internally to create the state object.

Type:

Methods

addStore(store, makeDefaultopt)

Adds a Store to those that a state instance will update

Parameters:
Name Type Attributes Default Description
store module:ol-ishare/store~Store

Store to add. If the store is already registered then this will reregister it (and potentially change whether it is the default).
makeDefault Boolean <optional>
 false

Whether the store should be made the default

removeStore(store) → {Boolean}

Removes a Store from those that a state instance will update

Parameters:
Name Type Description
store module:ol-ishare/store~Store

Store to remove. If the store is the current default, then the next one in the list of stores will become the default. To make a specific store the use setDefaultStore.
Returns:

whether the supplied store was found in the list of stores.

Type
Boolean

setDefaultStore(store) → {Boolean}

Sets a registered store to the default. If not currently registered, nothing will happen.

Parameters:
Name Type Description
store module:ol-ishare/store~Store

The store to make default
Returns:

Whether the store was found and changed to the default

Type
Boolean

get(keys) → {Object}

Get the value(s) for the specified key(s)

Parameters:
Name Type Description
keys Array.<String>

Key or keys to get from state
Returns:

Values for each requested key

Type
Object

set(keyOrDict, valueopt)

Set the value(s) for the specified key(s).

Note that: (a) all values are deep-copied and checked for casting to JSON, and (b) updates to the state are throttled by the options.interval value.

Parameters:
Name Type Attributes Description
keyOrDict String | Object

Key of value to set in state, or key-value pairs.
value * <optional>

If keyOrDict is a string key, this is for the value to set for that key.

reset(keys)

Change the value associated with the keys to those specified in options.defaults. If not set, they will be undefined.

Parameters:
Name Type Description
keys String

Keys to reset

sendToStores() → {Promise}

Sends the current state to all registered stores.

Returns:

Resolves to the keys of values that were successfully stored.

Type
Promise

updateFromStore(storeopt) → {Promise}

Updates state with values from the default Store (or a specified alternative).

Parameters:
Name Type Attributes Description
store module:ol-ishare/store~Store <optional>

Non-default store to use.
Returns:

Promise that resolves to the current state after it has been updated from the store

Type
Promise

override(options) → {Object}

Combines state default values, the passed in options, and the current state

The actual method of combining the options may vary from class to class, but the base class method should be a reasonable default for applications with a single options object

Parameters:
Name Type Description
options Object

Object containing settings used to initialize an application but could be anything - completely appication dependent.
Returns:

Default implementation returns new options object. Sub-classes should return the same types of objects passed as arguments, but definitely return something which makes it possible to pass the updated options to the application in a few steps (ideally one).

Type
Object

(abstract) watch(app)

Start tracking the changes made to the given application.

This will hook into or listen to events or request the settings (or use some other method) from a single instance of an application and set state values accordingly. The implementation will be wholly defined in the sub-class but it must use set to update state and must be able to be undone in stopWatching. Watching an application must not alter how it works in any way and trying to watch a second application must result in stopping watching the first.

Parameters:
Name Type Description
app *

An instance of the application to watch

(abstract) stopWatching()

Stop tracking the changes made to the currently watched application.

After stopping watching an application, the application should be indistinguishable from one that was never watched.

(abstract) apply(app) → {Promise}

Apply the given state to an application already in operation.

Like watch, this will be very application depdendent but is required if updating an application after startup, or updating a second instance of an application from the state of the first, or if not all values from the state can be set during application start.

Parameters:
Name Type Description
app *

An instance of the application to which to apply the current module:ol-ishare/state.State#
Returns:

As applying state might require slow or asynchronous calls, this must return a Promise that resolves to a list of state keys that couldn't be applied to the application instance

Type
Promise

(static) overrideObjects(…objects) → {Object}

Combine multiple objects into a new one in a specified order

This takes the properties of each object in turn and assigns them to a new object. Similar to Object.assign() but with deep copying of properties (i.e. no new).

E.g. if object1, object2, object3 are supplied, then the values of all properties in object2 will override those from the same properties in object1 (or they will be added if they don't already exist). Then the same thing happens with the properties in object3 overriding those from both object1 and object2.

Parameters:
Name Type Attributes Description
objects Object <repeatable>

The objects to combine - least important first
Returns:

A new combined object.

Type
Object