Status: Deprecated
Instead of requiring you to install this NPM module, Awesomebox now integrates directly with Github.
In order to focus on making the integration with your source control amazing, we're no longer providing support for this module.
awesomebox
Effortless HTML, CSS, JS development in the flavor of your choice
Installation
You'll have to have node.js installed first. The easiest way to do this is going to nodejs.org and clicking the big INSTALL button. Once node.js is installed, open up a terminal and and run the following.
$ npm install -g awesomebox
You may need to sudo in order to install awesomebox. Alternatively you can grant yourself permissions to /usr/local
running sudo chown $USER -R /usr/local
first.
Usage
Then to run awesomebox, just change directory into your project's directory and run awesomebox from there. That's it!
$ cd /path/to/my/project$ awesomebox
Videos
Quick Intro: http://screencast.com/t/xCpB1i66
Features
- Automatic Transpilation of HTML, CSS, and Javascript dialects
- Automatic Transpilation of
<script>
and<style>
tags - Layouts
- Partials
- Data Files (JSON and YAML)
Currently Supported Dialects
HTML
atpl
filename.html.atpl
dust
filename.html.dust
eco
filename.html.eco
ect
filename.html.ect
ejs
filename.html.ejs
haml
filename.html.haml
haml-coffee
filename.html.haml-coffee
handlebars
filename.html.handlebars
hogan
filename.html.hogan
jade
filename.html.jade
jazz
filename.html.jazz
jqtpl
filename.html.jqtpl
JUST
filename.html.just
liquor
filename.html.liquor
markdown using pygmentize
filename.html.md
or filename.html.markdown
mustache
filename.html.mustache
QEJS
filename.html.qejs
swig
filename.html.swig
templayed
filename.html.templayed
toffee
filename.html.toffee
underscore
filename.html.underscore
walrus
filename.html.walrus
whiskers
filename.html.whiskers
CSS
less
filename.css.less
or <style type="text/less"></style>
sass/scss
filename.css.sass
or <style type="text/sass"></style>
stylus
filename.css.styl
or <style type="text/stylus"></style>
Javascript
coffee-script
filename.js.coffee
or <script type="text/coffeescript"></script>
React.js
filename.js.jsx
or <script type="text/jsx"></script>
Directory Structure
To use awesomebox, you never need to change the directory structure that you're currently using. Just run awesomebox in your project's directory and it'll work!
- index.html # Will be rendered for / or /index or /index.html
- posts
|- index.html.ejs # Will be rendered for /posts or /posts/index or /posts/index.html
|- post-1.html
|- post-2.html
- css
|- style.css.less
- js
|- app.js.coffee
If you'd like to take advantage of some of the features that awesomebox provides, all you need to do is create a
content
directory and it'll get picked up automatically. Now you'll have access to layouts and data file access.
- content
|- index.html # Will be rendered for / or /index or /index.html
|- posts
|- index.html.ejs # Will be rendered for /posts or /posts/index or /posts/index.html
|- post-1.html
|- post-2.html
|- css
|- style.css.less
|- js
|- app.js.coffee
- layouts
|- default.html.ejs # Default layout
|- posts.html.ejs # Layout for posts directory
- data
|- identity.yml
|- blog_posts.json
box
Object
The The box
object is always available from your templates and contains special methods that link you into the
awesomebox system. The most notable of these is the box.content
method. This can be used by layouts to render
the main template for the current route or to render partials. There are also other properties available on the
box
object, such as the current view and current route.
Content
Content can be straight HTML or can use a view rendering engine.
Since awesomebox makes use of consolidate, it supports all rendering
engines listed in the consolidate documentation. The rendering engines and order is determined by the extensions
on the page filename. For instance, if you have a file named index.html.ejs.hogan
, the file will first be
run through the hogan
rendering engine and then then ejs
rendering engine. The resulting data will be returned
to the browser as HTML.
Partials
Partials are rendered using the box.content
method from within templates. Partial filenames MUST start with
the _
character. Partial resolution is the same as page resolution, except that partials are resolved either
relative to the template it is being called from or absolutely from the html
directory.
For instance, if the layout at /layouts/index.html.ejs
wants to include a footer partial, it can reference a
partial at /layouts/partials/_footer.html.ejs
by including this:
However, if the partial was located at /html/_footer.html.ejs
, then the layout should include this:
Passing data into partials is very easy. You can either pass in an object, like this:
Or you could provide the path to a data file, like this:
The above example will find the data file named name_data.{extension}
, parse it, and pass it into the print_my_name
partial.
Layouts
Layouts are used to abstract away all the headers and footers and general page structure that all pages tend to share. They are not necessary whatsoever but definitely make life much easier. It is important to note that layouts are only available for html pages.
Layouts are resolved in a very specific way. For any page, the applicable layout will be the directory name for
that page. For instance, for a page at /foo/bar/baz.html{.engine?}
, the resolution order would be
- /layouts/foo/bar.html{.engine?}
- /layouts/foo.html{.engine?}
- /layouts/index.html{.engine?}
- No Layout
Layouts can use the box.content()
method to place the content of the rendered page.
For example, you could create a simple layout that uses partials for the header and footer, and inserts the page content between them.
/layouts/index.html.ejs
My Amazing Project
This example also shows how you can share variables between the rendered content and the layout since the content is rendered first, then the layout is rendered.
/content/index.html.ejs
Welcome to my awesome project! I hope you have a nice stay. Look around for a bit.
Data
Data files can be used for a lot of different things, like configuration, example data, lists of information, etc.
These files can either be read in as raw files or parsed for you to use in your templates. Currently recognized formats
are JSON
and YAML
files with extensions .json
, .yaml
, .yml
. All data files should reside in the data
directory
and will be resolved within that directory.
For example, let's say that you want to display a list of names and pictures on your team page. You could maintain
that list in a data file and reference it from your template with box.data(...)
.
/data/team.json
/content/team.html.ejs
Our Awesome Team Check out my work at
You can also read the data raw with box.data.raw(...)
. This is great for debugging data files too.
Check out my data.
Deploying
If you'd like to run awesomebox on your own server, you're more than welcome to!
However, if you want something a little easier, you can deploy your project to Heroku with almost no work at all. Just use the Awesomebox Heroku Buildpack (follow the link for instructions).
License
Copyright (c) 2013 Matt Insler
Licensed under the MIT license.