Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 266 lines (177 sloc) 14.918 kb
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
1 # Barista
02b7a2d @Sutto Add more barista stuff
authored
2
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
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
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
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/).
af37599 @Sutto Let users switch the compilers in a simpler manner, change version numbe...
authored
5
e47952a @Sutto Add a rewritten getting started section to the readme
authored
6 As an added bonus, Barista also gives:
7
8 * Automatic support for a `:coffeescript` filter in [Haml](http://haml-lang.com/) (when Haml is loaded before Barista) — automatically converting inline CoffeeScript to JavaScript for you.
9 * Where possible, support for `coffeescript_include_tag` and `coffeescript_tag`.
10 * When possible, instead of pre-compiling in development and test modes, Barista will embed CoffeeScript in the page for you.
11 * Support for Heroku via [therubyracer-heroku](https://github.com/aler/therubyracer-heroku) and either pre-compiled JS or, optionally, a lightweight Rack app that generates on request.
12
13 ## Getting Started
14
15 Out of the box, Barista has semi-automatic support for Rails 3.0, Rails 2 (currently untested) and Sinatra. With a minimal amount of effort, you can also make it work in any Rack-based framework.
16
17 ### Rails 3
a96e3b9 @benatkin added an intro with the main reason I use barista
benatkin authored
18
e47952a @Sutto Add a rewritten getting started section to the readme
authored
19 Adding Barista to your Rails 3 application should as simple as adding two gems to your `Gemfile`, and running two commands. To get started, open up your `Gemfile` and add the following:
20
21 gem "json" # Only needed if on Ruby 1.8 / a platform that ships without JSON
22 gem "barista"
23
24 Next, you'll need to run the the following:
25
26 bundle install
27 rails g barista:install
28
29 This will install the gem into your application and will generate a file in `config/initializers/barista_config.rb` that contains a set of options to configure Barista options.
02b7a2d @Sutto Add more barista stuff
authored
30
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
31 Place your CoffeeScripts in `app/coffeescripts` and Barista will automatically compile them on change into `public/javascripts`.
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
32
e47952a @Sutto Add a rewritten getting started section to the readme
authored
33 ### Rails 2
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
34
e47952a @Sutto Add a rewritten getting started section to the readme
authored
35 Much like on Rails 3, Barista supports deep integration into Rails 2. The only thing missing (that is currently supported in the Rails 3 version) is built in support for generating a config file. If you're using bundler in your application, all you need to do is add:
36
37 gem "json" # Only needed if on Ruby 1.8 / a platform that ships without JSON
38 gem "barista"
0d85a19 @brainopia Update readme to reference using rake tasks with rails 2
brainopia authored
39
e47952a @Sutto Add a rewritten getting started section to the readme
authored
40 To your `Gemfile`. If you're not using bundler, doing `gem install json barista` and requiring barista both in your application should be enough to get you started.
41
42 If you wish to change the barista configuration, take a look at the [Rails 3 initializer](https://github.com/Sutto/barista/blob/master/lib/generators/barista/install/templates/initializer.rb) and modify it to suite your application as needed.
43
0d85a19 @brainopia Update readme to reference using rake tasks with rails 2
brainopia authored
44 If you wish to use barista tasks with rails 2 project, add
45
5a98cc5 @topfunky Use correct call for loading Barista tasks under Rails 2.
topfunky authored
46 load "barista/tasks/barista.rake"
0d85a19 @brainopia Update readme to reference using rake tasks with rails 2
brainopia authored
47
48 To your `Rakefile`.
49
e47952a @Sutto Add a rewritten getting started section to the readme
authored
50 ### Sinatra
51
52 Adding Barista to a Sinatra application is a relatively straight forward affair. Like in Rails 2 and Rails 3, you first need to add and require the barista gem and (optionally, the json gem). Unlike Rails 2 and 3 (which set it up automatically), you must also register the extension in your application. So, in the scope of your app (either the top level scope or the `Sinatra::Application` subclass you're using), you then need to simple add:
53
54 register Barista::Integration::Sinatra
55
56 Which will automatically set up the Barista environment and other similar details (e.g. the automatic compilation filter). Since you don't have initializers like you do in Rails, you
57 can then simply run your `Barista.configure` call and block anywhere before your application starts serving requests.
58
59 ### Other Rack-based Frameworks
60
61 Lastly, even though it is built out of the box to support Rails and Sinatra, Barista can also be used with any Rack-based framework. For proper integration, several things must be done. Namely, wherever you declare your middleware (e.g. in a `config.ru` file), you should register the two pieces of middleware barista uses. `Barista::Filter` should only be registered when
62 Barista performs compilation (e.g. in development mode) and `Barista::Server::Proxy` should be registered if you want it to support automatic serving of a `coffeescript.js` file and / or
63 on the fly (versus pre-request compilation) of CoffeeScripts.
64
65 For example, your `config.ru` may look like:
66
67 # Setup goes here...
68 use Barista::Filter if Barista.add_filter?
69 use Barista::Server::Proxy
70 run MyRackApplication
0d85a19 @brainopia Update readme to reference using rake tasks with rails 2
brainopia authored
71
e47952a @Sutto Add a rewritten getting started section to the readme
authored
72 Next, you need to configure barista anywhere before your the above code is run. e.g by adding the following immediatly preceeding it:
73
74 # Barista (for CoffeeScript Support)
75 Barista.app_root = root
76 Barista.root = File.join(root, 'coffeescripts')
77 Barista.setup_defaults
78 barista_config = root + '/barista_config.rb'
79 require barista_config if File.exist?(barista_config)
0d85a19 @brainopia Update readme to reference using rake tasks with rails 2
brainopia authored
80
e47952a @Sutto Add a rewritten getting started section to the readme
authored
81 Hence, if you'e using, for example, [serve](https://github.com/jlong/serve) users should have a `config.ru` that looks similar to [this example](https://github.com/YouthTree/site-design/blob/master/config.ru).
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
82
c30119c @Sutto Add more notes to the readme
authored
83 ### A Quick Note on the JSON Gem
84
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
85 Barista indirectly requires the json gem via the coffee-script gem, but it isn't listed as a dependency for very
c30119c @Sutto Add more notes to the readme
authored
86 good reasons. If you encounter errors relating to `require 'json'`, Then you'll need to add either `gem 'json'`
87 or `gem 'json_pure'` to your Gemfile.
88
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
89 If you're already running Ruby 1.9, this will be unnecessary as JSON is shipped as part of the standard library.
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
90
91 ## General Information
92
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
93 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`).
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
94
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
95 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
96 no need for you to install the coffee-script executable in Node as having Node itself, or any of the alternatives available, is enough.
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
97
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
98 When you want to deploy, you can simple run `rake barista:brew` to force the compilation of all JavaScripts for the current application.
75b217f @Sutto Prepare to bump the gem version, start updating the docs
authored
99
1fff5db @Sutto More docs
authored
100 ## In Practice
02b7a2d @Sutto Add more barista stuff
authored
101
1fff5db @Sutto More docs
authored
102 Barista not only supports compiling all JavaScripts on demand (via `rake barista:brew` as above, or `Barista.compile_all!`) but it
103 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
104 (although it is helpful).
02b7a2d @Sutto Add more barista stuff
authored
105
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
106 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
1fff5db @Sutto More docs
authored
107 to automatically bundle not only normal JavaScripts but also your CoffeeScripts.
02b7a2d @Sutto Add more barista stuff
authored
108
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
109 To add Barista to your project, simply add `gem 'barista', '~> 1.0'` to your Gemfile and run `bundle install`.
762266f @Sutto More docs
authored
110
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
111 Please note that for Jammit compatibility, in test and development mode (by default) it will
1fff5db @Sutto More docs
authored
112 automatically compile all CoffeeScripts that have changed before rendering the page.
f6d9273 @Sutto More docs
authored
113
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
114 Barista works out of the box with Rails 3 (and theoretically, Rails 2) — with support for Rack if
1fff5db @Sutto More docs
authored
115 you're willing to set it up manually. More docs on how to set it up for other platforms
116 will be posted in the near future.
6497165 @Sutto Add Barista.configure, misc doc changes
authored
117
60d87fb @Sutto Updated docs on the barista config
authored
118 ## Sinatra
119
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
120 To use Barista with [Sinatra](http://www.sinatrarb.com/), you'll need to first require the Barista gem in your application
60d87fb @Sutto Updated docs on the barista config
authored
121 and then add the following to your application scope (e.g. if you're using a custom class, there):
122
123 register Barista::Integration::Sinatra
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
124
60d87fb @Sutto Updated docs on the barista config
authored
125 This will automatically setup the filter as needed, setup a server proxy for the `coffee-script.js`
126 file and setup the defaults based on your applications environment
127
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
128 ## Configuration
db73b47 @Sutto More docs!
authored
129
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
130 Please note that Barista lets you configure several options. To do this,
db73b47 @Sutto More docs!
authored
131 it's as simple as setting up an initializer with:
132
133 rails generate barista:install
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
134
db73b47 @Sutto More docs!
authored
135 Then editing `config/initializers/barista_config.rb`. The options available are:
136
137 ### Boolean Options
138
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
139 All of these come in the form of `#option?` (to check its status), `#option=(value)` (to set it)
db73b47 @Sutto More docs!
authored
140 and `#option!` (to set the value to true):
141
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
142 * `verbose` – Output debugging error messages. (Defaults to true in test / dev)
143 * `bare` – Don't wrap the compiled JS in a Closure.
144 * `add_filter` – Automatically add an around filter for processing changes. (Defaults to true in test / dev)
145 * `add_preamble` – Add a time + path preamble to compiled JS. (Defaults to true in test / dev)
146 * `exception_on_error` – Raise an exception on compilation errors (defaults to true)
147 * `embedded_interpreter` – Embeds coffeescript + link to coffee file instead of compiling for include tags and haml filters. (Defaults to true in test / dev)
148 * `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)
db73b47 @Sutto More docs!
authored
149
150 ### Path options
151
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
152 * `root` – The folder path to read CoffeeScripts from. (Defaults to `app/coffeescripts`.)
153 * `output_root` – The folder to write compiled JS files to. (Defaults to `public/javascripts`.)
154 * `change_output_prefix!` – Method to change the output prefix for a framework.
151a5a0 @Sutto Expose the output_root option
authored
155 * `change_output_root!` - Method to change the output root for a given framework.
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
156 * `verbose` – Whether or not Barista will add a preamble to files.
157 * `js_path` – Path to the pure-JavaScript compiler.
158 * `env` – The application environment. (Defaults to `Rails.env`.)
159 * `app_root` – The application's root path.
160 * `bin_path` – The path to the `node` executable if non-standard and not using `therubyracer`.
db73b47 @Sutto More docs!
authored
161 * All of the hook methods mentioned below.
162
a9294b2 @dblock Added support for a dynamic preamble.
dblock authored
163 ### Custom Preamble
164
165 You can generate a custom preamble using a code block. For example, you can replace the location of the original `.coffee` file by a relative one to `Rails.root`.
166
167 Barista.add_preamble do |location|
168 "/* : DO NOT MODIFY - compiled from #{Pathname.new(location).relative_path_from(Rails.root).to_s}\n\n"
169 end
170
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
171 ## Frameworks
55afa0c @Sutto Add framework docs
authored
172
af37599 @Sutto Let users switch the compilers in a simpler manner, change version numbe...
authored
173 One of the other main features Barista adds (over other tools) is frameworks similar
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
174 to Compass. The idea being, you add CoffeeScripts at runtime from gems etc. To do this,
175 in your gem just have a `coffeescript` directory and then in your gem add the following code:
55afa0c @Sutto Add framework docs
authored
176
177 Barista::Framework.register 'name', 'full-path-to-directory' if defined?(Barista::Framework)
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
178
55afa0c @Sutto Add framework docs
authored
179 For an example of this in practice, check out [bhm-google-maps](http://github.com/YouthTree/bhm-google-maps)
83f23b6 @Sutto Readme info
authored
180 or, the currently-in-development, [shuriken](http://github.com/Sutto/shuriken). The biggest advantage of this
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
181 is you can then manage JS dependencies using existing tools like Bundler.
55afa0c @Sutto Add framework docs
authored
182
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
183 In your `Barista.configure` block, you can also configure on a per-application basis the output directory
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
184 for individual frameworks (e.g. put shuriken into `vendor/shuriken`, bhm-google-maps into `vendor/bhm-google-maps`):
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
185
91a269d @Sutto WIP implementation of hooks
authored
186 Barista.configure do |c|
187 c.change_output_prefix! 'shuriken', 'vendor/shuriken'
188 c.change_output_prefix! 'bhm-google-maps', 'vendor/bhm-google-maps'
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
189 end
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
190
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
191 Alternatively, to prefix all, you can use `Barista.each_framework` (if you pass true, it includes the 'default' framework
192 which is your application root).
193
91a269d @Sutto WIP implementation of hooks
authored
194 Barista.configure do |c|
195 c.each_framework do |framework|
196 c.change_output_prefix! framework.name, "vendor/#{framework.name}"
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
197 end
198 end
91a269d @Sutto WIP implementation of hooks
authored
199
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
200 ## Hooks
201
202 Barista lets you hook into the compilation at several stages, namely:
91a269d @Sutto WIP implementation of hooks
authored
203
204 * before compilation
205 * after compilation
206 * after compilation fails
8aeb5be Updated documentation
Matt Dean authored
207 * after compilation complete
91a269d @Sutto WIP implementation of hooks
authored
208
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
209 To hook into these hooks, you can do the following:
91a269d @Sutto WIP implementation of hooks
authored
210
211 * `Barista.before_compilation { |path| puts "Barista: Compiling #{path}" }`
212 * `Barista.on_compilation { |path| puts "Barista: Successfully compiled #{path}" }`
fd82e0f @Sutto Update to support hooks
authored
213 * `Barista.on_compilation_with_warning { |path, output| puts "Barista: Compilation of #{path} had a warning:\n#{output}" }`
91a269d @Sutto WIP implementation of hooks
authored
214 * `Barista.on_compilation_error { |path, output| puts "Barista: Compilation of #{path} failed with:\n#{output}" }`
8aeb5be Updated documentation
Matt Dean authored
215 * `Barista.on_compilation_complete { puts "Barista: Successfully compiled all files" }`
91a269d @Sutto WIP implementation of hooks
authored
216
217 These allow you to do things such as notify on compilation, automatically
218 perform compression post compilation and a variety of other cool things.
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
219
4bc4b7c @Sutto Add barista_growl to the README
authored
220 An excellent example of these hooks in use is [barista\_growl](http://github.com/TrevorBurnham/barista_growl),
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
221 by Trevor Burnham — a gem perfect for development purposes that automatically shows Growl messages
4bc4b7c @Sutto Add barista_growl to the README
authored
222 on compilation.
223
4fa48bb @linjunpop added capistrano recipe
linjunpop authored
224 ## Deployment
225
226 Add `require 'barisa/capistrano'` to your `deploy.rb`.
227
a3f160e @Sutto Add documentation updates
authored
228 # Contributors / Credits
229
230 The following people have all contributed to Barista:
231
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
232 * [Xavier Shay](https://github.com/xaviershay) – Added preamble text to generated text in verbose mode.
233 * [einarmagnus](https://github.com/einarmagnus) – Fixed jruby support.
234 * [Matt Dean](https://github.com/trabian) – Added `before_full_compilation` and `on_compilation_complete` hooks.
235 * [Trevor Burnham](https://github.com/TrevorBurnham) – Misc. documentation tweaks and hooks idea.
236 * [Sean McCullough](https://github.com/mcculloughsean) – Initial switch to support bare (vs. no\_wrap)
237 * [Ben Atkin](https://github.com/benatkin) – Docs work.
238 * [Ben Hoskings](https://github.com/benhoskings) – Misc. fixes, added preamble support.
239 * [Kim Joar Bekkelund](https://github.com/kjbekkelund) – Docs work.
2f83e61 @Sutto Updated contributors
authored
240 * [Jeffrey ODell](https://github.com/jodell) - Fixed an issue with messages during autocompile.
241 * [Paul McMahon](https://github.com/pwim) - Fixed a typo.
242 * [Ravil Bayramgalin](https://github.com/brainopia) - Fixes for Rakefiles on Rails 2.
243 * [Daniel Doubrovkine](https://github.com/dblock) - Dynamic Preambles, Making it easier to spec the application.
a3f160e @Sutto Add documentation updates
authored
244
db73b47 @Sutto More docs!
authored
245 Barista was originally heavily inspired by [Bistro Car](https://github.com/jnicklas/bistro_car), but has taken a few fundamentally
a3f160e @Sutto Add documentation updates
authored
246 different approach in a few areas.
247
db73b47 @Sutto More docs!
authored
248 Barista builds upon the awesome [coffee-script](https://github.com/josh/ruby-coffee-script) gem.
249
250 It's all possible thanks to [CoffeeScript](https://github.com/jashkenas/coffee-script) by Jeremy Ashkenas.
6497165 @Sutto Add Barista.configure, misc doc changes
authored
251
2f83e61 @Sutto Updated contributors
authored
252 If I've missed you're name and you've contributed to Barista, please let me know and I'll add you to the list (or
253 fork this document and send a pull request).
254
870add6 @Sutto Contributor details for Barista
authored
255 ## Note on Patches/Pull Requests ##
ef28ac5 @kjbekkelund Cleaned up the docs to make them more readable.
kjbekkelund authored
256
870add6 @Sutto Contributor details for Barista
authored
257 1. Fork the project.
258 2. Make your feature addition or bug fix.
259 3. Add tests for it. This is important so I don't break it in a future version unintentionally.
260 4. Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
261 5. Send me a pull request. Bonus points for topic branches.
262
263 ## Copyright ##
264
a96e3b9 @benatkin added an intro with the main reason I use barista
benatkin authored
265 Copyright (c) 2010 Darcy Laycock. See LICENSE for details.
Something went wrong with that request. Please try again.