bullseye/README.md

113 lines
3.4 KiB
Markdown
Raw Normal View History

2012-08-23 12:43:06 +00:00
# Bullseye!
2012-08-23 13:02:55 +00:00
An *extremely quickly written* shoot-from-the-hip implementation of [so-called Garber-Irish DOM-ready execution](http://viget.com/inspire/extending-paul-irishs-comprehensive-dom-ready-execution)
2012-08-23 13:43:15 +00:00
for the Rails asset pipeline. Even provides functionalty for Sass to target those pages! Could work with other Sprockets stuff down the road, too. But for now, it's
2012-08-23 12:43:06 +00:00
pretty married to Rails. Also, needs tests for the exactly four things that it does. Anyone wanna add exactly four Cucumber features?
## Why?
I got sick of on-page JavaScript. Also I like using the Asset Pipeline for what it's actually intended for,
2012-08-23 13:43:15 +00:00
reducing the number of HTTP requests. Finally, targeting pages in Sass should be easy.
2012-08-23 12:43:06 +00:00
## How?
Add the gem:
``` ruby
gem 'bullseye'
```
Replace your `body` tag in your layout with:
``` haml
!!!
%html
= bullseye_body do
= yield
```
That adds `data-action` and `data-controller` attributes to your `body` tag automagically. The controller
comes from `ActionController::Base.controller_path`, so it's the full namespaced underscored path (`Admin::UsersController`
becomes `admin/users`).
Then, in `application.js`:
``` javascript
//= require jquery
2012-08-23 12:43:06 +00:00
//= require bullseye
```
Finally, create some controller/actions-specific files within `app/assets/javascripts/bullseye`
and give them the extenstion `.bullseye`. For instance, target `SitesController#show` in JS and CoffeeScript:
``` javascript
// app/assets/javascripts/bullseye/sites/show.bullseye
alert("I am showing a site");
```
``` coffeescript
# app/assets/javascripts/bullseye/sites/show.bullseye.coffee
alert "I am also showing a site"
```
2012-08-30 15:23:50 +00:00
Want to use the same JavaScript for two actions, say `new` and `edit`? Put both actions in the filename separated by a dash:
``` coffeescript
# app/assets/javascripts/bullseye/sites/new-edit.bullseye.coffee
alert "I appear on both the new and edit actions"
```
2012-08-23 13:43:15 +00:00
Want to target that page in your Sass? Use a little string interpolation and a function that generates a selector:
``` sass
#{bullseye('sites/show')} {
background-color: green;
}
```
2012-08-23 12:43:06 +00:00
Piece of cake.
2012-08-27 13:39:34 +00:00
### Fuzzy search
Plugging Bullseye into an existing app may require making Bullseye work a little harder to target pages.
For instance, you can use Bullseye with ActiveAdmin to target particular actions on models.
However, you can't really add your own `body` tag to their templates. Luckily, they do put in both
the action and controller names in the `class` attribute of the `body` tag.
Create an initializer, like `config/initializers/bullseye.rb` and add the following:
``` ruby
Bullseye.configure do |config|
config.fuzzy_search = %{$('body').get(0).classNames.split(/\\s+/)}
config.css_selector = 'body.:action.:controller'
config.html_tag = { 'class' => ':action :controller' }
end
```
Then you can make your `controller/action.bullseye` files and everything should just work.
## Force the name of the controller/action
For things like error handling in `rescue_from`, you can force the `action` and `controller` that
Bullseye will use:
``` ruby
rescue_from StandardError do |e|
bullseye_target 'application/errors/http_500'
render 'http_500'
end
```
This will resolve to the controller `application/errors` and the action `http_500` in the Bullseye
HTML `body` tag for that page.
2012-08-27 13:39:34 +00:00
## Hacking
_You'll need to install [Penchant](http://github.com/johnbintz/penchant) to mess with the Gemfile
during development.
2012-08-27 13:39:34 +00:00