README.md
[](https://codeclimate.com/github/navinspm/clndr-rails)[](https://badge.fury.io/rb/clndr-rails)
#Clndr Rails
Simple way to insert calendar view into your rails app
This gem based on [CLNDR.js](http://kylestetz.github.io/CLNDR/)
##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](https://github.com/kylestetz/CLNDR#returning-the-instance--public-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"><</div>
<div class="clndr-next-button">></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:
```javascript
// 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](https://github.com/kylestetz/CLNDR#template-requirements) or [CLNDR site](http://kylestetz.github.io/CLNDR/)
### 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.