/xray-rails

A development tool that reveals your UI's bones

Primary LanguageRubyMIT LicenseMIT

Xray

Reveal your UI's bones

The dev tools available to web developers in modern browsers are great. Many of us can't remember what life was like before "Inspect Element". But what we see in the compiled output sent to our browser is often the wrong level of detail - what about visualizing the higher level components of your UI? Controllers, templates, partials, Backbone views, etc.

Xray is the missing link between the browser and your app code. Press cmd+shift+x (Mac) or ctrl+shift+x to reveal an overlay of the files that rendered your UI, and click anything to open the file in your editor. See Xray in action.

Screenshot

Current Support

Xray is intended for Rails 3.1+ and Ruby 1.9.

So far, Xray can reveal:

  • Rails views and partials
  • Backbone View instances if using the asset pipeline
  • Javascript templates if using the asset pipeline with the .jst extension

Installation

Xray depends on jQuery. Backbone is optional.

This gem should only be present during development. Add it to your Gemfile:

group :development do
  gem 'xray-rails'
end

Then bundle and delete your cached assets:

$ bundle && rm -rf tmp/cache/assets

Restart your app, visit it in your browser, and press cmd+shift+x (Mac) or ctrl+shift+x to reveal the overlay.

Note about config.assets.debug

For Xray to insert itself into your views automatically, config.assets.debug = true (Rails' default) must be set in development.rb. If you disabled this because of slow assets in Rails 3.2.13, try this monkey patch instead in an initializer.

Otherwise, you can insert Xray's scripts yourself, for example like so in application.js:

//= require jquery
//= require xray
...
//= require backbone
//= require xray-backbone

Backbone support via xray-backbone is optional.

Configuration

By default, Xray will open files with Sublime Text, looking for /usr/local/bin/subl.

You can configure this to be your editor of choice in Xray's UI, or create ~/.xrayconfig, a YAML file.

Example .xrayconfig:

:editor: '/usr/local/bin/mate'

Or for something more complex, use the $file placeholder.

:editor: "/usr/local/bin/tmux new-window 'vim $file'"

How this works

  • During asset compilation, JS files and templates are modified to contain file path information.
  • A middleware inserts xray.js, xray.css, and the Xray bar into all successful HTML response bodies.
  • When the overlay is shown, xray.js examines the file path information inserted during asset compilation.
  • Another middleware piggybacks the Rails server to respond to requests to open file paths with the user's desired editor.

Contributing

If you have an idea, open an issue and let's talk about it, or fork away and send a pull request.

A laundry list of things to take on:

  • Reveal views from Ember, Knockout, Angular, etc.
  • Overlapping boxes are a problem - parent views in real applications will often be obscured by their children.
  • The current scheme for associating a JS constructor with a filepath is messy and can make stack traces ugly.

Worth noting is that I have plans to solidify xray.js into an API and specification that could be used to aid development in any framework - not just Rails and the asset pipeline.