Project: clndr-rails - The Ruby Toolbox

#Clndr Rails Simple way to insert calendar view into your rails app This gem based on CLNDR.js

##Version Gem version have x.x.x.y where x.x.x - CLNDR version y- gem version

##Instalation For basic usage just include clndr-rails gem in Gemfile:

gem 'clndr-rails'

then run

bundle install

Run the Genereator

rails generate clndr:install

This will generate initializer in config/initializer/ with default configurations.

##Usage

Include clndr-rails javascripts and dependency libraries in your app/assets/javascripts/application.js:

//= require jquery
//= require moment
//= require underscore
//= require clndr-rails

and include css if you want use built in templates. Add into app/assets/stylesheets/application.css:

*= require clndr-rails

###Create and use calendar Create calendar is very simple. Just use Clndr.new(:name_of_clndr) in your controller or other else. You can access to Clndr by :name_of_clndr in helpers If you need dynamically change some settings you can assignment your Clndr to instance variable and use config methods, eg:

@simple_clndr = Clndr.new(:simple)
@simple_clndr.start_with_month = Time.now - 1.year

To add event just use .add_event(date,name,*other_data) method.

@simple_clndr.add_event(Time.now,'Event title',description:'You can access to description in your template by <%%= event.location %>.'

Also you can add multiday event:

# add_multiday_event(start_date,end_date,name,*other_data)
@simple_clndr.add_multiday_event('2012-12-1','2012-12-31','December 2012')

If you need use public CLNDR API you can use js var that same your Clnd name (see the generated code).

More about API

###Helpers For display Clndr in your view you can use show_calendar(:clndr_name,html_atributs) helper

<%= show_calendar(:simple, id:'simple-calendar',style:'width:60%')%>

or .view method:

<%= @simple_calendar.view %>

If you plane use Public API you can use link helpers:

next_month_link(calendar_name, text, html_options)
previous_month_link(calendar_name, text, html_options)
next_year_link(calendar_name, text, html_options)
previous_year_link(calendar_name, text, html_options)

In each link helper you can pass empty block or block with true to activate events callback.

###Templates CLNDR.js doesn't generate HTML,it inject data to yours template. If you want quick start you can use built in gem templates. All templates include in Clndr::Template module Now add two templates FULL, MINI and SIMPLE, also you can use BLANK template (it's empty template and CLNDR.js generate simple html) If you need more functionality or want create custom design you must use Clndr::Template.from_html() method. This metod get one argument selector in JQuery's format ('#some-id' or '.some-class') This is example of simple template:

<script type="text/template" id="full-clndr-template">
  <div class="clndr-controls">
    <div class="clndr-previous-button">&lt;</div>
    <div class="clndr-next-button">&gt;</div>
    <div class="current-month"><%= month %> <%= year %></div>
  </div>
  <div class="clndr-grid">
    <div class="days-of-the-week clearfix">
      <% _.each(daysOfTheWeek, function(day) { %>
        <div class="header-day"><%= day %></div>
      <% }); %>
    </div>
    <div class="days">
      <% _.each(days, function(day) { %>
        <div class="<%= day.classes %>" id="<%= day.id %>"><span class="day-number"><%= day.day %></span></div>
      <% }); %>
    </div>
  </div>
</script>

N.B.! If you use ERB like template engine you must use <%% %> in your templates to escape ERB tag

All of the things you have access to in your template:

// an array of day-of-the-week abbreviations,
// shifted as requested using the weekOffset parameter.
daysOfTheWeek: ['S', 'M', 'T', etc...]
// the number of 7-block calendar rows,
// in the event that you want to do some looping with it
numberOfRows: 5
// the days object, documented in more detail above
days: [ { day, classes, id, events, date } ]
// the month name- don't forget that you can do things like
// month.substring(0, 1) and month.toLowerCase() in your template
previousMonth: "April"
month: "May"
nextMonth: "June"
// the year that the calendar is currently focused on
year: "2013"
// all of the events happening this month
eventsThisMonth: [ ],
// all of the events happening last month
eventsLastMonth: [ ],
// all of the events happening next month
eventsNextMonth: [ ],
// anything you passed into the 'extras' property when creating the clndr
extras: { }

For more information about templating read CLNDR docs or CLNDR site

Configure

You can precofig your Clndr by editing config/initializers/clndr.rb file. Code below demonstrate avelible settings and theirs defaults

Clndr.configure do |config|

  # you can configure default template, jast use Clndr::Template::<template_name or from_html(selector)>
  config.template = Clndr::Template::FULL

  # start the week off on Sunday (true), Monday (false)
  # If you are changing the value ensure you are changing the abbreviation below 
  config.week_offset = true

  # An array of day abbreviation labels for the days
  config.days_of_the_week =['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']

  # determines which month to start with using either a date string in format `YYYY-MM-DD`, instance of `Time` class or `nil` (if use nil Clndr will use current month)
  config.start_with_month = Time.now

  # Configure callbacks. Get argument string of js function
  config.click_events do |event|

    # returns a 'target' object containing the DOM element, any events, and the date as a moment.js object.
    event[:click] = 'function(target){}'

    # fired when a user goes forward a month. returns a moment.js object set to the correct month.
    event[:nextMonth]= 'function(mont){}'

    # fired when a user goes back a month. returns a moment.js object set to the correct month.
    event[:previousMonth]= 'function(month){}'

    # fired when a user goes back OR forward a month. returns a moment.js object set to the correct month.
    event[:onMonthChange]= 'function(month){}'

    # fired when a user goes to the current month/year. returns a moment.js object set to the correct month.
    event[:today]= 'function(month){}'
    
  end

  # the target classnames that CLNDR will look for to bind events. these are the defaults.
  config.targets do |target|
    target[:nextButton]='clndr-next-button'
    target[:previousButton]= 'clndr-previous-button'
    target[:todayButton]= 'clndr-today-button'
    target[:day]= 'day'
    target[:empty]='empty'
  end

  # show the numbers of days in months adjacent to the current month (and populate them with their events)
  config.show_adjacent_months= true

  # when days from adjacent months are clicked, switch the current month.
  # fires nextMonth/previousMonth/onMonthChange click callbacks
  config.adjacent_days_change_month= true

  # a callback when the calendar is done rendering. This is a good place to bind custom event handlers.
  config.done_rendering='function(){}' # or nil

  # Set range of dates for calendar
  # By default dont used

  #config.constraints_start= Time.now
  #config.constraints_end= Time.now

  # fixed count of calendar rows
  config.force_six_rows = false

  # setup custom css classes for some calendar elements like day, event etc.
  # by default empty and use default CLNDR css classes
  config.classes do |custom_class|
    custom_class[:today] = "my-today"
    custom_class[:event] = "my-event"
    custom_class[:past]= "my-past"
    custom_class[:lastMonth] = "my-last-month"
    custom_class[:nextMonth] = "my-next-month"
    custom_class[:adjacentMonth] = "my-adjacent-month"
    custom_class[:inactive] = "my-inactive"
  end
end

###i18n You can internationalize calendars by include moment.js locale file

//=require moment/ru

Now date format will be for Russia

This project rocks and uses MIT-LICENSE.

clndr-rails

Development

Runtime

Configure