@benbraide/inlinejs-router

InlineJS Router Plugin

This is a plugin for the InlineJS Framework, enabling client side routing.

📢 Routing supports transitions and animations on data load.

Install

• Grab source or distribution versions from GitHub
• Include script in your HTML file.

CDNs

<script  src="https://cdn.jsdelivr.net/npm/@benbraide/inlinejs-router@1.x.x/dist/inlinejs-router.js"></script>

<script  src="https://cdn.jsdelivr.net/npm/@benbraide/inlinejs-router@1.x.x/dist/inlinejs-router.min.js"></script>

NPM Install

npm install @benbraide/inlinejs-router

Reference

Available directives:

Directive	Description
x-router	Used as the base directive for other extensions.

Available directive extensions:

Extension	Description
page	Registers a path as a new page.
fetch	Registers a fetch handler for a specific path or pattern.
mount	Directs the router concept where to render fetched data.
link	Binds an a or form element as a link to activate a path.

Available events:

Event	Description
load	Fired when a page has been loaded.
reload	Fired when the specified path is the same as the previous path and reload option is not set.
error	Fired when an error occurs while retrieving data for a loading page.
404	Fired when the specified path does not match any of the registered pages.
entered	Fired when a page load is initiated.
page	Fired when the processed path points to a new page.
path	Fired when the specified path is different from the previous one.

Example:

<template x-router:load="console.log('Page details:', $event.detail)"></template>

These events can also be subscribed to using the x-on core directive. Example: <template x-on:router-load.join.window="..."></template> Note: These events are fired on the global window object. That is why the x-on example above includes a .window modifier.

Available mount events:

Event	Description
load	Fired when the data is swapped
reload	Fired when data is swapped, but the path is the same as the previous one.
entered	Fired when a data swapping is initiated.

Example:

<template x-router:mount-load="console.log('Load details:', $event.detail)"></template>

These events can also be subscribed to using the x-on core directive. Example: <template x-on:router-mount-load.join="..."></template> Note: These events are preceded by a mount-.

Available magic properties:

Property	Description
$router	Exposes methods used for interacting with the router concept.

Directives

---

x-router

x-router Used as the base directive for other extensions. By itself it does nothing.

Directive Extensions

---

page

x-router:page Registers a path as a new page.

Notes:

• Pages must be registered before they can be requested/visited.
• Registered page is removed when element with directive is removed from the DOM.

Examples:

• Specifying a static path:

<template x-router:page="/about"></template>

• Specifying a pattern path:

<template x-router:page.evaluate="/^\/cust.*/"></template>

• Specifying a register object:

<template x-router:page.evaluate="{ path: '/about', name: 'about', title: 'About Us', cache: true, reload: false }"></template>

Note: The only required property of the register object is the path.

• Specifying a path that should be cached:

<template x-router:page.cache="/about"></template>

• Specifying a path that should always be reloaded:

<template x-router:page.reload="/fragile"></template>

fetch

x-router:fetch Registers a fetch handler for a specific path or pattern.

Examples:

• Using the innerHtml content as data:

<template x-router:fetch="/about">
    <p>This page is about a service.</p>
</template>

• Using the innerHtml content as data with placeholders:

<template x-router:fetch="/users/:id">
    <p>Specified user has an ID of {: $params.id :}.</p>
</template>

• Using the innerHtml content as data with optional placeholders:

<template x-router:fetch="/users/:id?">
    <p>Specified user has an ID of {: $params.id || 'Nil' :}.</p>
</template>

• Using the innerHtml content as data with typed placeholders:

<template x-router:fetch="/users/:id:integer">
    <p>Specified user has an ID of {: $params.id :}.</p>
</template>

• Using callback as data:

<template x-router:fetch.evaluate="{ path: '/about', handler: () => '<p>This page is about a service.</p>' }"></template>

• Using callback as data with placeholders:

<template x-router:fetch.evaluate="{ path: '/users/:id', handler: ({ params }) => `<p>Specified user has an ID of ${params.id}.</p>` }"></template>

• Using callback as data with optional placeholders:

