/recurring_select

A gem for adding selectors for setting recurring events.

Primary LanguageRubyMIT LicenseMIT

Recurring Select

Build Status Code Climate

This gem adds selectors and helpers for working with recurring schedules in a Rails app. It uses ice_cube recurring scheduling gem.

Created by the Jobber team for Jobber, the leading business management tool for field service companies.

Check out the live demo (code in spec/dummy folder)

Usage

Basic selector:

Add the gem to your Gemfile:

gem 'recurring_select'

Require Assets

Desktop Interface:

  • application.js: //= require recurring_select
  • application.css: //= require recurring_select

jQuery Mobile Interface:

  • application.js: //= require jquery-mobile-rs
  • application.css: //= require jquery-mobile-rs

Form Helper

In the form view call the helper:

<%= f.select_recurring :recurring_rule_column %>

Options

f.select_recurring :current_existing_rule, [
  IceCube::Rule.weekly.day(:monday, :wednesday, :friday),
  IceCube::Rule.monthly.day_of_month(-1)
]

Use :allow_blank for a "not recurring" option:

  f.select_recurring :current_existing_rule, nil, :allow_blank => true

Use :data attribute to position the recurring select dialog inline (after the select input):

  f.select_recurring :current_existing_rule, nil, { :allow_blank => true }, { data: { recurring_select_position: 'inline' } }

Additional Helpers

Recurring Select also comes with helpers for parsing the parameters when they hit your application.

You can send the column into the is_valid_rule? method to check the validity of the input.

RecurringSelect.is_valid_rule?(possible_rule)

There is also a dirty_hash_to_rule method for sanitizing the inputs for IceCube. This is sometimes needed if you're receiving strings, fixed numbers, strings vs symbols, etc.

RecurringSelect.dirty_hash_to_rule(params)

I18n

Recurring Select is I18n aware

You can create a locale file like this:

en:
  recurring_select:
    not_recurring: "- not recurring -"
    change_schedule: "Change schedule..."
    set_schedule: "Set schedule..."
    new_custom_schedule: "New custom schedule..."
    custom_schedule: "Custom schedule..."
    or: or

You have to translate JavaScript texts too by including the locale file in your assets manifest. Only French and English are supported for the moment.

//= require recurring_select/en
//= require recurring_select/fr

For other languages include a JavaScript file like this:

$.fn.recurring_select.texts = {
  locale_iso_code: "fr"
  repeat: "Repeat"
  frequency: "Frequency"
  daily: "Daily"
  weekly: "Weekly"
  monthly: "Monthly"
  yearly: "Yearly"
  every: "Every"
  days: "day(s)"
  weeks_on: "week(s) on"
  months: "month(s)"
  years: "year(s)"
  first_day_of_week: 1
  day_of_month: "Day of month"
  day_of_week: "Day of week"
  cancel: "Cancel"
  ok: "OK"
  days_first_letter: ["S", "M", "T", "W", "T", "F", "S"]
  order: ["1st", "2nd", "3rd", "4th", "5th", "Last"]
}

Options include:

$.fn.recurring_select.options = {
  monthly: {
    show_week: [true, true, true, true, false, false] //display week 1, 2 .... Last
  }
}

Testing and Development

The dummy app uses a Postgres database recurring_select_development. To get setup:

bundle
rake db:create

Start the dummy server for clicking around the interface:

rails s

Use Guard and RSpec for all tests. I'd love to get Jasmine running also, but haven't had time yet.

Tests can be ran against different versions of Rails like so:

BUNDLE_GEMFILE=spec/gemfiles/Gemfile.rails-4.0.x bundle install
BUNDLE_GEMFILE=spec/gemfiles/Gemfile.rails-4.0.x bundle exec rspec spec

Feel free to open issues or send pull requests.

Licensing

This project rocks and uses MIT-LICENSE.