Here's a handy guide to help outline exactly how all of this works.
First, clone the repo:
$ git clone https://github.com/ftzeng/bane.gitThen change into the directory and run the setup script:
$ cd bane
$ ./summon.shOr, if you're lazy, here's the whole thing in one line:
$ git clone https://github.com/ftzeng/bane.git && cd bane && ./summon.shFirst, you will probably want to run the Grunt
watch task, which is the default task:
$ gruntThis will automatically compile your Jade templates, Sass stylesheets,
and Font Custom SVGs as they change. You can modify this task in Gruntfile.js.
More conveniently, you can use the powerup.sh script, like so:
$ source ./powerup.shThis is just a little bit more convenient and opens up a new tab with the site in it.
BBBane.ed (★Backbone Boilerplate Bane edition★) has the following directory structure, with the example project:
├── Gruntfile.js
├── app
│ ├── app.js
│ ├── config.js
│ ├── main.js
│ ├── modules
│ │ └── (your modules)
│ ├── router.js
│ ├── styles
│ │ └── (stylesheets, based off Atomic)
│ ├── templates
│ │ ├── some_module
│ │ │ └── (module templates)
│ │ └── main.jade
│ └── templates.js
├── assets
│ └── images
├── data
│ └── (dummy JSON data)
├── favicon.ico
├── index.html
├── package.json
├── powerup.sh
├── summon.sh
├── source
│ ├── icons
│ │ └── (SVG source files)
│ └── images
│ └── (PSDs, AIs, etc)
└── vendor
├── jam
│ └── (jam packages)
└── js
└── libs
└── (other js libs)
main.js
Here is where the application kicks off. app.js and router.js are
loaded, and then the Router created in router.js is instantiated and
attached to your app.
Backbone's history is setup. In our case, we're using hash urls instead
of the HTML5 history API. Using "true" urls requires some special
handling on the server, and in our prototyping use case it's nice if we
can just use a simple HTTP server (see below on how).
This file also specifies a binding for links in the document, hijacking
relative links (i.e. links on the same site) so they use the app's
router instead of their normal behavior.
Specifying a data-bypass attribute on the element will override this
binding.
app.js
Here is where you can load in any additional JS packages and configure
your app object, such as setting what the root url is.
This is also where LayoutManager is setup and where template fetching is
handled.
router.js
This is where the navigation interaction is handled. You load your app
here and your modules as well. Routes are created here as well.
config.js
This is what RequireJS loads first (as specified in index.html) and
loads Jam's RequireJS config (thereby loading your core packages) and
then loading main.js.
modules/
Here is the meat-and-potatoes of your app. Modules are logical units
representing the entities in your application. Things that 'belong
together' should be wrapped up in a module, which would encompass
the relevant model(s), view(s), and collection(s).
You load these modules into router.js.
templates/
Templates are stored here. Bane uses
Jade as its templating engine, and
expects .jade as template extensions. You should try to group them
according to module, though you are not held to these rules.
styles/
Bane is using my Atomic CSS microframework as a submodule. It's still a
work in progress and is meant to reflect my own style defaults, so you
may want to swap this out with something more appropriate for yourself.
If you decide to stick with my framework, you can edit _atomic.scss to
configure Atomic, such as colors/type and what modules to use, and to
paste in icon classes generated by Font Custom
(see below).
In index.scss you can place the rest of your styles.
data/
Place dummy data in here as json files. Specify your collection urls
to point to the appropriate files here. This allows your prototype to
feel a little more 'real'.
source/
Place asset source files in here, such as SVGs for building icon fonts,
or PSDs for raster graphic assets.
vendor
Third-party packages are placed in here, such as those installed by Jam
(in vendor/jam/), or those you install yourself (in vendor/js/, for
example).
package.json
Specify your app's dependencies and other information here.
This is also where Jam's directories are specified.
Font Custom is an awesome tool that allows you to build your own icon fonts from SVG files.
Here's how to install it on OSX.
You will need Homebrew, which can be
installed by running the following command:
$ ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"Then, to install Font Custom:
$ brew install fontforge ttfautohint
$ gem install fontcustomSee the Font Custom site for Linux installation instructions.
The source SVGs are located in source/icons, so if you are modifying,
adding, or removing icons, place them there.
If you have the Grunt default (watch) task running, Grunt will automatically compile, move and modify these files so that you're using the newest icons.
Otherwise, you'll need to run following command from your application root to compile the SVGs into an icon font.
$ fontcustom compile source/iconsGrunt is an essential automation tool. It will
perform a set of preconfigured tasks for you, which you define in
Gruntfile.js.
Bane's default task can be initialized with:
$ gruntin Bane's root directory.
This will start watching the project files for any changes, and
automatically compile Jade, Sass, and Font Custom files. It will also run a server on
port 8989, providing access to the project (i.e.
http://localhost:8989).
If you are not running the native app version of
LiveReload, you can
optionally uncomment the livereload: true configuration line in the
Gruntfile to start a LiveReload server as well. To use it, install the
LiveReload Chrome
extensions,
so that your site will automatically refresh on file change.
You can easily augment Grunt to your own liking with its vast set of plugins.