ChangeApplier API

which transfers all the state from newModel onto model - whilst still preserving the identity of model as model - and hence its association with any particular ChangeApplier. These two calls, clear followed by copyModel often occur together (and will be automated in a future version of the ChangeApplier).

After its construction, the particular model object to which a ChangeApplier is bound is available at applier.model.

New in v1.3:
Version 1.3 of Infusion includes a Sneak Peek view of our new transactional ChangeApplier. The ChangeApplier supports transactions by default, and can be configuring using an optional options parameter:


var applier = fluid.makeChangeApplier(model, options);

For more information see the fluid:Transactional ChangeApplier section below.

Firing a change using a ChangeApplier

There are two calls which can be used to fire a change request - one informal, using immediate arguments, and a more formal method which constructs a concrete ChangeRequest object.


applier.requestChange(path, value, type)

Parameter	Type	Description

Parameter	Type	Description
`path`	`string`	An EL path into the model where the change is to occur.
`value`	`object`	An object which is to be either updated (or added if necessary), or removed from the model at path `path`
`type`	(optional) `"ADD"` or `"DELETE"`	A key string indicating whether this is an ADD request (the default) or a DELETE request (a request to unlink a part of the model)


applier.fireChangeRequest(changeRequest)

requestChange and fireChangeRequest reach exactly the same implementation - the only difference is in the packaging of the arguments. For requestChange they are spread out as a sequence of 3 arguments, whereas for fireChangeRequest, they are packaged up as named fields (path, value and type) of a plain Javascript object. Such an object is called a "ChangeRequest" and is a convenient package for these requests to pass around in in an event pipeline.

Registering interest in a ChangeApplier

Currently ChangeAppliers support two types of listeners (to be expanded).

Guard Listeners.

The first type, called guard listeners, are notified of an upcoming change request before it occurs. Guards can be registered and deregistered at the path guards with a call to addListener:


applier.guards.addListener(pathSpec, guard, namespace)

Parameter	Type	Description

Parameter

Type

Description

pathSpec

v1.2 and earlier:
string
New in v1.3:
string or Object

An EL expression, possibly with wildcards (* in place of a path component) which matches the set of EL paths, which on receiving a change request, will trigger this guard.

New in v1.3:
The pathSpec can also be an Object with the following properties:

{
    path: an EL expression
    priority: an integer
    transactional: boolean  (see Transactional Listeners below)
}

The priority will affect when the listener is fired: All listeners will be sorted according to priority and fired in order. A higher number implies a higher priority. The default if unspecified will be the highest possible priority.

guard

function

A function pointer holding a guard

namespace

string

(Optional) - a namespace key, which is used to scope additions and removals of this guard (see Infusion Event System for interpretation of event namespaces)

A guard may be removed with a call to


applier.guards.removeListener(guard)

where guard holds either the original function reference, or else the string value supplied as the namespace.

A guard listener is just a function with a particular signature - for example, guard could be implemented as follows:


function guard(model, changeRequest) {
    if (changeRequest.value === null) {
        return false;
        }
    }
}

The behaviour of this guard is to reject any incoming change which would appy a null value to the model - by making a false return, the entire change cycle which triggered it would be cancelled, since guards have the semantics of preventable events (see Infusion Event System for the different event categories).

The arguments supplied to a guard are as follows:

Parameter	Description

Parameter	Description
model	The overall model attached to the ChangeApplier with which this guard is registered
changeRequest	The ChangeRequest object with which this request was started

modelChanged listeners

Registration and deregistration of modelChanged listeners is just as for guards -


applier.modelChanged.addListener(pathSpec, listener, namespace)
applier.modelChanged.removeListener(listener)

The signature and timing of the listener is different to guards. Unlike a guard, the listener is notified after the change has already been applied to the model - it is too late to affect this process and so this event is not preventable. The signature for these listeners is


function listener(model, oldModel, changeRequest)

Parameter	Description

Parameter	Description
model	The overal model attached to the ChangeApplier with which this listener is registered
oldModel	A "snapshot" of the previous model condition - created as if by `fluid.copyModel`.
changeRequest	The ChangeRequest object with which this request was started