map
can.route.mapAssign a can.Map instance that acts as can.route's internal can.Map. The purpose for this is to cross-bind a top level state object (Application State) to the can.route.
can.route.map(mapConstructor)
Parameters
-
mapConstructor
{can.Map}
A can.Map constructor function. A new can.Map instance will be created and used as the can.Map internal to can.route.
can.route.map(mapInstance)
Parameters
-
mapInstance
{can.Map}
A can.Map instance, used as the can.Map internal to can.route.
Use
One of the biggest challenges in a complex application is getting all the different parts of the app to talk to each other simply, cleanly, and reliably.
An elegant way to solve this problem is using the Observer Pattern. A single object, which can be called Application State, holds the high level state of the application.
Here is a video explaining how this pattern can be used in an application.
CanJS recommends using an Application State object in your application. There are benefits to making this state object mirror the routing in your application.
can.route
already contains an internal can.Map instance, which is serialized into the hash (or pushstate URLs).can.route.map
provides an easy to way make your Application State object cross-bound tocan.route
.The Application State object, which is cross-bound to the can.route via
can.route.map
and represents the overall state of the application, has several obvious uses:When to call it
Its important to call
can.route.map
at the very start of your application's lifecycle, before any calls tocan.route.bind
. This is becausecan.route.map
creates a new internalcan.Map
, replacing the default one, so this order is important to ensure you're binding to the correct Map.Basic Example
A basic example of an Application State for a reporting application, is shown below:
This object would then be passed into the can.Controls or can.Components that make up the building blocks of this application. Via can.route, the URL in the page would mirror the current state of the app.
Demo
The following shows creating an appState that loads data at page load, has a virtual property 'locationIds' which serializes an array, and synchronizes the appState to can.route:
Using arrays and can.Lists
If the Application State contains a property which is any non-primitive type, its useful to use the [can.Map.define] plugin to define how that property will serialize.
can.route
calls can.Map.prototype.serialize internally to turn the Application State object into URL params.The following example shows a flags property, which is an array of string-based flags:
Loading data on application start
Applications commonly require loading some metadata on page load, which must be loaded as part of the Application State before the components can be initialized.
To implement this functionality:
can.Map
constructorcan.route.map
with this objectcan.route.ready
, to initialize can.route and begin firing event handlers bound to can.routeThe following example shows a locations property, which contains a list of location
can.Map
's loaded at page load. As users select a location, its selected property is toggled.A locationIds property is defined, which is the serialized version of location. A setter is defined on locationIds, which will translate changes in locationIds back to the true source of the data in locations.