<template x-router:fetch.evaluate="{ path: '/users/:id?', handler: ({ params }) => `<p>Specified user has an ID of ${params.id || 'Nil'}.</p>` }"></template>

• Intercepting all requests:

<template x-router:fetch.evaluate="() => '<p>Handling all requests</p>'"></template>

mount

x-router:mount Directs the router concept where to render fetched data.

Examples:

• Specifying the default mount point:

<template x-router:mount></template>

• Specifying a mount point for a specific "protocol":

<template x-router:mount="modal"></template>

• Specifying a different DOM element as mount point:

<template x-router:mount.evaluate="document.querySelector('#router-mount')"></template>

• Specifying a mount object:

<template x-router:mount.evaluate="{ protocol: 'modal', target: document.querySelector('#router-mount') }"></template>

link

x-router:link Binds an a or form element as a link to activate a path.

Examples:

• Binding to an a element with href attribute:

<a href="/about" x-router:link></a>

• Binding to a form element with action attribute:

<form method="get" action="/search" x-router:link>
    <input name="query">
    <button type="submit">Search</button>
</form>

When the form above is submitted, a fetch request is made with the URL: /search?query=[Input Value] to the router.

• Binding to an a element specifying to always reload data:

<a href="/about" x-router:link.reload></a>

• Binding to an a element and listening for active state changes:

<a href="/about" x-router:link="console.log('Active state:', $active)"></a>

Note: x-router:link exposes a $active context property when evaluating the specified expression.

Magic Properties

---

$router

$router Exposes the following methods:

Method	Description
setPrefix	sets a prefix, to be prepended on fetch requests, on the router concept. Syntax: $router.setPrefix(prefix: string): void.
addMiddleware	adds a middleware to intercept page load requests. Syntax: $router.addMiddleware(middleware: IRouterMiddleware): string.
removeMiddleware	removes a middleware from the list. Syntax: `$router.removeMiddleware(middleware: IRouterMiddleware
addFetcher	adds a fetcher to intercept fetch requests. Syntax: $router.addFetcher(fetcher: IRouterFetcher): void.
removeFetcher	removes a fetcher from the list. Syntax: $router.removeFetcher(fetcher: IRouterFetcher): void.
addProtocolHandler	adds a protocol handler to respond to the specified protocol. Syntax: `$router.addProtocolHandler(protocol: string
removeProtocolHandler	removes a protocol handler from the list. Syntax: $router.removeFetcher(handler: RouterProtocolHandlerType): void.
addPage	registers a new page. Syntax: $router.addPage(page: IRouterPageOptions): string.
removePage	removes a registered page. Syntax: `$router.removePage(page: string
findPage	searches for page from the list. Syntax: `$router.findPage(page: string
findMatchingPage	searches for page that would handle the specified path. Syntax: `$router.findPage(path: string): IRouterPage
mount	initializes the router concept on the webpage. Syntax: $router.mount(load?: boolean): void.
goto	instructs the router concept to visit a path. Syntax: `$router.goto(path: string
reload	reloads the current path. Syntax: $router.reload(): void.
getCurrentPath	returns the current path. Syntax: $router.getCurrentPath(): string.
getActivePage	returns the current active page. Syntax: `$router.getActivePage(): IRouterPage
getActivePageData	returns the data associated with the specified key on the current page. Syntax: $router.getActivePageData(key?: string): any.

Security

If you find a security vulnerability, please send an email to [e-mail]

InlineJS relies on a custom implementation using the Function object to evaluate its directives. Despite being more secure then eval(), its use is prohibited in some environments, such as Google Chrome App, using restrictive Content Security Policy (CSP).

If you use InlineJS in a website dealing with sensitive data and requiring CSP, you need to include unsafe-eval in your policy. A robust policy correctly configured will help protecting your users when using personal or financial data.

Since a policy applies to all scripts in your page, it's important that other external libraries included in the website are carefully reviewed to ensure that they are trustworthy and they won't introduce any Cross Site Scripting vulnerability either using the eval() function or manipulating the DOM to inject malicious code in your page.

License

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