A simple router element for targeting portions of your webpage at specific content based on the URL. Includes support for...
- Route based on url or url sections such as
- search query
- and more...
- Lazy loading of inner content.
Built on top of the ZephJS Framework.
zephjs-router is available as an npm package:
npm install zephjs-router
Once installed find the
zephjs-router.js file and copy it into your local project as needed.
zephjs-router.js is a self contained element and includes a copy of ZephJS within it. If you are interested in the unbundled version without ZephJS, see the
Within your HTML file, include the following:
Once the script is loaded you can use
<zephjs-rotuer> anywhere within your HTML content.
This matched the ABC hash.This matched the DEF hash.
When loaded on your page, the
zephjs-router.js script creates two custom elements:
<zephjs-router> element identifies a section of your webpage as being driven by a router. Within the router, you include zero or more
<zephjs-route> elements to describe a given route and its content. Each of these routes will only be displayed if the route
match attribute is met.
Any content other than
<zephjs-router>element is not displayed.
You may use
<zephjs-router>as many times as you like within you code. Each is an isolated router and works independant of any other router.
<zephjs-route> element is used to identify some content and the rules under which that content is displayed. It has the following structure:
... content ...
match attribute describes the text test we want to match. There are several different types of matching rules:
*: All match. The match will always be true regardless of the item being matched against (See below).
text: Exact match. The match will be true only if the item being matched against (see below) is exactly the same as the text provided.
text*Starts with match. The match will be true only if the item being matched against (see below) starts with the text provided.
*textEnds with match. The match will be true only if the item being matched against (see below) ends with the text provided.
*text*Contains match. The match will be true only if the item being matched against (see below) contains the text provided.
If no match attribute is provided, the match will never be true.
against attribute describes what the
match argument is matching against; that is, what property of the page (usually the url or a part of the url) the
match expression is compared against. There are several different options:
url: Matches are compared against the entire url
href: Same as
hash: Matches are compared against the hash portion of the url:
xyz. Note that the preceeding number sign (#) character is removed prior to comparison.
path: Matches are compared against the path portion of the url:
pathname: Same as
protocol: Matches are compared against the protocol portion of the url:
port: Matches are compared against the port portion of the url:
4000. Note that for matching purposes port is treated as a string.
host: Matches are compared against the host portion of the url:
awesomeeng.com:4000. The host portion is a concatenation of the hostname and port portions.
hostname: Matches are compared against the hostname portion of the url:
origin: Matches are compared against the origin portion of the url:
http://awesomeeng.com:4000. The origion portion is a concatenation of the protocol, hostname, and port portions.
search: Matches are compared against the search/query string of the url:
abc=1223. Note that the query string is treated as a whole string, not separtated into a query object.
You may define as many
<zephjs-route>elements within a
<zephjs-router>element as you wish.
If more than one route element matches, only the first match is shown.
The content you provide within
<zephjs-route> is the HTML that is displayed when the route matches. If the route does not match, the content is not displayed.
You may specify a
default route by adding the
default attribute (with no value) to one of your
<zephjs-route> elements. If no route matches, the default is selected.
In the event that no default is provided and no route matches, the first route will be treated as the default.
In all of our above examples our
<zephjs-route> has contained its content within it. However, especially with large sites, there is a case where you would prefer to load the content within a route only if that route is matched. This is possible with lazy loading.
To use lazy loading instead of providing content with your
<zephjs-route> element, you add a
lazy attribute with the value being the path to the content to load. For example:
When the route is match, ZephJS will go out and load the content specified by the
lazy attribute, and insert it into the
<zephjs-route> element. There after, it will just use that content anytime the route is matched. (In fact, once the content is loaded, the
lazy attribute is removed to prevent it from being loaded again.)
zephjs-router ships with a set of examples for your reference.
Basic Hash Router Example: An example of routing against the url hash.
Lazy Loading Router Example: An example of using Lazy Loading.
The Awesome Engineering Company
zephjs-router is written and maintained by The Awesome Engineering Company. We believe in building clean, configurable, creative software for engineers and architects and customers.
To learn more about The Awesome Engineering Company and our suite of products, visit us on the web at https://awesomeeng.com.
Support and Help
zephjs-router is released under the MIT License. Please read the LICENSE file for details.