Vanilla Router Is A Open-Source Library That Allows You To Implement No-Reload Page Routing using history.pushState
, Support For HTML Components & Their Inclusion With In-Built Support For TopBar.js.
Currently This Is The First Release Of Vanilla Router named 0.1 Alpha. It Is In Rapid Development & Bugs Can be Seen.
- On-Page / No-Reload Page Routing
- HTML Components (Referred To As Drops)
- TopBar.js Support Included
Include Vanilla Router By Adding Either The File, Or The CDN To Your <Head>
Tag
NOTE: It is important to include the CDN / File Only In Your Head Tag
<head>
<title>...</title>
<script src="./vanillarouter.min.js"></script>
// Or
<script src="https://cdn.jsdelivr.net/gh/Adison-Masih/vanillarouter/vanillarouter.min.js"></script>
</head>
Initialize A New VanillaRouter Instance Like This:
const router = new VanillaRouter()
Vanilla Router Gives You Three Initialization Options:
useTopBar
is used to provide if you want to use the TopBar Package . Its Default Value Istrue
. You Will Learn about it later in this doc.topBarConfig
is used to configure thetopbar
package. if not provided (or providednone
), default configuration is used.isProduction
can be used to avoid any errors that happen during runtime. default value isfalse
. if set totrue
, no errors will be thrown even when there are any (only Valid for VanillaRouter Package).
const router = new VanillaRouter({
useTopBar: true,
topBarConfig: 'none',
isProduction: true,
})
Every Page you want to route to needs to contain a <routable>
tag inside of the absolute <body>
tag. All The contents from the routable will be taken by the demanding page when routed to this page. that means, anything outside the <routable>
tag will not be rendered / added to DOM when routed to.
This Tag accepts three html attributes
:
title
script
css
The title
attribute of the <routable>
element will become the <title>
of the page when ROUTED TO.
<body>
<routable title="Enter Page title here">
Your Content Here...
</routable>
</body>
Though You Can include as Many Scripts inside the <routable>
element, they will only stay inside the <routable>
element itself and will not be appended to the <body>
.
<routable>
<script>let x</script> // These Scripts
<script>let y</script> // Will Stay Inside
<script>let z</script> // The <routable> Element
</routable>
But This Behaviour Can Be Overriden For one
script element by providing it with a unique id
attribute and then passing the value of id
attribute to the script
attribute of the <routable>
element
<routable script="myScript">
<script id="myScript">let mine = "yours!"</script>
// This Script will be Appended to the end of the body when routed to the this page.
</routable>
As for the script
, css
attribute has the same story, add an id to the style element, pass it to the css
attribute and it will be appended to the <head>
element when routed to the current page.
If your application is in a directory or some nested url, you might need to consider absolute paths. it is by default set to /
. you can change it globally by:
router.setABSPath('/your/nested/url')
Well the part you've been waiting for is here. to navigate to a page, you need to use the router.to()
method provided by the vanilla router instance. this method is async
and can be awaited
. it uses the history.pushState
method to change the url
and state
of the page.
It takes three parameters:
url
- required*component
- optionaltitle
- optional
The url
parameter will navigate to the url you pass in here. how this works is, it fetches the url
you give, parses it, then takes the valid contents from the routable
element, do some tweaks and displays the results blazing fast!
const router = new VanillaRouter({...options})
router.to("/your-url-here")
if you want to navigate to a url
but want to fetch the contents from a different url, you can pass it as the component
.
router.to('/a-different-url', '/real-url')
if you don't pass the title
attribute in the <routable>
element, you can pass it in the title
parameter of this function. it will behave the same way and both work on fallback system.
<routable>
I ain't got no title!
</routable>
router.to("/url", "/component", "I've Got You Covered!")
Bonus: If You Have Set the
useTopBar
totrue
while initializing the router instance, you will see the bar on the top animating when you start to navigate and fades out when the results are displayed.
Although, whatever you place outside the <routable>
element won't be shown while routing, though it will require you to rewrite the page 2 times. which is pretty difficult according to me (opinions differ). for that purpose you have the <direct>
element. it must be placed inside the <routable>
tag, whatever you place inside the <direct>
tag, in-spite of being inside <routable>
will not be rendered while routing and only renderes when the page is directly visited.
<routable>
This will be shown while Routing!
<direct>
This Won't Be Shown While Routing!
</direct>
</routable>
If You Want Something inside your <direct>
tag to be rendered while routing, wrap it up in <routed>
element and you're done! this is completely opposite to the <direct>
element and can you be used to avoid writing same code multiple times.
Well, Attaching Event listeners to everything you want to route to can be difficult and weird. to avoid this, you get the <rlink>
element.
It stands for Routable Link
. it is a <a href>
tag but in a routed way 😉
. it is converted to anchor tag on runtime with the stateful
attribute to indicate and differ it from normal anchor tags.
It Has Two Different Attributes for different use cases.
href
- the value of this will be the url routed to.
<rlink href="/your-url-here">Click Here!</rlink>
abshref
- it prepends theabsolute path
of your application to the provided value.
router.setABSPath('/nested/dir')
<rlink abshref="/your-url-here">Click Here!</rlink> // returns abspath provided value
VanillaRouter provides you to break down your html code in form of components also known as drops
.
To Create A Drop
, create a file with any file name ending with the extension .drop
.
Then Place your HTML ONLY
Contents inside it.
To Access with from another page use the <drop>
element with the attribute name
providing the filename of the drop without the .drop
extension.
<drop name="navbar" />
if you wan to use history.replaceState
instead of history.pushState
, you can use the router.replace
method. it takes the same arguments as the router.to
but uses history.replaceState
instead.
If you want to route to the abspath
of the router, which is /
by default, you can use the router.home
method. it takes no arguments.
router.home() // redirects to absolute path
Currently Back
And Forward
Buttons are not handled by the router. it is prone to the next update. but if you want to extend the library by adding your own handlers, you can do it so by:
router.handlePopState = () => {
// your code here
}
router.handlePopState
is executed when window.onpopstate
occurs and is set by the router, so don't need to attach the window.onpopstate
handler seperately so that you can extend the library by ease.