CLNDR.js

CLNDR is a jQuery calendar plugin. It was created -- you've heard this before -- out of frustration with the lack of truly dynamic front-end calendar plugins out there.

See a demo: kylestetz.github.io/CLNDR/

Download

Development: clndr.js
Production: clndr.min.js

Returning to grab a new version? Have a look at the CHANGELOG.md file.

If you'd like to run some tests in a particular browser or environment, tests/test.html contains a list of basic functionality tests. When contributing, please run these (and add to them when appropriate) before submitting a pull request or issue!

Dependencies

jQuery and Moment.js are depended upon. By default CLNDR tries to use Underscore.js's _.template() function, however if you specify a custom rendering function (see documentation below) Underscore will not be used at all.

Because their APIs are the same, Lo-Dash's _.template() function will work as well! Just include Lo-Dash instead of Underscore.

Using NPM

You can install CLNDR via NPM:

npm install clndr

Underscore is not installed by default. This allows you to use whichever templating engine you want to. If you want to use the default template option with Underscore, just install it as a dependency of your project: npm install underscore or npm install lodash.

Using Bower

You can install CLNDR via Bower:

bower install clndr

CLNDR Using Angular

If you want to integrate clndr into an angular.js site, get started with this directive: angular-clndr.

CLNDR Using Rails

If you're building a rails application you may be interested in this gem by @sedx: clndr-rails.

Introduction: You Write The Markup

There are wonderful and feature-rich calendar modules out there and they all suffer the same problem: they give you markup (and often a good heap of JS) that you have to work with and style. This leads to a lot of hacking, pushing, pulling, and annoying why-can't-it-do-what-I-want scenarios.

CLNDR doesn't generate markup (well, it has some reasonable defaults, but that's an aside). Instead, CLNDR asks you to create a template and in return it supplies your template with a great set of objects that will get you up and running in a few lines.

The 'Days' Array

Here's a typical CLNDR template. It's got a controller section and a grid section.

<div class="clndr-controls">
  <div class="clndr-previous-button">&lsaquo;</div>
  <div class="month"><%= month %></div>
  <div class="clndr-next-button">&rsaquo;</div>
</div>
<div class="clndr-grid">
  <div class="days-of-the-week">
  <% _.each(daysOfTheWeek, function (day) { %>
    <div class="header-day"><%= day %></div>
  <% }) %>
    <div class="days">
    <% _.each(days, function (day) { %>
      <div class="<%= day.classes %>"><%= day.day %></div>
    <% }) %>
    </div>
  </div>
</div>

The days array contains most of the stuff we need to make a calendar. Its structure looks like this:

{
  day: 5,
  events: [],
  classes: "day",
  date: moment("2015-12-31")
}

This makes quick work of generating a grid. days.classes contains extra classes depending on the circumstance: if a given day is today, 'today' will show up, as well as an 'event' class when an event lands on that day.

Pass In Your Events

CLNDR accepts events as an array of objects:

events = [
  {
    date: "YYYY-MM-DD or some other ISO Date format",
    and: "anything else"
  }
]

CLNDR looks through the objects in your events array for a date field unless you specify otherwise using the dateParameter option. In your template the days array will auto-magically contain these event objects in their entirety. See the examples for a demonstration of how events populate the days array.

Usage

CLNDR leans on the awesome work done in Underscore and moment. These are requirements unless you are using a different rendering engine, in which case Underscore is not a requirement). Do be sure to include them in your <head> before clndr.js. It is a jQuery plugin, so naturally you'll need that as well.

The bare minimum (CLNDR includes a default template):

$('.parent-element').clndr();

With all of the available options:

$('.parent-element').clndr({

  // The template: this could be stored in markup as a
  //   <script type="text/template"></script>
  // or pulled in as a string
  template: clndrTemplate,

  // Determines which month to start with using either a date string or a
  // moment object.
  startWithMonth: "YYYY-MM-DD" or moment(),

  // Start the week off on Sunday (0), Monday (1), etc. Sunday is the default.
  // WARNING: if you are dealing with i18n and multiple languages, you
  // probably don't want this! See the "Internationalization" section below
  // for more.
  weekOffset: 0,

  // An array of day abbreviation labels. If you have moment.js set to a
  // different language, it will guess these for you! If for some reason that
  // doesn't work, use this...
  // WARNING: if you are dealing with i18n and multiple languages, you
  // probably don't want this! See the "Internationalization" section below
  // for more.
  daysOfTheWeek: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],

  // Optional callback function that formats the day in the header. If none
  // supplied, defaults to moment's `dd` and truncates to one character.
  // The callback is passed a moment object representing the day, and a string
  // is to be returned.
  formatWeekdayHeader: function (day) {
    return day.format('dd').charAt(0);
  },

  // The target classnames that CLNDR will look for to bind events.
  // these are the defaults.
  targets: {
    day: 'day',
    empty: 'empty',
    nextButton: 'clndr-next-button',
    todayButton: 'clndr-today-button',
    previousButton: 'clndr-previous-button',
    nextYearButton: 'clndr-next-year-button',
    previousYearButton: 'clndr-previous-year-button',
  },

  // Custom classes to avoid styling issues. pass in only the classnames that
  // you wish to override. These are the defaults.
  classes: {
    past: "past",
    today: "today",
    event: "event",
    selected: "selected",
    inactive: "inactive",
    lastMonth: "last-month",
    nextMonth: "next-month",
    adjacentMonth: "adjacent-month",
  },

  // Click callbacks! The keyword 'this' is set to the clndr instance in all
  // callbacks.
  clickEvents: {
    // Fired whenever a calendar box is clicked. Returns a 'target' object
    // containing the DOM element, any events, and the date as a moment.js
    // object.
    click: function (target) {...},

    // Fired when a user goes to the current month and year. Returns a
    // moment.js object set to the correct month.
    today: function (month) {...},

    // Fired when a user goes forward a month. Returns a moment.js object
    // set to the correct month.
    nextMonth: function (month) {...},

    // Fired when a user goes back a month. Returns a moment.js object set
    // to the correct month.
    previousMonth: function (month) {...},

    // Fires any time the month changes as a result of a click action.
    // Returns a moment.js object set to the correct month.
    onMonthChange: function (month) {...},

    // Fired when the next year button is clicked. Returns a moment.js
    // object set to the correct month and year.
    nextYear: function (month) {...},

    // Fired when the previous year button is clicked. Returns a moment.js
    // object set to the cor

CLNDR

Install / Use

README