README

Views Middleware for Pinecone Router

A views middleware for Pinecone Router.

About

Views middleware for Pinecone Router. Allows you to set the path for a view and it'll be fetched and displayed in the specified element.

Installation

CDN

Include the following <script> tag in the <head> of your document, before Pinecone Router:

<script src="https://cdn.jsdelivr.net/npm/pinecone-router-views@1.x.x/dist/index.umd.js"></script>

ES6 Module:

import 'https://cdn.jsdelivr.net/npm/pinecone-router-middleware-views@1.x.x/dist/index.umd.js';

NPM

npm install pinecone-router-middleware-views

// load this middleware
import 'pinecone-router-middleware-views';
// then load pinecone router
import 'pinecone-router';

Important: This must be added before loading Pinecone Router.

Usage

Demo

Enable views middleware in the router Settings:

function router() {
    return {
        settings: {
            middlewares: {
                views: {
                    enable: true;
                }
            }
        }
    }

add x-view to the routes with the value being the path to view.

That's it!

example:

<div x-data="router()" x-router>
    <template x-route="/" x-view="/home.html"></template>
    <template x-route="/hello/:name" x-view="/hello.html"></template>
    <template x-route="notfound" x-view="/404.html"></template>
</div>

<div id="app">this will be replaced by the content of the views.</div>

function router() {
    return {
        settings: {
            middlewares: {
                views: {
                    enable: true;
                }
            }
        }
    }
}

Notes: :

Routes can share views.
View are simply html files, can be text files too.
You can set the selector in settings. leaving it empty will default to '#app'
You can also handle routes while using views
- Note: The handlers will be executed before the view is loaded.

Settings

views: {
    enable: true,
    basePath: '/',
    selector: '#app',
}

Authorization

If you'd like to make checks before actually displaying a view, using authentication/authorization etc, you can make your checks in the handler. Then within the handler, if you need to redirect the user to another page simply return context.redirect('/another/page') this way it'll prevent the views from rendering and go to the other page directly.

Example:

The route you'd like to authorize: In this example the user will only be allowed to edit their own profile

<div x-data="router()" x-router>
    ...
    <template
        x-route="/profile/:username/edit"
        x-handler="editProfile"
        x-view="/editprofile.html"
    ></template>
    <template x-route="/unauthorized" x-view="/unauthorized.html"></template>
    ...
</div>

The handler

auth is a placeholder name, replace it with your own auth provider methods

editProfile(context) {
    if (context.params.username != auth.username) {
        return context.redirect('/unauthorized');
    }
}

Tip! To access the current context (params etc) from within the views, use the $router Magic Helper from an Alpine component or window.PineconeRouter.currentContext from Javascript.

Important: Make sure the view don't have an Alpine Router component in them! Keep the router component outside of the specified selector.

Can't use body as the selector to avoid that issue.

Events:

This middleware dispatch these events:

name	recipient	when is it dispatched
pinecone-start	window	when the page start loading
pinecone-end	window	when the page loading ends
fetch-error	x-router	when the fetch fail

The first two can be used to show a loading bar or indicator

Loading bar Example:

Using nProgress (Recommended):

window.addEventListener('pinecone-start', () => nProgress.start());
window.addEventListener('pinecone-end', () => nProgress.done());

You can also implement your own by doing something like this:

<div
    x-data="{show:true}"
    @pinecone-end.window="show=false"
    @pinecone-start.window="setTimeout(()=>show=true, 100)"
    x-show="show"
>
    style it as you wish.
</div>

Supported versions

Version	Pinecone Router Versions
1.x.x	^1.0.0

Contributing:

Please refer to CONTRIBUTING.md

Versioning

This projects follow the Semantic Versioning guidelines.

License

Licensed under the MIT license, see LICENSE.md for details.

Usage no npm install needed!