bottle_rocket

Gem | Source | Documentation

Place a countdown element on your view! It'll be updated by JavaScript.

Use the framework of your choice. A generator is only available for Rails, though.

Installation

Add this line to your application's Gemfile:

gem 'bottle_rocket'

And then execute:

$ bundle

Or install it yourself as:

$ gem install bottle_rocket

Rails 3.1 or greater (with asset pipeline enabled)

Require the javascript file in app/assets/javascripts/application.js:

//= require bottle_rocket

Rails 3.0 (or greater with asset pipeline disabled)

Run the generator:

rails generate bottle_rocket:install

Running the generator will copy 'bottle_rocket.js' over to the public\javascripts directory. Be sure to add bottle_rocket.js to your layout file:

<%= javascript_include_tag 'bottle_rocket' %>

To make Javascript updates work on other frameworks download the file from 'vendor/assets' manually and place it in the corresponding directory.

Usage

 <%= countdown to: Time.now + 28.hours %>

results in a countdown like this:

1d 03 h 59m 59s

or to count down from another time than now:

 <%= countdown to: Time.now - 2.months, from: Time.parse '2012-09-27 01:07:00' %>

The generated html looks like this:

<div class="countdown">
  <span class="unit days">
    <span class="amount-1">1</span>
    <span class="separator">d</span>
  </span>
  <span class="unit hours">
    <span class="amount-0">0</span>
    <span class="amount-3">3</span>
    <span class="separator">h</span>
  </span>
  <span class="unit minutes">
    <span class="amount-5">5</span>
    <span class="amount-9">9</span>
    <span class="separator">m</span>
  </span>
  <span class="unit seconds">
    <span class="amount-5">5</span>
    <span class="amount-9">9</span>
    <span class="separator">s</span>
  </span>
</div>

:units

Select which time units should be displayed. The given order affects the output of the result.

Available keys are:

:days, :hours, :minutes, :seconds, :milliseconds

Default is

[:days, :hours, :minutes, :seconds]

Example with selected units using default options:

 <%= countdown to: Time.now + 2.hours, units: [:minutes, :seconds] %>

results in a countdown like this:

59m 59s

Options

When you want to modify a unit using options supply the unit as a Hash. Additional units supplied as symbols are not affected.

:separators

Define how different time units are separated from each other.

Defaults to:

millenniums:  'MN'
centuries:    'C'
decades:      'D'
years:        'Y'
months:       'M'
weeks:        'w'
days:         'd'
hours:        'h'
minutes:      'm'
seconds:      's'
milliseconds: 'ms'
microseconds: 'µs'
nanoseconds:  'ns'

Example to overwrite the 'days' separator:

<%= countdown to: Time.now + 2.months, units: [{ days: { separator: { title: 'T' } } }] %>

results in a countdown like this:

61 T

To singularize separators on '1' and '-1' pass an additional 'singular' option:

<%= countdown to: Time.now + 1.day, units: [{ days: { separator: { title: 'days', singular: 'day' } } }] %>

results in a countdown like this:

1 day

:leading_zeroes

You can add leading zeroes to units. Nice to have when using a 'clock-like' countdown.

Defaults to

false

Example:

 <%= countdown to: Time.now + 124.minutes, units: [{ hours: { separator: { title: ':' }, leading_zeroes: true } }, { minutes: { separator: { title: ':' }, leading_zeroes: true } }, { seconds: { leading_zeroes: true } }] %>

results in a countdown like this:

02:04:00

:steps

Define how often the countdown should be updated via Javascript.

Possible steps are:

:milliseconds, :seconds, :minutes, :hours, :days

Defaults to the smallest unit value specified (uses seconds when no steps and no units are specified).

Example:

<%= countdown to: Time.now + 1.day, steps: :minutes %>

will update the countdown every minute.

Countup

For a reverse countdown starting at 00:00:00 use the countup method using the same options:

 <%= countup from: Time.now to: Time.now + 1.hour %>

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request