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.
• is targetted toward web apps built on JavaScript MVC frameworks (we love Backbone).
• gives your web app a (customizable) folder structure for development and production.
• concatinates and minifies your CSS and JS files.
• allows you to create your own folder hierarchy of JavaScript templates.
• creates and maintains your production assets (css, js, templates).
• includes a copy of Skeleton to get you started with a responsive design.
• 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.

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.)

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.
• Since Paul Irish is watching, use the HTML Mobile Boilerplate. We use it in our app but were too lazy to put it in the sample index.html. Lots of good tidbits in there like the ellipsis class.
• We’ll probably be open-sourcing our Backbone layer that fits on top of this in the future.

Q&A

• What is the heck are Javascript templates? Reusable markup in a JavaScrip tag. See here link.

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.