Guide to Building Views

As outlined in the page building guide, each view is represented by its own module in the src/media/js/view/ directory. For example:

define('views/myview', ['l10n'], function(l10n) {
    var gettext = l10n.gettext;  // Trust me, do this.

    return function(builder) {
        // ...
    };
});

The function returned by the view module is documented thoroughly in the page building guide. This is code that runs when the page is being rendered by the templating engine and processed by the builder. Here are some best practices:

• You should NOT perform ANY delegated event bindings on elements that are not a part of the page. All delegated event bindings on non-page elements should be bound at the module level. This prevents event listener leaks.
• Computationally expensive lookups, queries, and data structures should be done outside of the returned function (at the module level). This ensures that the value is only computed a single time.
• Delegated events should be used whenever possible, and state should be preserved on affected elements (e.g.: via data attributes) rather than in variables.
• State variables should never exist at the module level, unless it represents a persistent state.

Routing

After creating a page, it is installed but not reachable. To make a page accessible, you must create a route in the src/media/js/routes.js file. A route is represented by an object in the routes list.

var routes = window.routes = [
    {'pattern': '^/$', 'view_name': 'hello_world'},

    {'pattern': '^/tests$', 'view_name': 'tests'},
    {'pattern': '^/debug$', 'view_name': 'debug'}
];

Each route object should match the following prototype:

{
  "pattern": "<regexp>",
  "view_name": "<view name>"
}

pattern should represent a regular expression. Allowed RegExp components are documented below.

view_name should represent the name of the view's module.

Routes will be tried in sequence. If no route is found for a URL, Commonplace gives up and navigates the browser to that URL. If a pattern matches, the builder is fired up for the corresponding view.

Acceptable regular expressions

Regular expressions for views are slightly limited. Only the following features may be used:

Groups

Groups are used to match parameters in URLs. These will be replaced when parameters are passed to the second argument of the urls.reverse() method.

Non-matching groups may NOT be used.

Non-repeating optional components

The ? operator may be used in regexps, but only on static elements. The following three scenarios are the only valid uses of ?:

• Optional characters: ^/path/to/view/?$ (optional trailing slash)
• Optional groups: ^/path/to/view(/\w+)?$ *
• Optional character sets: ^/results/[0-9]?$

* Note that optional groups are not evaluated greedily. This means that you may not have multiple optional groups. Instead, create multiple routes pointing to the same view.

? may NOT be used to perform greedy matching.