README.md in barista-0.7.0.pre3 vs README.md in barista-1.0.0

- old
+ new

@@ -1,36 +1,92 @@ # Barista # -Barista is a rails plugin that transparently compiles CoffeeScript to JavaScript. When a `.coffee` file is changed and the page is refreshed, it delays sending the `.js` file until it's been regenerated from the newly modified CoffeeScript. This way, you can refresh immediately after saving the `.coffee` file, and not worry about an old `.js` file being sent to the browser (as often happens when using `coffee --watch`). +Barista is a set of tools to make using [CoffeeScript](http://jashkenas.github.com/coffee-script/) in Rails 3, Rails 2 and Rack applications +easier. You can think of it as similar to [Compass]() but instead of for Sass, it's for CoffeeScript. -Barista supports using `therubyracer` when installed or, by default, the node.js version of CoffeeScript via the `coffee` executable. +Getting started is fairly simple - The short version for Rails 3 is simply: -Barista is very, very similar to [bistro\_car](http://github.com/jnicklas/bistro_car) (infact, credit where credit is due - it shares similar -code / is almost a fork). +1. Add `gem 'barista', '~> 1.0'` to your Gemfile +2. Run `bundle install` +3. Run `rails generate barista:install` -The main difference being, it lets you use coffee as you would javascript. Simply put, Write coffee -and place it in `app/coffeescripts` and Barista will automatically serve it as if it was placed in `public/javascripts` +Place your CoffeeScript's in `app/coffeescripts` and Barista will automatically compile them on change into `public/javascripts`. -That is, `app/coffeescripts/demo.coffee` will work for `/javascripts/demo.js`. Even better (and more importantly -for me), it provides `Barista.compile_all!` which takes all coffee files and compiles them into `public/javascripts`. -If you're using Jammit, this means you can simple run a rake task (`rake barista:brew` before running jammit) and -your coffeescripts will be automatically provided, ready for bundling. +As an added bonus, Barista also gives: +* Automatic support for a `:coffeescript` filter in Haml (when Haml is loaded before barista) - Automatically converting inline CoffeeScript + to JavaScript for you. +* Where possible, support for `coffeescript_include_tag` and `coffeescript_tag`. +* When possible, instead of pre-compiling in development and test modes, Barista will embed CoffeeScript in the page for you. +* Support for Heroku via `therubyracer` and either pre-compiled JS or, optionally, a lightweight Rack app that generates on request. + + +## General Information + +Barista transparently compiles CoffeeScript to JavaScript - When a `.coffee` file is changed and the page is refreshed, it first regenerates all `.js` files whose `.coffee` sources have been recently changed. This way, you can refresh immediately after saving the `.coffee` file, and not worry about an old `.js` file being sent to the browser (as often happens when using `coffee --watch`). + +Barista supports using `therubyracer` when installed or, by default, using either the `node` executable or `jsc` (on OSX) to compile your scripts. There is +no need for you to install the coffee script executable in node - having Node itself or any of the alternatives available is enough for you to get support. + +When you want to deploy, you can simple run `rake barista:brew` to force the compilation of all JavaScripts fro the current application. + +## In Practice + +Barista not only supports compiling all JavaScripts on demand (via `rake barista:brew` as above, or `Barista.compile_all!`) but it +also ships with a simple Rack server app that will compile on demand for platforms such as Heroku, meaning you don't need write access +(although it is helpful). + +If you're using Jammit, the precompilation phase (e.g. `rake barista:brew` before running jammit) will make it possible for your application +to automatically bundle not only normal JavaScripts but also your CoffeeScripts. + To add to your project, simply add: - gem 'barista', '>= 0.5.0' + gem 'barista', '~> 1.0' To your Gemfile and run bundle install. -As you place .coffee files in app/coffeescripts, it will automatically handle them for you. +Please note that for Jammit compatibility, in test and dev mode (by default) it will +automatically compile all CoffeeScripts that have changed before rendering the page. -Please note that for Jammit compatibility etc, by default in test and dev mode it will -automatically compile all coffeescripts that have changed before rendering the page. +Barista works out of the box with Rails 3 (and theoretically, Rails 2) - with support for Rack if +you're willing to set it up manually. More docs on how to set it up for other platforms +will be posted in the near future. -Barista require rails 3+ (but patches for Rails 2 will be accepted.) +## Configuration ## +Please note that barista lets you configure several options. To do this, +it's as simple as setting up an initializer with: + + rails generate barista:install + +Then editing `config/initializers/barista_config.rb`. The options available are: + +### Boolean Options + +All of these come in the form of `#option?` (to check it's status), `#option=(value)` (to set it) +and `#option!` (to set the value to true): + +* `verbose` - Output debugging error messages. (Defaults to true in test / dev) +* `bare` - Don't wrap the compiled JS in a Closure +* `add_filter` - Automatically add an around filter for processing changes. (Defaults to true in test / dev) +* `add_preamble` - Add a time + path preamble to compiled JS. (Defaults to true in test / dev) +* `exception_on_error` - Raise an exception on compilation errors (defaults to true) +* `embedded_interpreter` - Embeds coffeescript + link to coffee file instead of compiling for include tags and haml filters. (Defaults to true in test / dev) + +### Path options + +* `root` - the folder path to read coffeescripts from, defaults to app/coffeescripts +* `output_root` - the folder to write them into, defaults to public/javascripts. +* `change_output_prefix!` - method to change the output prefix for a framework. +* `verbose` - whether or not barista will add a preamble to files. +* `js_path` - Path to the pure-javascript compiler. +* `env` - The application environment. (defaults to Rails.env) +* `app_root` - The root of the application. +* `bin_path` - The path to the `node` executable if non-standard and not using therubyracer. +* All of the hook methods mentioned below. + ## Frameworks ## One of the other main features Barista adds (over other tools) is frameworks similar to Compass. The idea being, you add coffee scripts at runtime from gems etc. To do this, in your gem just have a `coffeescript` directory and then in you gem add the following code: @@ -80,46 +136,27 @@ An excellent example of these hooks in use is [barista\_growl](http://github.com/TrevorBurnham/barista_growl), by Trevor Burnham - a gem perfect for development purposes that automatically shows growl messages on compilation. -## Configuration ## - -Please note that barista lets you configure several options. To do this, -it's as simple as setting up an initializer with: - - rails generate barista:install - -Then editing `config/initializers/barista_config.rb`. - -Currently available options are: - -* `root` - the folder path to read coffeescripts from, defaults to app/coffeescripts -* `output_root` - the folder to write them into, defaults to public/javascripts. -* `no_wrap` and `bare` - stop coffee from automatically wrapping JS in a closure. -* `change_output_prefix!` - method to change the output prefix for a framework. -* All of the hooks mentioned above. -* `verbose` - whether or not barista will add a preamble to files. -* `compiler` - One of `:native` or `:node`, to force the compiler version. -* `compiler_klass` - A custom compiler class. -* `js_path` - Path to the pure-javascript compiler - # Contributors / Credits The following people have all contributed to Barista: * [Xavier Shay](https://github.com/xaviershay) - Added preamble text to generated text in verbose mode. * [einarmagnus](https://github.com/einarmagnus) - Fixed jruby support. * [Matt Dean](https://github.com/trabian) - Added `before_full_compilation` and `on_compilation_complete` hooks. * [Trevor Burnham](https://github.com/TrevorBurnham) - Misc. documentation tweaks and hooks idea. * [Sean McCullough](https://github.com/mcculloughsean) - Initial switch to support bare (vs. no\_wrap) * [Ben Atkin](https://github.com/benatkin) - Docs work. +* [Ben Hoskings](https://github.com/benhoskings) Misc fixes, added preamble support. -Barista was originally heavily inspired by [Bistro Car](https://github.com/jnicklas/bistro_car), but taking a fundamentally +Barista was originally heavily inspired by [Bistro Car](https://github.com/jnicklas/bistro_car), but has taken a few fundamentally different approach in a few areas. -The Native JavaScript compiler was heavily inspired by and based on [Sam Stephenson's](https://github.com/sstephenson) fork of -the ruby-coffee-script gem. All credit for the idea goes to him and the code is based on his simple approach. +Barista builds upon the awesome [coffee-script](https://github.com/josh/ruby-coffee-script) gem. + +It's all possible thanks to [CoffeeScript](https://github.com/jashkenas/coffee-script) by Jeremy Ashkenas. ## Note on Patches/Pull Requests ## 1. Fork the project. 2. Make your feature addition or bug fix.