msavin:parrot

v1.1.0Published 8 years ago

This package has not had recent updates. Please investigate it's current state before committing to using it in your project.

Parrot

A New Kind of Router for SPAs

Parrot is a PARameter ROUTer made just for building SPAs using Meteor. It brings state management to a whole new level by letting you store all kinds of data on the URL in a fast and convenient way.

Parrot simplifies route management in the same way that template-level subscriptions simplify data management. The two are a great combination, especially because the parameters are a reactive data source.

An easy way to understand Parrot to think of it as having Session stored on the URL instead of in-memory. Another way to look at it is, as if each URL is a function call. The section refers to the function name, and the parameters are its arguments. The best part is, you can use it however you would like.

1/*____________________________________________________________________
2|                      |                  |                           |
3|  http://meteor.toys  /  #documentation  /  section=Mongol/type=pro  |
4|  Origin              |  Section         |  Parameters               |
5|______________________|__________________|__________________________*/
6
7Router.register({
8    "documentation": function (parameters) {
9        console.log("Person is viewing: " +  parameters.section); 
10        console.log("The version is: " +  parameters.type);
11    }
12});
13
14Router.go("documentation", {
15	section: "Mongol",
16	type: function () {
17		if (Meteor.user().subscriber) {
18			return "pro";
19		} else {
20			return "free";
21		}
22	}
23});
24
25// URL     -> http://meteor.toys/#documentation/section=Mongol/type=pro
26// Output ->  Person is viewing: Mongol
27//            The version is: pro

The code above will route the application from the default of http://meteor.toys/#home to http://meteor.toys/#documentation/section=Mongol/type=pro, and run the appropriate callback.

Parrot works great with Lamma, a layout manage for Meteor-Blaze applications, and a friend of Parrot.

Copy and Paste to Start

Getting started with Parrot is as easy as running:

meteor add msavin:parrot

and then tuning this optional chunk of code on your client:

1Router.init({
2    home: "home",
3    onError: function () {
4        // Display error notice
5        FancyUI.error("404");
6    },
7    onChange: function (newRoute, oldRoute) {
8        Analytics.track(newRoute.name);
9    }
10});

Once you have that set, you can use Router.register() to register routes, as show in the example on top.

If a route is defined, Parrot will run it along with the onChange callback, which can be used to bake in additional guards, tracking, etc. If it is not not registered, Parrot will run on the onError callback, if one is present.

FYI: you can use Parrot just for the set and get functions, and it should stack fine with other routers in this use case.

How To Go Places

With Parrot, you can specify your routes as a string:

1Router.go("documentation/section=Mongol/showMenu=true");

However, in other cases you may want to set the parameters dynamically. To do that, you just pass in each parameter and its value as an object:

1Router.go('documentation', {
2	section: function () {
3		return "introduction";
4	},
5	type: "pro"
6});

Parameter Caching

Parrot caches the parameter values you set under each section. When specifying parameters in Router.go, you can pass the cache into your functions to leverage that value.

1Router.go('documentation', {
2    section: function (cache) {
3        if (cache) {
4            return cache;
5        } else {
6            return "introduction";
7        }
8    },
9    type: "pro"
10});

Parameter caching can be handy for letting your application "remember" where it's user was. For example, if a user navigates to "documentation" in your app, then to "dashboard", and then back to "documentation", you can drop them off exactly where they were, as shown in the example above.

Reactive Key/Value Parameters

Whatever key/value pair you set through on URL will be set as a reactive value in the application, and whatever reactive value you set in the application will be displayed in the URL. It's like a parrot - hah!

1// Set key/value pair just like with Session
2Router.set("section", "Mongol");
3// Turns this: http://meteor.toys/#documentation/section=Mongol
4//       into: http://meteor.toys/#documentation/section=Mongol
5
6// This is a reactive data source powered by ReactiveDict
7Router.get("section");
8// Returns: "Mongol"
9
10// Remove key/value pair
11Router.delete("section");
12// Turns this: http://meteor.toys/#documentation/section=Mongol
13//       into: http://meteor.toys/#documentation

With this approach, it's really easy to control small parts of your application while embracing the full capabilities of browser navigation. A URL can contain like 2000 characters, so you can keep a lot of data there.

Setting Multiple Parameters at Once

Every time you set or remove a parameter, it counts as an entry in the browsers history, and therefore the back-forward navigaton. Thus, when you need to step multiple parameters at once, you might prefer to do so in one shot. Here's how you can do that:

1Router.set({
2    'a':'1',
3    'b':'2'
4}); 
5// URL becomes: http://localhost:3000/#/a=1/b=2
6
7Router.delete(['a','b']); 
8// URL becomes: http://localhost:3000/#/

You can use Parrot for the parameters functionality alone by not using the Router.init function. At that point, it becomes like Session except the key/value pairs are stored on the URL instead of just in memory. With that, you get all the benefits of Session, plus support for reloads, link sharing, and back-forward navigation.

Project State and Intended Use

Parrot is light, stable, and designed to work closely with Meteor. Parrot is designed for single-page web applications. If you are building something that requires indexing, such as a content website, you might prefer something else

Thanks to Moshe Berman for helping with the URL parser!