Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/navinspm/clndr-rails

Gem to CLNDR.js library
https://github.com/navinspm/clndr-rails

calendar clndr hacktoberfest rails

Last synced: 3 months ago
JSON representation

Gem to CLNDR.js library

Awesome Lists containing this project

README 

        
[![Code Climate](https://codeclimate.com/github/navinspm/clndr-rails/badges/gpa.svg)](https://codeclimate.com/github/navinspm/clndr-rails)[![Gem Version](https://badge.fury.io/rb/clndr-rails.svg)](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:



```



  <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>



```

 **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::

  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.