dojox/mvc/sync¶
Authors: | Akira Sudoh, Ed Chatelain |
---|---|
Developers: | Akira Sudoh, Ed Chatelain |
since: | V1.8 |
dojox/mvc/sync API¶
The module’s value is a sync
function that can be directly called to synchronize two dojo/Stateful properties.
The sync
function is in the form shown below:
sync(source, sourceProp, target, targetProp, options);
The following parameters should be provided to the sync
function:
source
- This is the dojo/Stateful to get one of its properties, or its all properties, to be in sync.sourceProp
- This is the dojo/Stateful property name insource
, or*
. Using*
means to get all properties in sync. (See Wildcard syntax section fore more details)target
- This is the dojo/Stateful to get one of its properties, or its all properties, to be in sync.targetProp
- This is the dojo/Stateful property name intarget
, or*
. Using*
means to get all properties in sync. (See Wildcard syntax section fore more details)options
- The optional list of options. (See Data binding direction section and Data converter section for more details)
The basic usage can be seen in the example below, where target.foo
will become “fooValue0” as soon as sync
function is called (as it’s copied from source.foo
), and source.foo
will become “fooValue1” as soon as “fooValue1” is set to target.foo
:
require(["dojo/Stateful", "dojox/mvc/sync"], function(Stateful, sync){
var source = new Stateful({foo: "fooValue0"}),
target = new Stateful();
sync(source, "foo", target, "foo"); // Start synchronization between source.foo and target.foo
alert(target.get("foo"));
target.set("foo", "fooValue1"); // This change is reflected to source.foo, too, as source.foo is in sync with target.foo by sync function
alert(source.get("foo"));
});
sync
function returns a handle that allows stopping synchronization at some point in the future. For example:
require(["dojo/Stateful", "dojox/mvc/sync"], function(Stateful, sync){
var source = new Stateful({foo: "fooValue0"}),
target = new Stateful();
var handle = sync(source, "foo", target, "foo"); // Start synchronization between source.foo and target.foo
alert(target.get("foo"));
handle.remove(); // Stop synchronization between source.foo and target.foo
target.set("foo", "fooValue1");
alert(source.get("foo")); // Still "fooValue0" as synchronization had been stopped before "fooValue1" is set to target.foo
});
Wildcard syntax¶
When sourceProp
and targetProp
are *
, sync
function tries to synchronize all properties in source
/target
. The list of properties are determined by the following way:
- If
target.get("properties")
is there, use it. Otherwisesync
function enumerates properties intarget
, except_watchCallbacks
function. - If
target.get("excludes")
is there,sync
function removes the property names in it, from above list. - If
source.get("properties")
is there,sync
function removes the property names that are not in it, from above list.
Data binding direction¶
By default, sync
function watches for changes both at target.targetProp
and source.sourceProp
and reflects one change to another. sync
function allows to specify the direction via options.bindDirection
, which are:
sync.from
- Only reflect changes insource.sourceProp
totarget.targetProp
sync.to
- Only reflect changes intarget.targetProp
tosource.sourceProp
sync.both
- Reflect changes in each other (Default)
The basic usage of data binding direction can be seen in the example below, where change in source.foo
is reflected to target.foo
, but not the other way around:
require(["dojo/Stateful", "dojox/mvc/sync"], function(Stateful, sync){
var source = new Stateful({foo: "fooValue0"}),
target = new Stateful();
sync(source, "foo", target, "foo", {bindDirection: sync.from}); // Start one-way synchronization from source.foo to target.foo
alert(target.get("foo"));
source.set("foo", "fooValue1"); // This change is reflected to target.foo, too, as target.foo reflects the change in source.foo by sync function
alert(target.get("foo"));
target.set("foo", "fooValue2"); // This change won't be reflect to source.foo, as the data binding is only from source.foo to target.foo, not the other way around
alert(source.get("foo")); // source.foo still is "fooValue1"
});
Data converter¶
sync
function allows source.sourceProp
and target.targetProp
to have different format as they are synchronized, for example, source.soureProp
to have String "2"
and target.targetProp
to have Number 2
. It’s done by specifying options.converter
, which has some interface compatibility with dojo/number
, dojo/date/locale
, etc., so that those libraries can be used directly as the converter, by having the following properties:
format
- A function that convertssource.sourceProp
totarget.targetProp
. When an error is thrown here,target.targetProp
won’t be set. It has optional 2nd parameter (options
), which is passed in ifconstraints
property exists insource
ortarget
passed intosync
function.parse
- A function that convertstarget.targetProp
tosource.sourceProp
. When an error is thrown here,source.sourceProp
won’t be set. It has optional 2nd parameter (options
), which is passed in ifconstraints
property exists insource
ortarget
passed intosync
function.
The basic usage of options.converter
is shown below:
sync(source, sourceProp, target, targetProp, {
converter: {
format: function(value){
return "" + value; // Simple conversion from number to string
},
parse: function(value){
return value - 0; // Simple conversion from string to number
}
}
});
An example of using dojo/date/locale
as data converter is shown below:
require(["dojo/Stateful", "dojo/date/locale", "dojox/mvc/sync"], function(Stateful, dateLocale, sync){
var source = new Stateful({date: new Date(1970, 0, 1, 0, 0, 0, 0)}),
target = new Stateful();
sync(source, "date", target, "date", {converter: dateLocale}); // Start synchronization between source.date and target.date
alert(target.get("date")); // target shows formatted date
source.set("date", new Date()); // This change is reflected to target.date, target.date will be formatted version of newer date
alert(target.get("date"));
});