better-hash-router

v3.2.2

Published

2 years ago

A Router Library for Hash links on an html page

Downloads

124

0High
0Medium
0Low

amalu_sajeev

hash router hash router browser router better hash router better router vanilla

Better-Hash-Router

A better routing using hashed anchor tags on your html pages.

Usage

include the script from CDN https://unpkg.com/better-hash-router@latest

index.html

<script src="./script.js" type="module"></script>

script.js

import { Hash } from "https://unpkg.com/better-hash-router@latest";

see HTML example on Github here

or if you're using npm

Install npm i better-hash-router

// ES6
import { Hash } from "better-hash-router";

// CommonJS
const { Hash } = require("better-hash-router");

Note: The <body> </body> must be empty. all the content on each route will be parsed and injected to the <body></body> at runtime.

How TO

First you have to initialize the library, else it'll remind you to doing so by throwing an error.

Hash.initialize();

Now you have to create a new instance of Hash

const myRouter = new Hash("router-name");

Now you can add new Routes to your Router instance.
route() method accepts 2 parameters.

path: a String representing the hashed path without the #. eg. if path is "#about" then remove the #. which is "about"
data: String | HTMLElement | Object | Function data can be passed in as multiple formats. see the examples below.
route() method returns the router instance. therefore the method is chainable.

Both Arguments are Mandatory.

"/" path determines the root path, which is your default path. so the contents assigned to the "/" route will be displayed when you open your page.

Adding new routes

data: string

Hash.initialize();
const myRouter = new Hash("router-name");
myRouter.route("/", "this will be displayed on your root");

data: HTMLElement

Hash.initialize();
const myRouter = new Hash("router-name");

const aboutDiv = document.createElement("div");
aboutDiv.innerHTML = "Hey this is about me";

myRouter.route("about", aboutDiv);

data: { template, selector }

   { 
    template: "absolute path to file", 
    selector: "css selector" 
    }

assuming that you have an html file on /pages/contact.html and there is an element with id contact-form

NOTE: Here the selector is optional. if selector is not provided, then all the contents of the contact.html's body will be copied to the route.

Hash.initialize();
const myRouter = new Hash("router-name");
myRouter.route("contact", { 
 template: "/pages/contact.html", 
 selector: "#contact-form" 
});

data: Function

Hash.initialize();
const myRouter = new Hash("router-name");
myRouter.route("/", () => {
 return "this data comes from a function";
});

Chaining `route()` methods

instance.route() can be chained since it returns the instance itself.

Hash.initialize();
const myRouter = new Hash("router-name");
myRouter
.route("/", "this page shows info about me")
.route("contact", "my contact info")
.route("any_other_route", "some interesting stuff"); 

// goto yourdomain:port/#any_other_route to see the content

Manually open a page

instance.open() can be used to open a path manually.

accepts an argument Path as a String

const button = document.getElementById("contact-button");
button.addEventListener("click", event => {
myRouter.open("contact");
});

Events

Hash.EVENTS // all supported events can be accessed via this static property.

open - fires when you open a page using instance.open(path).
doneparsing - fires when a intance.route(path, data) parse a template.
close - fires when the close() method is called.
error - fires when a parsing error occures on a route.

Event Handlers

addEventListener(event, callback)

myRouter.addEventListener("open",function (event){
 // your code goes here..
});

onPageLoad(path, callback)

myRouter.onPageLoad("/", function (event) {
 // your code goes here..
});

onReady(path, callback)

myRouter.onReady("/", function (event) {
 // your code goes here..
});

onError(callback)

myRouter.onError(function(){
 // your code goes here..
});

Instance Methods

1. route(path, data)
2. open(path)
3. fetchTemplate({template, selector})
4. onPageLoad(path, callback)
5. onReady(path, callback)
6. onError(callback)
7. addEventListener(event, callback)

Instance Properties

1. availableRoutes (getter)

Static Methods

1. initialize()
2. isRouteDefined(path)
3. close()
4. router(name)

Static Properties

1. availableRouters
2. isInitialized
3. availableTemplates
4. EVENTS

Examples

using a function as the data argument.

function must have a return statement of a String or an HTMLElement

Hash.initialize();

const navigationRouter = new Hash("navigation");

navigationRouter.route("/", () => {
  const tiles = ["skills", "projects", "about", "resume", "contact"];
  const wrapper = document.createElement("div");

  tiles.forEach(tile => {
    const link = document.createElement("a");
    a.innerHTML = tile;
    wrapper.append(link)
  });

  return wrapper;
});

using templates from a single html file.

assuming that you have a template.html file in your root directory. and they have elements with appropriate id

Hash.initialize();
 
const myRouter = Hash.router("my router");

myRouter
 .route("/", {template: "/template.html", selector: "#home"})
 .route("about", {template: "/template.html", selector: "#about"})
 .route("contact", {template: "/template.html", selector: "#contact"});

DOM Manipulation

If you want to manipulate the content of your routes, please note that they don't exist at the window.onload event. because the routes and their contents are fetched and rendered after the onload event of window. so, instead of using window.onload, you should use the onPageLoad eventListener on your router instance.

assuming that you already have a contact route defined on your router

myRouter.onPageLoad("contact", (event) => {
 console.log("contact page has loaded");
 // now you can Manipulate your DOM elements her...
});

CONTRIBUTOR

Amalu Sajeev

Feel free to reach out to me..