songkick/dolphin

= Dolphin

{<img src="https://secure.travis-ci.org/songkick/dolphin.png?branch=master" alt="Build Status" />}[http://travis-ci.org/songkick/dolphin]
{<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/songkick/dolphin]

Dolphin is a feature flipper, as Rails plugin. Use it to flip areas of your app on your off, based on pre-defined conditions.

== Installation

  git submodule add git://github.com/grillpanda/dolphin.git vendor/plugins/dolphin
  git submodule init
  git submodule update

Or

  script/plugin install git://github.com/grillpanda/dolphin.git

== Configuration

=== Define your flippers

You’ll need to add some flippers. These are called later by the feature helper and determine whether a feature should be visible or not.

Dolphin has the flippers <b><tt>enabled</tt></b> and <b><tt>disabled</tt></b> baked in. These return <tt>true</tt> and <tt>false</tt> respectively.

In <b><tt>config/initializers/dolphin.rb</tt></b>:
  Dolphin.configure do
    flipper(:admin) { logged_in_user.admin? }
    flipper(:local) { request.env['HTTP_X_FORWARDED_FOR'] == '127.0.0.1' }
  end

Note that whatever methods or variables you use in your flipper blocks will need to be available to the scope in which you include <tt>Dolphin::Helper</tt>.

=== Add some features

Add <b><tt>config/dolphin/features.yml</tt></b> and configure some features. You need to provide the name of your feature, and the name of the flipper it should use.

  local_feature: local
  disabled_feature: off

<b>Important</b>: If you want to remember your feature settings between deploys, store <tt>features.yml</tt> somewhere that will survive them and link to it.

=== Include the helper

  module ApplicationController < ActionController::Base
    include Dolphin::Helper
  end

  module ApplicationHelper
    include Dolphin::Helper
  end

== Usage

=== Displaying a feature, or not

Use your super-secret mondo-feature with the <tt>feature</tt> helper method.

  <% feature :local_feature do %>
    <h1>MMM, TUNA</h1>
  <% end %>

Dolphin will call the flipper associated with the feature and run what’s in the feature block if the result is truthy. If a feature or a flipper isn’t found, or there’s an error with the flipper, whatever’s in the feature block won’t be run.

You can pass a partial to the <tt>feature</tt> helper instead of a block.

  <%= feature(:local_feature, :partial => 'tuna', :collection => @tuna) %>

You can check the availability of a feature using <tt>feature?</tt>

  <%= link_to('TUNA FISH', tuna_path) if feature?(:tuna) %>

== Considerations

Dolphin stores it’s feature configuration on disk, and needs to read it once per request. This hasn’t been a performance issue for us, but it’s something to keep in mind.

== License

Copyright (c) 2010 Matt Johnson, released under the MIT license