Docs
Everything You Need to Know
Router
Use
ChocolateChip-UI's router enables you to capture the user's interaction with ChocolateChip-UI's various navigations schemes. These are three: navigation lists, slide out menus and tab bars.
Getting Started
To use routes you first need to initialize a router:
var routes = new Router();
You can then add a route to handle:
routes.addRoute({
route: 'detailScreen',
callback: () => {
// Do stuff when entering "detailScreen"
}
})
Passing a Parameter to a Route
When setting up your navigation lists, slide out menus and tab bars, you can provide a parameter that can be captured by the route callback to do something specific based on its value. This allows you to have, for example, a navigation list where all the list items go to the same page. The route for that page takes the provided parameter of each list item and renders content based on that parameter value. You can use a unique property, an id or uuid or whatever to identify each object in the collection to use as route parameters. You use a semi-colon, :, after the route to separate the parameter from the route. Below is a navigation list item with a uuid as a parameter of the route. Notice how the parameter is seprated from the route by the semi-colon:
<li data-goto="detail:N356f953-2c3c-4a72-b4e7-5955662ec80f">
The semi-colon tells the router that what follows is a route parameter. When the user taps such a list item, the router separates the parameter from the route and lets you capture it in your route's callback.
addRoute
If you have a single route, pass it as a single object. If you have more than one route, pass them as additional arguments, separated by commas:
routes.addRoute({
route: 'main',
callback: () => {
// Do stuff when entering "main"
}
},
{
route: 'detailScreen',
callback: () => {
// Do stuff when entering "detailScreen"
}
})
Below is an example of how to capture a route parameter in the callback. Notice the id parameter in the callback's function. That will be the parameter captured from the route value. In this examle we're passing a single object inside an array as the argument for addRoute. Because it's single, you could pass it as a plain object without the enclosing array. However, if you want to pass in multiple routes to handle, they do need to be enclosed in an array.
const routes = new Router();
routes.addRoute({
route: 'detail',
callback: (param) => {
// Filter model with param passed in route.
// We use "[0]" at the end to extract the object from the array:
const whichPerson = peopleState.filter((person) => person.uuid === param)[0];
// Output peron's name:
$('#chosenPerson').text('Welcome, ' + whichPerson.firstName + '.');
}
});
If you have a single destination and you want to render it differently based on the route parameter, you probably want to use a switch state to do so. In the following example, based on whether the id is 'music', 'pictures', etc., we use a different template and data set to render in the container '#myList' when the user navigates to the 'choice' screen:
routes.addRoute({
// The route:
route: 'choice',
// Callback to handle passed param:
callback: (param) => {
// Method to rener templates in switch statement:
const renderChosenTemplate = (element, template, item) => {
listView.setTemplate(template);
listView.setElement(element);
listView.render(item);
};
// Handle passed param:
switch (param) {
case 'music':
renderChosenTemplate('#myList', templates[0], music)
break
case 'pictures':
renderChosenTemplate('#gridOfImages', templates[1], imageCollection)
break
case 'documents':
renderChosenTemplate('#myList', templates[2], docs)
break
case 'recipes':
renderChosenTemplate('#myList', templates[3], recipes)
break
case 'favorites':
renderChosenTemplate('#myList', templates[4], favorites)
break
}
}
})
Take a look at the example source code for slide-out-menu-routes.html in the ChocolateChip-UI examples. Read for how to get the examples.
Digging deeper
Navigation lists automatically dispatch a route when the user taps on a list item. Where does it get the route? From the data-goto value you use to indicate where that list item goes to. Similarly, silde out menus use the data-show property. And tab bars use data-id. Because setting up each type of layout is different, it will be easier to open the examples provided in the source code. You want to look at the following examples depending on what type of layout you wish to create:
- navigation-routes.html
- slide-out-menu-routes.html
- tabbar-nav-routes.html
You can find these in the examples folder created from the command line as mentioned previously. Please read Install.