rebel-router

 

A lightweight JavaScript router written for ultra-modern web applications where web components are first class citizens. Rebel-router is designed to make building modern applications using ES2015 and beyond easier while not tying you into a specific framework or technology stack. Rebel-router allows you to write web components to represent your views so you can make full use of the view controller pattern based on nothing more than browser standards.

 

Note: Currently this is very much a work in progress. I'm working hard to add more desirable features such as History API support and getting the router field testing in real world applications.

##Features

• Light-weight
• Zero dependencies
• Nested routes
• Animation support
• Built on web components

##Examples

• Getting started tutorial
• Accessing route parameters
• Using nested routing
• Using animations
• Complete demo

##Platform Support

While some browsers do not support the full specification for web components you will need to include the webcomponents.js pollyfill.

Latest*	Latest	Latest	IE 11	Latest	Latest*
*Includes both Mobile & Desktop versions.

#Why?

The latest features of JavaScript (ES2015-17) provide solutions to problems web developers have been struggling with for years. This includes native support for modules, true encapsulation with web components and a reliance on monolithic frameworks to really build anything scalable. Rebel-router allows the developer to write web components which represent views and provides an easy way to tie these views to a URL path with easy access to any parameters. This provides some flexible structure in writing vanilla JavaScript applications without frameworks.

#Getting started

Rebel-router is designed to be used when building applications using the latest version of JavaScript and will need transpiling down to ES5 using babel or similar.

1. Install rebel-router into your project from npm

npm install rebel-router

1. Create your views as web components

#home.js
export class HomePage extends HTMLElement {
    createdCallback() {
        this.template = `<p>This is my home page.</p>`;
    }
    attachedCallback() {
        this.render();
    }
    render() {
        this.innerHTML = this.template;
    }
}

document.registerElement("home-page", HomePage);

#about.js
export class AboutPage extends HTMLElement {
    createdCallback() {
        this.template = `<p>This is my about page.</p>`;
    }
    attachedCallback() {
        this.render();
    }
    render() {
        this.innerHTML = this.template;
    }
}
document.registerElement("about-page", AboutPage);

1. Import your views into your main application file to register the elements.

#app.js
import {HomePage} from './home.js';
import {AboutPage} from './about.js';

1. Add the router and specify configuration in your HTML file

    <rebel-router animation="true" shadow="false" inherit="false">
        <route path="/about" component="about-page"></route>
        <route path="/info"><p>This is a simple info page.</p></route>
        <default component="home-page"></default>
    </rebel-router>

A simple tutorial on how to get started with rebel-router can be found here.

#Usage

This section of the document details the API for rebel-router.

##<rebel-router></rebel-router>

This element is used to insert a pre-configured router instance into the DOM.

###Attributes

Attribute Name	Required	Type	Example	Default	Comments
animation	No	Boolean	true	false	Whether or not to enable animation for route transitions.
shadow	No	Boolean	false	false	Whether or not the router should be encapsulated within the shadow DOM.
inherit	No	Boolean	false	true	Whether or not the router should inherit a parent routes path.

###Children

Configuration is specified via child elements of <rebel-router>.

###<route></route>

####Attributes

Attribute Name	Required	Type	Example	Comments
path	Yes	String	/user/{id}	The path to which the specified template or component should be rendered.
component	No	String	about-page	The registered element name of the component to be rendered for the specified path.

####Children

If you do not wish to use a component to render your view for the specified path you are able to add arbitrary HTML to be used as the template.

###<default></default>

###Attributes

Attribute Name	Required	Type	Example	Comments
component	No	String	home-page	The registered element name of the component to be rendered for the specified path.

####Children

As with the route element you are also able to add arbitrary HTML to be used as the template.

###Example

<rebel-router animation="true" shadow="false" inherit="false">
    <route path="/info" component="info-page"></route>
    <route path="/resources/{resource}" component="resources-list"></route>
    <route path="/resource/people/{id}" component="people-resource"></route>
    <route path="/resource/starships/{id}" component="starships-resource"></route>
    <route path="/resource/vehicles/{id}" component="vehicles-resource"></route>
    <route path="/resource/species/{id}" component="species-resource"></route>
    <route path="/resource/planets/{id}" component="planets-resource"></route>
    <route path="/test/{id}">
        <p>This is a simple page template which can access the route params: ${id}.</p>
    </route>
    <default component="home-page"></default>
</rebel-router>

##<rebel-back-a></rebel-back-a>

An extended HTML anchor element which is used to trigger a back animation for router instances which have animation enabled.

###Attributes

Attribute Name	Required	Type	Example	Comments
href	Yes	String	#/users	The path of the route the anchor element should navigate too.

###Example

    <a href="#/user/1" is="rebel-back-a"><span class="icon icon-arrow-left2"></span> Back</a>

#To Do

• History API Support - Where as I've not yet found any real need for this this router is aimed at ultra-modern applications now that the History API is widely supported this will be one of the next features added
• Intercept transition - A nice feature of many routers is the ability to do work and resolve when finished before a route transition completes allowing you to set-up data from the next page
• Write a comprehensive test suite to test all aspects of rebel-router and associated elements