Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 134 lines (91 sloc) 6.742 kb
55afa0c @Sutto Add framework docs
authored
1 # Barista #
02b7a2d @Sutto Add more barista stuff
authored
2
af37599 @Sutto Let users switch the compilers in a simpler manner, change version nu…
authored
3 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`).
4
5 Barista supports using `therubyracer` when installed or, by default, the node.js version of CoffeeScript via the `coffee` executable.
a96e3b9 @benatkin added an intro with the main reason I use barista
benatkin authored
6
02b7a2d @Sutto Add more barista stuff
authored
7 Barista is very, very similar to [bistro\_car](http://github.com/jnicklas/bistro_car) (infact, credit where credit is due - it shares similar
8 code / is almost a fork).
9
10 The main difference being, it lets you use coffee as you would javascript. Simply put, Write coffee
6497165 @Sutto Add Barista.configure, misc doc changes
authored
11 and place it in `app/coffeescripts` and Barista will automatically serve it as if it was placed in `public/javascripts`
02b7a2d @Sutto Add more barista stuff
authored
12
6497165 @Sutto Add Barista.configure, misc doc changes
authored
13 That is, `app/coffeescripts/demo.coffee` will work for `/javascripts/demo.js`. Even better (and more importantly
02b7a2d @Sutto Add more barista stuff
authored
14 for me), it provides `Barista.compile_all!` which takes all coffee files and compiles them into `public/javascripts`.
15
16 If you're using Jammit, this means you can simple run a rake task (`rake barista:brew` before running jammit) and
17 your coffeescripts will be automatically provided, ready for bundling.
18
762266f @Sutto More docs
authored
19 To add to your project, simply add:
20
9232356 @Sutto Minor version bump
authored
21 gem 'barista', '>= 0.5.0'
762266f @Sutto More docs
authored
22
23 To your Gemfile and run bundle install.
24
d8a0cca Consistently reference 'app/coffeescripts' instead of 'app/scripts'
Trevor Burnham authored
25 As you place .coffee files in app/coffeescripts, it will automatically handle them for you.
762266f @Sutto More docs
authored
26
f6d9273 @Sutto More docs
authored
27 Please note that for Jammit compatibility etc, by default in test and dev mode it will
28 automatically compile all coffeescripts that have changed before rendering the page.
29
6497165 @Sutto Add Barista.configure, misc doc changes
authored
30 Barista require rails 3+ (but patches for Rails 2 will be accepted.)
31
55afa0c @Sutto Add framework docs
authored
32 ## Frameworks ##
33
af37599 @Sutto Let users switch the compilers in a simpler manner, change version nu…
authored
34 One of the other main features Barista adds (over other tools) is frameworks similar
35 to Compass. The idea being, you add coffee scripts at runtime from gems etc. To do this,
36 in your gem just have a `coffeescript` directory and then in you gem add the following code:
55afa0c @Sutto Add framework docs
authored
37
38 Barista::Framework.register 'name', 'full-path-to-directory' if defined?(Barista::Framework)
39
40 For an example of this in practice, check out [bhm-google-maps](http://github.com/YouthTree/bhm-google-maps)
83f23b6 @Sutto Readme info
authored
41 or, the currently-in-development, [shuriken](http://github.com/Sutto/shuriken). The biggest advantage of this
42 is you can then manage js dependencies using existing tools like bundler.
55afa0c @Sutto Add framework docs
authored
43
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
44 In your `Barista.configure` block, you can also configure on a per-application basis the output directory
45 for individual frameworks (e.g. put shuriken into vendor/shuriken, bhm-google-maps into vendor/bhm-google-maps):
46
91a269d @Sutto WIP implementation of hooks
authored
47 Barista.configure do |c|
48 c.change_output_prefix! 'shuriken', 'vendor/shuriken'
49 c.change_output_prefix! 'bhm-google-maps', 'vendor/bhm-google-maps'
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
50 end
51
52 Alternatively, to prefix all, you can use `Barista.each_framework` (if you pass true, it includes the 'default' framework
53 which is your application root).
54
91a269d @Sutto WIP implementation of hooks
authored
55 Barista.configure do |c|
56 c.each_framework do |framework|
57 c.change_output_prefix! framework.name, "vendor/#{framework.name}"
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
58 end
59 end
91a269d @Sutto WIP implementation of hooks
authored
60
61 ## Hooks ##
62
63 Barista lets you hook into the compilation at several stages. Namely:
64
65 * before compilation
66 * after compilation
67 * after compilation fails
8aeb5be Updated documentation
Matt Dean authored
68 * after compilation complete
91a269d @Sutto WIP implementation of hooks
authored
69
70 To hook into these hooks, you can use like so:
71
72 * `Barista.before_compilation { |path| puts "Barista: Compiling #{path}" }`
73 * `Barista.on_compilation { |path| puts "Barista: Successfully compiled #{path}" }`
fd82e0f @Sutto Update to support hooks
authored
74 * `Barista.on_compilation_with_warning { |path, output| puts "Barista: Compilation of #{path} had a warning:\n#{output}" }`
91a269d @Sutto WIP implementation of hooks
authored
75 * `Barista.on_compilation_error { |path, output| puts "Barista: Compilation of #{path} failed with:\n#{output}" }`
8aeb5be Updated documentation
Matt Dean authored
76 * `Barista.on_compilation_complete { puts "Barista: Successfully compiled all files" }`
91a269d @Sutto WIP implementation of hooks
authored
77
78 These allow you to do things such as notify on compilation, automatically
79 perform compression post compilation and a variety of other cool things.
85060b1 @Sutto Bump version, allow you to change prefixes for frameworks
authored
80
4bc4b7c @Sutto Add barista_growl to the README
authored
81 An excellent example of these hooks in use is [barista\_growl](http://github.com/TrevorBurnham/barista_growl),
82 by Trevor Burnham - a gem perfect for development purposes that automatically shows growl messages
83 on compilation.
84
6497165 @Sutto Add Barista.configure, misc doc changes
authored
85 ## Configuration ##
86
87 Please note that barista lets you configure several options. To do this,
88 it's as simple as setting up an initializer with:
89
a3f160e @Sutto Add documentation updates
authored
90 rails generate barista:install
6497165 @Sutto Add Barista.configure, misc doc changes
authored
91
92 Then editing `config/initializers/barista_config.rb`.
93
94 Currently available options are:
95
a3f160e @Sutto Add documentation updates
authored
96 * `root` - the folder path to read coffeescripts from, defaults to app/coffeescripts
97 * `output_root` - the folder to write them into, defaults to public/javascripts.
98 * `no_wrap` and `bare` - stop coffee from automatically wrapping JS in a closure.
99 * `change_output_prefix!` - method to change the output prefix for a framework.
100 * All of the hooks mentioned above.
101 * `verbose` - whether or not barista will add a preamble to files.
102 * `compiler` - One of `:native` or `:node`, to force the compiler version.
103 * `compiler_klass` - A custom compiler class.
104 * `js_path` - Path to the pure-javascript compiler
105
106 # Contributors / Credits
107
108 The following people have all contributed to Barista:
109
110 * [Xavier Shay](https://github.com/xaviershay) - Added preamble text to generated text in verbose mode.
111 * [einarmagnus](https://github.com/einarmagnus) - Fixed jruby support.
112 * [Matt Dean](https://github.com/trabian) - Added `before_full_compilation` and `on_compilation_complete` hooks.
113 * [Trevor Burnham](https://github.com/TrevorBurnham) - Misc. documentation tweaks and hooks idea.
114 * [Sean McCullough](https://github.com/mcculloughsean) - Initial switch to support bare (vs. no\_wrap)
115 * [Ben Atkin](https://github.com/benatkin) - Docs work.
116
117 Barista was originally heavily inspired by [Bistro Car](https://github.com/jnicklas/bistro_car), but taking a fundamentally
118 different approach in a few areas.
119
120 The Native JavaScript compiler was heavily inspired by and based on [Sam Stephenson's](https://github.com/sstephenson) fork of
121 the ruby-coffee-script gem. All credit for the idea goes to him and the code is based on his simple approach.
6497165 @Sutto Add Barista.configure, misc doc changes
authored
122
870add6 @Sutto Contributor details for Barista
authored
123 ## Note on Patches/Pull Requests ##
124
125 1. Fork the project.
126 2. Make your feature addition or bug fix.
127 3. Add tests for it. This is important so I don't break it in a future version unintentionally.
128 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)
129 5. Send me a pull request. Bonus points for topic branches.
130
131 ## Copyright ##
132
a96e3b9 @benatkin added an intro with the main reason I use barista
benatkin authored
133 Copyright (c) 2010 Darcy Laycock. See LICENSE for details.
Something went wrong with that request. Please try again.