website.js
Library to run a Multi-Page-Content-Website as a Single-Page-Application.
It's like a static site generator that runs in your browser.
Installation
npm install websitejs
bower install websitejs
Or use a file from the /dist
folder directly.
The website.bundle.js
build is a basic, working website with:
- HTTP (fetch sitemap and content using XHR)
- Markdown (convert Markdown to HTML)
- Render (Render content into document element IDs)
- Log (Log all events for debugging)
The Idea
website.js is a framework for running multi-page content websites as a Single-Page-Application.
It handles the lifecycle and essential tasks of a multi-page website:
- Fetch website metadata (config, sitemap and page metadata)
- Respond to URL changes (Router)
- Fetch content (i.e. Markdown or HTML)
- Render the page
Using plugins and events, website.js is easy to extend and customize the above tasks.
Included plugins:
- For fetching website metadata and content:
- HTTP
- Firebase
- Firebase REST
- For rendering
- Template: Parse content using DOT template engine
- Markdown: Parse (some) content as Markdown
- Render: Insert HTML content into DOM-elements (using the element id)
- For debugging
- Log: Log all events that are triggered
There is one special plugin: The Core Plugin.
The Core Plugin handles the flow of the website:
- On
created(options)
, fetch the website data withgetData(callback)
- On
gotData(data)
, checkdata.sitemap
for urls. - Trigger
gotDataForUrl(url,pageData)
for every url to populate the router. - When the router fires
navigated
, getContent(id,callback)
to fetch contentgotContent(id)
to transform contentrender(pageData)
the pagerendered(pageData)
do stuff after renderingrendered /your/url(pageData)
do stuff after rendering a specific URL.
Getting Started
var site = router: html5: false // defaults to true, if browser supports it base: '/example' // base url, all navigation is relative to this url core: ... // Override the core plugin (optional) plugins: // Add plugins Websitepluginshttp Websitepluginsfirebase Websitepluginsmarkdown Websitepluginsrender Websitepluginslog // plugins often add more options! // navigate programatically to a urlsite; // re-render current url/routesite;site; // re-render current URL after all events have fired.site; // re-render current URL after 100 ms. // Content that has been fetched (useful to transform content after a `gotContent` event)sitecontentid;
Events
// listen to website' events (see below) site site
Events are fired roughly in the following sequence:
-
When creating new Website:
created(options)
gotDataForUrl(url,pageData)
gotData(data)
-
When navigating:
navigated(url)
gotContent(id)
- this is called for every idrender(pageData)
rendered(pageData)
renderer [url](pageData)
Note that gotContent(id)
only has the id
. Use this.content[id]
to access the content.
Plugins
A plugin is an object that listens to events. Simply use eventNames as attributes. For example, the MarkdownPlugin transforms content into markdown:
var MarkdownPlugin = { ifthis thiscontentid = ; } // created: function(options) { /* initializes the markdownFilter */ } // etc;
In addition to the events, plugins allow two extra methods:
{ // fetch your data ; } { // fetch your content }
Core Plugin
The Core Plugin handles the lifecycle of the website: On navigation, fetch and render content.
So you must specify the urls of your website, and what content to fetch for every url.
To do this, getData
follows a convention:
data.sitemap
contains a map fromurl
topageData
.pageData.content
is an string (contentId) or an object ({name:contentId,name:contentId}
).render(pageData)
is called with page metadata, only contentId has been replaced with actual content.
You still need to provide plugins for
getData(callback)
getContent(id,callback)
render(pageData)
Site metadata (Example):
var data = sitemap: '/page1': title: 'Page 1' content: 'page1.md' '/page2': title: 'Page 2' content: sidebar: 'sidebar.md' content: 'page2.md' // + other site data
HTTP Plugin
Configure http with a content and data url:
http: content: locationorigin + '/example/content/' data: locationorigin + '/example/site.json'
Firebase Plugin
Configure Firebase with a content and data url:
firebase: content: 'https://YOURFIREBASE.firebaseio.com/content/' data: 'https://YOURFIREBASE.firebaseio.com/data/'
Firebase is comes in two flavours: Live and REST.
The plugin automatically creates a correct URL for the REST API (i.e. append .json
).
Note: Firebase does not allow .
or /
in keys. Therefore, when saving data to firebase, you must use -dot-
and \
.
When retrieving the sitemap and content, these are automatically converted back to .
and /
.
Render Plugin
Renders pageData.content
as follows:
- For an object
{#elementId: content}
: Inserts content into element with #elementId - For a string: Replace document.body with content
Note: The #layout
element is always rendered first, allowing you to specify a layout first, then render blocks of content in that layout.
Example:
content = "layout":"sidebar-layout.html" "sidebar":"navigation.html" "content":"blog-about-javascript.md"
You can write a custom Render plugin as follows:
var MyCustomRenderer = { // `this` is the Website instance pageMetadataurl // route (normalized url) // url parameters pageMetadataparams // content (the contentId has been replaced with actual content) pageMetadatacontent } // later:var website = plugins: MyCustomRenderer }// orwebsite
Markdown Plugin
The Markdown Plugin parses all content as Markdown.
If you want, you can specify a filter (i.e. which content id need to use Markdown?)
// Filter using a string (content-id must contain this string) markdown: '.md' // Filter with a Regex markdown: /.md$/ // Filter with a function // // imagine you have the following Site metedata: // data.markdown = ['pagea','pageb'] { return thisdatamarkdown >= 0; }
Template (DOT) Plugin
Uses the fast and efficient doT template engine.
On gotContent
, compiles the template.
On render
, renders the template with your page metadata.
If you want, you can specify a filter (see above)
template: filter: '.tmpl' // string, regex or function
Cache Plugin
Caches sitemap and content in IndexedDB, WebSQL or localStorage using localForage
Advanced features
// live-update your site:sitesitesite; // Manually get data or content:site ;site ;site
Changelog
0.2.0: 12/1/2015
- Added cache and template plugins
- Added
bundle
build with everything included. - Few minor bugfixes
0.1.0: 9/1/2015
First release. Implementation and API are probably relatively stable now.
Contribute
Feel free to contribute to this project in any way. The easiest way to support this project is by giving it a star.
Contact
- @markmarijnissen
- http://www.madebymark.nl
- info@madebymark.nl
© 2014 - Mark Marijnissen