Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Incremental rollout of code with server-side and client-side support
Ruby JavaScript
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
db
lib
rails
spec
.gitignore
Gemfile
README.md
Rakefile
changelog.md
sapling.gemspec

README.md

Sapling Gem

Sapling lets you seed your new features to just a few users at a time. You can change which and how many users are seeded for a feature dynamically by updating the database via the Sapling API. Core features are the ability to seed a feature for specific users and/or a percentage of users.

Heritage

This is a port of the rollout gem for use with ActiveRecord instead of Redis. We dropped the groups functionality, but otherwise we mirrored the API.

Setup

Add a route to your routes file. Feel free to change the 'sapling/stylesheet.css' to whatever you want.

map.sapling_script 'sapling/script.js', :controller => 'sapling', :action => 'script'

After including your javascript library, add this:

<%= javascript_include_tag sapling_script_path, :id => 'sapling_script' %>

Run the db/create.sql file to create the sapling_settings table on your DB

Ensure you have a current_user method to your application controller, which returns a user object, or nil if no active user.

class ApplicationController < ActionController::Base
  ...
  def current_user
    # Return your current user
    # This is already done for you in Devise, RestfulAuthentication, and other authentication lib
  end
  ...
end

For a given feature space_chat,

Server-side Usage

To check if a feature is enabled for a user in rails controllers or views: use

sapling.active?(:space_chat [, :user => the current user])

Note: sapling will automatically populate the user argument by calling current_user

To get the css classes the javascript adds to the HTML element for a feature:

sapling.css_class(:space_chat)
sapling.css_toggle_class(:space_chat)

To enable a feature for a specific user, in the rails console:

Sapling::ActiveRecord.new.activate_user(:space_chat, space_admin)

To disable a feature for a specific user, in the rails console:

Sapling::ActiveRecord.new.deactivate_user(:space_chat, space_admin)

To enable a feature for 50% of the users, in the rails console:

Sapling::ActiveRecord.new.activate_percentage(:space_chat, 50)`

To disable a feature activated for anyone but individually-activated users, in the rails console:

Sapling::ActiveRecord.new.deactivate_percentage(:space_chat)

Note: Individually-activated users are always activated, regardless of the percentage setting. A deactivated user may still have access to a feature if they fall within an active percentage.

Custom Feature-Active Tests

You can optionally inject your own code for testing if a feature is active. In rails, just added methods of the following form to your ApplicationController:

# Example: override feature-active? for feature :new_homepage
#
# options:
#   :feature => object of type Sapling::Feature
#       (current settings for the feature from the database)
#   :active => true if the feature would be active without the override
#
# remaining options are those passed to 'sapling.active?'
#   :user => user to test for feature-active
#   :context_id => Integer
#
# return true if the feature is active.
def new_homepage_active?(options={})
  # your test here
end

Note If you are using Sapling manually, when you create a Sapling instance, you can pass in an any object which responds to "current_user" and implements zero or more of your feature-active overrides.

Client-side Usage

Sapling include a javascript helper which adds and removes classes on the HTML element for a given user, based upon the features available to that user.

Given the feature space_chat, if it is enabled for the given user, the html root will get the class sapling_feature_space_chat_on. If disabled for the given user, the class will be sapling_feature_space_chat_off.

To retrieve the class name for a given feature, you can use sapling.css_class(feature) and sapling.css_toggle_class(feature, on? (boolean) ) in your ERB files.

Using the client-side tools, you can define CSS classes which will be visible/invisible when a feature is enabled/disabled. For example:

CSS:

/* Chat Defaults to being hidden for everyone */
.sapling_feature_chat.enabled {
  display: none;
}
.sapling_feature_chat.disabled {
  display: block;
}

/* When chat is enabled, we hide the disabled container, and show the enabled container */
html.sapling_feature_chat_on .sapling_feature_chat.enabled {
  display: block;
}
html.sapling_feature_chat_on .sapling_feature_chat.disabled {
  display: none;
}

ERB:

<div class="<%= sapling.css_class(:chat) %> enabled">
  REJOICE - SPIFF CHAT ENABLED FOR YOU
</div>

<div class="<%= sapling.css_class(:chat) %> disabled">
  DESPAIR - SPIFF CHAT NOT ENABLED FOR YOU
</div>

Note Currently, the javascript generated depends on MooTools being loaded first.

TODO

  • Rails 3 compatibility
  • Remove mootools dependency
  • Database migration generator
Something went wrong with that request. Please try again.