Nebulous Puffy Marshmallows
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    properjs-pagecontrollerpublic

    PageController

    A lightweight, modern javascript router.

    Installation

    npm install properjs-pagecontroller --save-dev

    About

    PageController is a simple javascript router that utilizes an intelligent module pattern tied to the request lifecycle of pages in your webapp. It uses XHR and History and has support for Hash state as well. PageController is powerful because its a wrapper around Router which includes PushState, a small History management utility.

    Usage

    For the usage example lets assume you have a module called router in your webapp that will work with PageController. For a full example of a working router module you can check this one out here.

    Assume the router module has more going on, but this shows how to initialize PageController. By default, PageController does not do anything. You have to configure it first and then call the initPage method to turn it on. Here's the setup process.

    Instantiate

    You can view more on routerOptions here.

    this.controller = new PageController({
        // Transition duration for page animations in milliseconds. 
        // The default transition-time is 0 to just handle the request cycle. 
        // Why have this? If you want nice transitions you'll use it. 
        // Say your request is fast, like 10ms or whatever, this will ensure 
        // that your transitionTime is still honored allowing exit/intro animations. 
        transitionTime: 400,
     
        // Router options 
        routerOptions: {}
    });

    Configure routes

    You can view more on route configuration here.

    this.controller.setConfig([
        "/",
        ":view",
        ":view/:uid"
    ]);

    Apply modules

    You can see a full example of a basic PageController compatible module here. There are three required methods a module must have in order for PageController to work with it:

    • onload
    • unload
    • isActive

    You can optionally give your module and init method and it will be called once as part of the page-controller-initialized-page event cycle. There are some other module patterns that tend to make sense. I prefer giving my modules a teardown method that the unload method calls. This allows you to manually unload a module outside of the PageController lifecycle in your webapp if need be. I also like a setup method designed to work alongside the isActive method.

    // Assume we have this in our app 
    import view from "./views";
     
    this.controller.setModules([
        views
    ]);

    Here's a high-level look at how a module can use those patterns.

    const views = {
        // Optional, called once when PageController is initialized 
        init () {},
     
        // Reset variables/properties and query the DOM 
        setup () {
            this.views = {};
            this.elements = core.dom.main.find( ".js-view" );
        },
     
        // Your view is active so you can work with the DOM 
        onload () {
            this.elements.forEach(( element, i ) => {
                this.loadView( this.elements.eq( i ) );
            });
        },
     
        // Your view is inactive so reset variables/properties 
        unload () {
            this.teardown();
        },
     
        // Reset variables/properties 
        teardown () {
            this.views = {};
            this.elements = null;
        },
     
        // Query DOM and determine if this module should load 
        isActive () {
            this.setup();
     
            return (this.elements.length > 0);
        },
     
        // Any unique methods relevant to your module... 
     
        loadView ( element ) {
            const data = element.data();
     
            this.views[ data.uid ] = new View({
                id: data.uid,
                el: element,
                url: data.api
            });
        }
    };

    Handle events

    These are the most critical events to work with when using PageController. The router lifecycle has 3 hooks — transition out, refresh document state, transition in. A one-time initialization event is fired after you call initPage. You can view examples of using these router events here.

    initPage

    this.controller.on( "page-controller-initialized-page", this.initPage.bind( this ) );

    changePageOut

    this.controller.on( "page-controller-router-transition-out", this.changePageOut.bind( this ) );

    changeContent

    this.controller.on( "page-controller-router-refresh-document", this.changeContent.bind( this ) );

    changePageIn

    this.controller.on( "page-controller-router-transition-in", this.changePageIn.bind( this ) );

    Start router

    You have to manually call the initPage method in order for PageController to do anything with your webapp.

    this.controller.initPage();

    Events

    These are all the events PageController fires.

    • page-controller-router-samepage
    • page-controller-router-synced-modules
    • page-controller-router-refresh-document
    • page-controller-router-transition-out
    • page-controller-router-transition-in
    • page-controller-initialized-page

    Methods

    These are all the available methods your PageController instance has. You can take advantage of access to the core Router and PushState instances. Say you want to manually trigger a route? You can do something like this:

    this.controller.getRouter().trigger( path );

    install

    npm i properjs-pagecontroller

    Downloadsweekly downloads

    40

    version

    0.4.3

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar