express-routes-dispatcher v2.2.1

JSON based routing for Node.js

JSON based MVC routing using express and twig as template engine.

In this implementation, the routing is based on JSON format, which is a map from an URL path to a controller (Controller) for processing the request, apply it to data (Model) and finally to a template for visualization a result (View).

The format is similar to the syntax of Symfony YAML based Routing.

1. Installation
2. Usage
3. Class Router
4. Writing routes
5. Writing controllers
6. Writing templates
7. Demo
8. Tests
9. License

Installation

$ npm install express-routes-dispatcher --save

or

$ yarn add express-routes-dispatcher

Usage

The Router allows you to organize simple and clear MVC-architecture in your Node.js application. Structure of directories can be the next:

app/                          // Application root.
 ├─ modules/                  // The directory containing folders of modules.
 │   ├─ Users/                // Module "Users"
 │   │   ├─ controllers/      // Controllers of the module.
 │   │   ├─ models/           // Models of the module.
 │   │   ├─ views/            // Templates such as pages, partials or blocks (BEM) of the module.
 │   │   └─ routing.js        // Routing of the module.
 │   └─ •••                   // Other modules.
 ├─ views/                    // Common templates such as static pages, partials or blocks (BEM).
 ├─ config.js                 // Config file.
 ├─ index.js                  // The entry point of the application.
 └─ routes.js                 // Base routing file. Includes common static pages and routing files of modules.

The entry point of the application is index.js. It processes all HTTP-requests.

File routes.js describes the URLs, controllers for processing requests by this URLs and templates to returning response data by the controller.

See the example of application.

Class Router

The main class allowing to create and to start router of your application.

Constructor

new Router(routes, options) returns instance of the Router.

import Router from 'express-routes-dispatcher';
import routes from 'routes.js';

const router = new Router(routes);

Methods

start(cb) starts and returns instance of Node.js server. Use this instance to stop server by method close().

Function cb will be called after successful starting.

const server = router.start(({ host, port, protocol }) => {
    console.log(`Server on ${protocol}://${host}:${port} was started.`);
}); // -> "Server on http://localhost:3000 was started."

close(cb) stops server.

const server = router.start();

/* ... */

server.close(({ host, port, protocol }) => {
    console.log(`Server on ${protocol}://${host}:${port} was stoped.`);
}); // -> "Server on http://localhost:3000 was stoped."

Writing routes

A routes map is an object with routes names as keys and object of routes descriptions as values.

Formal syntax

/* Inline routing description */

{
    <route name>: {
        path: <URL>,

        controller: <a path to the controller function>,
        defaults: {
            _format: <the format of a response>,
            _template: <a path to the template>,
            <pairs 'key-value' to define default values of parameters from the path>,
        },
        methods: <an array of allowed methods for requests>,
        requirements: {
            <pairs 'key-value' to define requirements for values of parameters from the path>,
        },
    },
    ...
}

<route name> is a string. It should be unique, otherwise, a last declared route with the same name will override earlier ones.

/* External routing description */

{
    <routes branch name>: {
        resource: <a path to the file of external routing description>,

        prefix: <prefix for parameter 'path' of plugged routes>,
    },
    ...
}

<routes branch name> is a string. It should be also unique.

Writing controllers

Controller is a function which accepts as a parameter the object request and returns data object. This data will be able in the template.

Example

/* controller.js */

module.exports = (request) => {
    const { params: { id } } = request;

    return {
        data: {
            id: id,
        },
    };
};

{# index.twig #}

<p>Parameter "id" from URL is {{ data.id }}</p>

Writing templates

Twig is a powerful template engine. More about it you can read in official documentation.

For all templates are available some global variables and functions.

Twig constants

__route is an object which contains parameters of the current route.

Example:

{% if (__route.name == 'main') %}
    <span>Main page</span>
{% else %}
    <a href="{{ path('main') }}">Main page</a>
{% endif %}

Twig tags

render is a tag which can render a controller inside another one.

Syntax:

{% render <controller> with <params> %}

Example:

{# views/index.twig #}

<h1>Page template</h1>

{% render 'controller/partials' with {
    template: 'views/partials.twig',
}) %}

/* controller/partials.js */

module.exports = () => {
    return {
        data: {
            foo: 'baz',
        },
    };
};

{# views/partials.twig #}

<h2>Partials template</h2>

<p>foo: {{ data.foo }}</p>

In final HTML document we will get:

<h1>Page template</h1>

<h2>Partials template</h2>

<p>foo: baz</p>

Twig functions

path(name, options) is a function returns a generated URL by route name. Accepted parameters:

Example:

/* routes.js */

module.exports = {
    profile: {
        path: '/users/profile/{id}/',
    },
};

{# views/pages/index.twig #}

<a href="{{ path('profile', {
    hash: 'name',
    params: {
        id: '1a2s564ws',
    },
    query: {
        tab: 'info',
    },
}) }}">My profile</a>

In a browser you'll see:

<a href="/users/profile/1a2s564ws/?tab=info#info">My profile</a>

Demo

You can try it on the example application. To launch:

$ git clone https://github.com/ahtohbi4/express-routes-dispatcher.git
$ cd express-routes-dispatcher
$ yarn install
$ yarn start

Then open http://localhost:3000 in your favorite browser.

:warning: The demo application uses CSS Grid Layout.

Tests

$ git clone https://github.com/ahtohbi4/express-routes-dispatcher.git
$ cd express-routes-dispatcher
$ yarn install
$ yarn test

License

MIT © Alexander Antonov alexandr-post@yandex.ru