Mandible: SocialGenius’s AudioVroom Buildtool Documentation

:

                           _,.---,---.,_
                       ,;~'             '~;,
                     ,;                     ;,
                    ;                         ; ,
                   ,'                         /'
                  ,;                        /' ;,
                  ; ;      .           .   '  ; ;
                 | ;   ______       ______   ; |
                 |  '/~"     ~" . "~     "~\'  |
                 |  ~  ,-~~~^~, | ,~^~~~-,  ~  |
                  |   |        }:{        |   |
                  |   l       / | \       !   |
                   .~  (__,.--" .^. "--.,__)  ~.
                  |    ----;' / | \ `;----    |
                    \__.       \/^\/       .__/
               ___   V| \                 / |V
              |      | |T~\___!___!___/~T| |
              |      | |`IIII_I_I_I_IIII'| |
      Mandible |      |  \,III I I I III,/  |
              |       \   `~~~~~~~~~~'    /
              |         \   .       .   /
              |__         \.    ^    ./
                             ^~~~^~~~^

:

Welcome

Mandible is a build and development toolset pulled from SocialGenius’s Audiovroom, open-sourced for your using pleasure.

Audiovroom is the popular HTML5 Facebook Mobile app that lets you play your friends like radio stations, across any browser or device.

See the full Facebook talk about responsive design, media queries, and cross-device HTML5 here.

Mandible

• is a collection of open-source and custom tools for organizing and prepping a web app for production.
• includes a copy of Skeleton, and dimension specific CSS files to get you started with a responsive design.
• makes your app mobile-ready from the start with the right HTML meta and CSS (taken from HTML5 boilerplate).
• gives your web app a (customizable) folder structure for development and production.
• concatinates and minifies your CSS and JS files.
• Comes with Underscore for JavaScript templating.
• allows you to create your own folder hierarchy of JavaScript templates.
• automatially creates and maintains production assets (css, js, templates).
• can watch for CSS and template changes and concat them on the fly.
• Includes a makeFile for concating JS, CSS, and concating templates in one easy step.
• detects for IE and includes polyfills like respond.js for parity in IE.

Mandible is targetted toward web apps built on JavaScript MVC frameworks (we love Backbone).

Mandible works by

• compressing and minifying your CSS with Sass.
• compresses and minifying your JS with UglifyJS.
• externalizing your JavaScript templates and watching for changes with NodeInterval.

Requirements

To use this tools you need to have the following installed:

• You need to install Ruby (already installed on all macs).
• You need to install Sass. sudo gem install sass
• You need to instal Node. (Compile it from here.)

Note: Compressed assets are not included in this repo. To see the sample code you must run “make” in the root folder at least once. (Which require you have the above installed.)

To use

For developers:

1. In terminal, run the two shell scripts in /bin. Keep them open while you do your development and all your CSS and templates changes are automatically merged into the production ready files.
2. While working, view your changes in /assets/index_uncompressed.html
3. When you’re done for the day, compress your JavaScript files by typing make in the root project folder. In case your bin scripts are off, this will also automatically compress all CSS, JS, and rerender the templates - but only when necessary.
4. Verify the production file at /assets/index.html.

For build managers:

1. Simply type make -B to force all CSS, JS, and templates processes to run. Push to production box(es) and / or CDN.

Explanation of application architecture

.
├── /assets                        <-- "Production" folder container html and compressed assets.
│   ├── index.html                 <-- The production-ready file you want to view to launch this webapp.
│   └── index_uncompressed.html    <-- The uncompressed js prod version with templates, use this during daily development.
├── /src                           <-- "Development" folder container html and uncompressed assets.
│   ├── index.html                 <-- Prod file without templates. Just used to generate real prod file. Never use it.
│   └── index_uncompressed.html    <-- Dev index file with raw js. Do your development here.
├── /bin                           <-- Dev shell scripts.
│   ├── sass-watch.sh              <-- Run this in another terminal tab to watch for css changes. It will automatically concat and minify to assets/css
│   └── template-watch.sh          <-- Run this in another terminal tab to watch for template changes. All templates get concatinated into assets/*.html files.
├── /vendor                        <-- Open-source shell scripts referenced by /bin scripts.
└── makefile                       <-- make utility for concatinating and minifying all js (and css and templates) to assets folder.

Additional tips

• You should probably put production ready folders assets/js and assets/js under .gitignore so they aren’t comitted to your repository (this is done for you.)
• If you want just the SASS bits steal just the sass script in /bin/watch-css.sh and src/scss/index.scss.
• If you want just the js compression features Steal the makeFile and the vendor folder.
• If you want just the template concat / watch features clone NodeInterval.
• We use HTML Mobile Boilerplate. Read up on it for lots of good tidbits like the ellipsis class.
• We recommend CSSPie for advance CSS3 support in IE.
• We’ll probably be open-sourcing our Backbone layer that fits on top of this in the future.

Projects we use and recommend:

• backbone.js - MVC JavaScript framework that utilizes jQuery and underscore.js. Underscore’s templating ability is especially useful.
• Skeleton - Grid-based CSS layout system to allow content to reflow to various browser widths.
• Facebook JavaScript SDK - The JavaScript SDK provides a rich set of client-side functionality for accessing Facebook’s server-side API calls.
• Soundmanager 2 - Cross-browser audio support.
• iScroll 4 - JS lib for native scrolling ability in subsections.
• Sass - Ruby Gem for organizing and minifying CSS.
• Node Interval - Node utility for managing and concatenating template files.