Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Cleaned up the docs to make them more readable.

  • Loading branch information...
commit ef28ac5bde5a8aac36cfb70533cfc5918f2d695c 1 parent 60d87fb
Kim Joar Bekkelund kjbekkelund authored Sutto committed

Showing 1 changed file with 58 additions and 63 deletions. Show diff stats Hide diff stats

  1. +58 63 README.md
121 README.md
Source Rendered
... ... @@ -1,41 +1,40 @@
1   -# Barista #
  1 +# Barista
2 2
3 3 Barista is a set of tools to make using [CoffeeScript](http://jashkenas.github.com/coffee-script/) in Rails 3, Rails 2 and Rack applications
4   -easier. You can think of it as similar to [Compass]() but instead of for Sass, it's for CoffeeScript.
  4 +easier. You can think of it as similar to [Compass](http://compass-style.org/), but for CoffeeScript instead of [Sass](http://sass-lang.com/).
5 5
6   -Getting started is fairly simple - The short version for Rails 3 is simply:
  6 +Getting started is fairly simple — the short version for Rails 3 is simply:
7 7
8 8 1. Add `gem 'barista', '~> 1.0'` and, if you're not using Ruby 1.9, `gem 'json'` to your Gemfile
9 9 2. Run `bundle install`
10 10 3. Run `rails generate barista:install`
11 11
12   -
13   -Place your CoffeeScript's in `app/coffeescripts` and Barista will automatically compile them on change into `public/javascripts`.
  12 +Place your CoffeeScripts in `app/coffeescripts` and Barista will automatically compile them on change into `public/javascripts`.
14 13
15 14 As an added bonus, Barista also gives:
16 15
17   -* Automatic support for a `:coffeescript` filter in Haml (when Haml is loaded before barista) - Automatically converting inline CoffeeScript
  16 +* Automatic support for a `:coffeescript` filter in [Haml](http://haml-lang.com/) (when Haml is loaded before Barista) — automatically converting inline CoffeeScript
18 17 to JavaScript for you.
19 18 * Where possible, support for `coffeescript_include_tag` and `coffeescript_tag`.
20 19 * When possible, instead of pre-compiling in development and test modes, Barista will embed CoffeeScript in the page for you.
21   -* Support for Heroku via `therubyracer` and either pre-compiled JS or, optionally, a lightweight Rack app that generates on request.
  20 +* Support for Heroku via [therubyracer](https://github.com/cowboyd/therubyracer) and either pre-compiled JS or, optionally, a lightweight Rack app that generates on request.
22 21
23 22 ### A Quick Note on the JSON Gem
24 23
25   -Barista indirectly requires the json gem via the coffee-script gem, but it isn't list as a dependency for very
  24 +Barista indirectly requires the json gem via the coffee-script gem, but it isn't listed as a dependency for very
26 25 good reasons. If you encounter errors relating to `require 'json'`, Then you'll need to add either `gem 'json'`
27 26 or `gem 'json_pure'` to your Gemfile.
28 27
29   -If you're already running Ruby 1.9, this will be unnecessary as json is now shipped as part of the standard library.
  28 +If you're already running Ruby 1.9, this will be unnecessary as JSON is shipped as part of the standard library.
30 29
31 30 ## General Information
32 31
33   -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`).
  32 +Barista transparently compiles CoffeeScript to JavaScript. When a `.coffee` file is changed and the page is refreshed, Barista 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`).
34 33
35   -Barista supports using `therubyracer` when installed or, by default, using either the `node` executable or `jsc` (on OSX) to compile your scripts. There is
36   -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.
  34 +Barista supports using `therubyracer` when installed or, by default, using either the `node` executable or `jsc` (on OS X) to compile your scripts. There is
  35 +no need for you to install the coffee-script executable in Node as having Node itself, or any of the alternatives available, is enough.
37 36
38   -When you want to deploy, you can simple run `rake barista:brew` to force the compilation of all JavaScripts fro the current application.
  37 +When you want to deploy, you can simple run `rake barista:brew` to force the compilation of all JavaScripts for the current application.
39 38
40 39 ## In Practice
41 40
@@ -43,87 +42,82 @@ Barista not only supports compiling all JavaScripts on demand (via `rake barista
43 42 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
44 43 (although it is helpful).
45 44
46   -If you're using Jammit, the precompilation phase (e.g. `rake barista:brew` before running jammit) will make it possible for your application
  45 +If you're using [Jammit](http://documentcloud.github.com/jammit/), the precompilation phase (e.g. `rake barista:brew` before running Jammit) will make it possible for your application
47 46 to automatically bundle not only normal JavaScripts but also your CoffeeScripts.
48 47
49   -To add to your project, simply add:
50   -
51   - gem 'barista', '~> 1.0'
52   -
53   -To your Gemfile and run bundle install.
  48 +To add Barista to your project, simply add `gem 'barista', '~> 1.0'` to your Gemfile and run `bundle install`.
54 49
55   -Please note that for Jammit compatibility, in test and dev mode (by default) it will
  50 +Please note that for Jammit compatibility, in test and development mode (by default) it will
56 51 automatically compile all CoffeeScripts that have changed before rendering the page.
57 52
58   -Barista works out of the box with Rails 3 (and theoretically, Rails 2) - with support for Rack if
  53 +Barista works out of the box with Rails 3 (and theoretically, Rails 2) with support for Rack if
59 54 you're willing to set it up manually. More docs on how to set it up for other platforms
60 55 will be posted in the near future.
61 56
62 57 ## Sinatra
63 58
64   -To use barista with sinatra, you'll need to first require the barista gem in your application
  59 +To use Barista with [Sinatra](http://www.sinatrarb.com/), you'll need to first require the Barista gem in your application
65 60 and then add the following to your application scope (e.g. if you're using a custom class, there):
66 61
67 62 register Barista::Integration::Sinatra
68   -
  63 +
69 64 This will automatically setup the filter as needed, setup a server proxy for the `coffee-script.js`
70 65 file and setup the defaults based on your applications environment
71 66
72   -## Configuration ##
  67 +## Configuration
73 68
74   -Please note that barista lets you configure several options. To do this,
  69 +Please note that Barista lets you configure several options. To do this,
75 70 it's as simple as setting up an initializer with:
76 71
77 72 rails generate barista:install
78   -
  73 +
79 74 Then editing `config/initializers/barista_config.rb`. The options available are:
80 75
81 76 ### Boolean Options
82 77
83   -All of these come in the form of `#option?` (to check it's status), `#option=(value)` (to set it)
  78 +All of these come in the form of `#option?` (to check its status), `#option=(value)` (to set it)
84 79 and `#option!` (to set the value to true):
85 80
86   -* `verbose` - Output debugging error messages. (Defaults to true in test / dev)
87   -* `bare` - Don't wrap the compiled JS in a Closure
88   -* `add_filter` - Automatically add an around filter for processing changes. (Defaults to true in test / dev)
89   -* `add_preamble` - Add a time + path preamble to compiled JS. (Defaults to true in test / dev)
90   -* `exception_on_error` - Raise an exception on compilation errors (defaults to true)
91   -* `embedded_interpreter` - Embeds coffeescript + link to coffee file instead of compiling for include tags and haml filters. (Defaults to true in test / dev)
92   -* `auto_compile` - Automatically compile coffeescript to JS when coffeescript is newer than generated JS file. After turn it off, your server will use generated JS file directly and won't depend on any coffeescript compilers. (Defaults is true)
93   -
  81 +* `verbose` – Output debugging error messages. (Defaults to true in test / dev)
  82 +* `bare` – Don't wrap the compiled JS in a Closure.
  83 +* `add_filter` – Automatically add an around filter for processing changes. (Defaults to true in test / dev)
  84 +* `add_preamble` – Add a time + path preamble to compiled JS. (Defaults to true in test / dev)
  85 +* `exception_on_error` – Raise an exception on compilation errors (defaults to true)
  86 +* `embedded_interpreter` – Embeds coffeescript + link to coffee file instead of compiling for include tags and haml filters. (Defaults to true in test / dev)
  87 +* `auto_compile` – Automatically compile CoffeeScript to JS when CoffeeScript is newer than the generated JS file. After you turn it off, your server will use the generated JS file directly and won't depend on any CoffeeScript compilers. (Defaults is true)
94 88
95 89 ### Path options
96 90
97   -* `root` - the folder path to read coffeescripts from, defaults to app/coffeescripts
98   -* `output_root` - the folder to write them into, defaults to public/javascripts.
99   -* `change_output_prefix!` - method to change the output prefix for a framework.
100   -* `verbose` - whether or not barista will add a preamble to files.
101   -* `js_path` - Path to the pure-javascript compiler.
102   -* `env` - The application environment. (defaults to Rails.env)
103   -* `app_root` - The root of the application.
104   -* `bin_path` - The path to the `node` executable if non-standard and not using therubyracer.
  91 +* `root` – The folder path to read CoffeeScripts from. (Defaults to `app/coffeescripts`.)
  92 +* `output_root` – The folder to write compiled JS files to. (Defaults to `public/javascripts`.)
  93 +* `change_output_prefix!` – Method to change the output prefix for a framework.
  94 +* `verbose` – Whether or not Barista will add a preamble to files.
  95 +* `js_path` – Path to the pure-JavaScript compiler.
  96 +* `env` – The application environment. (Defaults to `Rails.env`.)
  97 +* `app_root` – The application's root path.
  98 +* `bin_path` – The path to the `node` executable if non-standard and not using `therubyracer`.
105 99 * All of the hook methods mentioned below.
106 100
107   -## Frameworks ##
  101 +## Frameworks
108 102
109 103 One of the other main features Barista adds (over other tools) is frameworks similar
110   -to Compass. The idea being, you add coffee scripts at runtime from gems etc. To do this,
111   -in your gem just have a `coffeescript` directory and then in you gem add the following code:
  104 +to Compass. The idea being, you add CoffeeScripts at runtime from gems etc. To do this,
  105 +in your gem just have a `coffeescript` directory and then in your gem add the following code:
112 106
113 107 Barista::Framework.register 'name', 'full-path-to-directory' if defined?(Barista::Framework)
114   -
  108 +
115 109 For an example of this in practice, check out [bhm-google-maps](http://github.com/YouthTree/bhm-google-maps)
116 110 or, the currently-in-development, [shuriken](http://github.com/Sutto/shuriken). The biggest advantage of this
117   -is you can then manage js dependencies using existing tools like bundler.
  111 +is you can then manage JS dependencies using existing tools like Bundler.
118 112
119 113 In your `Barista.configure` block, you can also configure on a per-application basis the output directory
120   -for individual frameworks (e.g. put shuriken into vendor/shuriken, bhm-google-maps into vendor/bhm-google-maps):
  114 +for individual frameworks (e.g. put shuriken into `vendor/shuriken`, bhm-google-maps into `vendor/bhm-google-maps`):
121 115
122 116 Barista.configure do |c|
123 117 c.change_output_prefix! 'shuriken', 'vendor/shuriken'
124 118 c.change_output_prefix! 'bhm-google-maps', 'vendor/bhm-google-maps'
125 119 end
126   -
  120 +
127 121 Alternatively, to prefix all, you can use `Barista.each_framework` (if you pass true, it includes the 'default' framework
128 122 which is your application root).
129 123
@@ -132,17 +126,17 @@ which is your application root).
132 126 c.change_output_prefix! framework.name, "vendor/#{framework.name}"
133 127 end
134 128 end
135   -
136   -## Hooks ##
137 129
138   -Barista lets you hook into the compilation at several stages. Namely:
  130 +## Hooks
  131 +
  132 +Barista lets you hook into the compilation at several stages, namely:
139 133
140 134 * before compilation
141 135 * after compilation
142 136 * after compilation fails
143 137 * after compilation complete
144 138
145   -To hook into these hooks, you can use like so:
  139 +To hook into these hooks, you can do the following:
146 140
147 141 * `Barista.before_compilation { |path| puts "Barista: Compiling #{path}" }`
148 142 * `Barista.on_compilation { |path| puts "Barista: Successfully compiled #{path}" }`
@@ -154,20 +148,21 @@ These allow you to do things such as notify on compilation, automatically
154 148 perform compression post compilation and a variety of other cool things.
155 149
156 150 An excellent example of these hooks in use is [barista\_growl](http://github.com/TrevorBurnham/barista_growl),
157   -by Trevor Burnham - a gem perfect for development purposes that automatically shows growl messages
  151 +by Trevor Burnham — a gem perfect for development purposes that automatically shows Growl messages
158 152 on compilation.
159 153
160 154 # Contributors / Credits
161 155
162 156 The following people have all contributed to Barista:
163 157
164   -* [Xavier Shay](https://github.com/xaviershay) - Added preamble text to generated text in verbose mode.
165   -* [einarmagnus](https://github.com/einarmagnus) - Fixed jruby support.
166   -* [Matt Dean](https://github.com/trabian) - Added `before_full_compilation` and `on_compilation_complete` hooks.
167   -* [Trevor Burnham](https://github.com/TrevorBurnham) - Misc. documentation tweaks and hooks idea.
168   -* [Sean McCullough](https://github.com/mcculloughsean) - Initial switch to support bare (vs. no\_wrap)
169   -* [Ben Atkin](https://github.com/benatkin) - Docs work.
170   -* [Ben Hoskings](https://github.com/benhoskings) Misc fixes, added preamble support.
  158 +* [Xavier Shay](https://github.com/xaviershay) – Added preamble text to generated text in verbose mode.
  159 +* [einarmagnus](https://github.com/einarmagnus) – Fixed jruby support.
  160 +* [Matt Dean](https://github.com/trabian) – Added `before_full_compilation` and `on_compilation_complete` hooks.
  161 +* [Trevor Burnham](https://github.com/TrevorBurnham) – Misc. documentation tweaks and hooks idea.
  162 +* [Sean McCullough](https://github.com/mcculloughsean) – Initial switch to support bare (vs. no\_wrap)
  163 +* [Ben Atkin](https://github.com/benatkin) – Docs work.
  164 +* [Ben Hoskings](https://github.com/benhoskings) – Misc. fixes, added preamble support.
  165 +* [Kim Joar Bekkelund](https://github.com/kjbekkelund) – Docs work.
171 166
172 167 Barista was originally heavily inspired by [Bistro Car](https://github.com/jnicklas/bistro_car), but has taken a few fundamentally
173 168 different approach in a few areas.
@@ -177,7 +172,7 @@ Barista builds upon the awesome [coffee-script](https://github.com/josh/ruby-cof
177 172 It's all possible thanks to [CoffeeScript](https://github.com/jashkenas/coffee-script) by Jeremy Ashkenas.
178 173
179 174 ## Note on Patches/Pull Requests ##
180   -
  175 +
181 176 1. Fork the project.
182 177 2. Make your feature addition or bug fix.
183 178 3. Add tests for it. This is important so I don't break it in a future version unintentionally.

0 comments on commit ef28ac5

Please sign in to comment.
Something went wrong with that request. Please try again.