JSCalendar

The lightest Javascript calendar out there, without any dependency (no jQuery). This is a work in progress, but it is ready to be used in production.

The development files are using es2016, so I used babel with the es2015 preset and babily to minify the whole thing. Distribution files can be found under ./dist/. There are both normal and minified files.

Sailor's honour

If other kind developers want to lend a hand, I will obviously stop pushing directly to master and switch to a dev branch ;)

Installation

Using git

git clone https://github.com/rykdesjardins/js-calendar

Using NPM

npm install --save vanilla-js-calendar

Using bower

bower install --save vanilla-js-calendar

Basic usage

var elem = document.getElementById("myCalendar");
var calendar = new JSCalendar(elem, { /* options */ }).init().render();

Simple design and fast rendering

Options

Option name	Usage	Default
views	Array of available views	["day", "week", "month"]
viewsVocab	Object of words used to represent the views { view : "display name" }	{day : "Day", week : "Week", month : "Month" }
buttons	Available buttons in the top control bar	["previous", "today", "next"]
buttonsActions	JSCalendar function, or user-defined function object for top buttons { action : "functionName" \|\| function }	{ previous : "goBack", today : "goNow", next : "goNext" }
buttonsVocab	Object of words used to represent the buttons { action : "display name" }	{previous : "<", today : "Today", next : ">"}
monthsVocab	Array of display names for every months	["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
daysVocab	Array of display names for every week day	["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
emptyDayVocab	Display phrase when no event is found for a partical day	"Nothing here."
noDate	Word used when an event has no time at a certain date	"Somewhen"
nonameEventVocab	Words used when an event does not have a name	"Event without a name"
globalSelector	Query Selector used to search for JSCalendars in the DOM	".js-calendar"
eventBackground	Default event background color	"rgb(126, 156, 193)"
titleCropSize	Number of letter max for events in the month view	20
datasource	URL used to request matrix data	""
datasourceHeaders	Headers to be sent to the data source on every request	{}
ampm	Flag, setting it to true will use 12h system, false will use 24h	true
displaySeconds	Flag, setting it to true will display the seconds for the events in the calendar	false
dayviewGapMinutes	Number of minutes between each block in day view	30
dayviewNoTimeGapSize	Number of block used in day view for events without a time	2
alwaysFetch	Wether to always fetch from server or not	false
fetchReplaces	Wether to replace the entire matrix after fetching, false for append	false
dayviewGapHeight	Height of a block in day view, in pixels	38
height	Maximum height for the calendar, if it goes beyond, scroll bars are added	700
width	Maximum width for the calendar, if it goes beyond, the rest will be hidden. Can also be "full" for responsive full width.	1024

Hooks

Hooks can be used to customize certain events and alter the way data is fetched, processed and rendered.

// Hooks on a specific instance
var calendarInstance = new JSCalendar(elem);
calendarInstance.on('eventName', (calendar, extra) => {
    // calendar is the current calendar instance
    // extra contains various data depending on the event
});

// Hooks on all instances
JSCalendar.on('eventName', (calendar, extra) => {
    // Arguments are the same as above
});

Hook name	Context
new	Fired when a JSCalendar object is built using the default constructor.
init	Fired when the initialization logic is being processed for a newly built object. Fired before the DOM structure is created.
willPush	Fired before adding an item to the calendar dynamically.
pushed	Fired after adding an item to the calendar dynamically.
didNotPush	Fired after failing to add an item to the calendar dynamically.
willRender	Fired before rendering the calendar, also before fetching data from the data source if specified.
rendered	Fired after the render logic was processed.
dragging	Fired when an event is grabbed and ready to be moved around.
dropped	Fired when an event is dropped, the event cellMightMove will be triggered right after this one.
cellMightMove	Fired when a cell movement is validated.
cellMoved	Fired after an event was moved from a cell to another.
cellDidNotMoved	Fired when a cell could have moved, but the validation failed or the event was dropped onto its original cell.
matrixWillSet	Fired when a matrix is sent to replace the current one in the calendar's state.
matrixSet	Fired after a matrix was set as the current matrix state.
matrixWillAppend	Fired when another matrix is about to be inserted into the current matrix state
matrixAppended	Fired after another matrix was inserted into the current matrix state
willFetch	Fired before sending a fetch request to a data source.
fetched	Fired after receiving data from the data source.
viewWillChange	Fired before rendering a new view (month, week, day).
viewChanged	Fired after changing view. This will not fire if the view was set to the current one (wasn't changed).

Static functions

Those can be called using the class directly

// Will instanciate all calendars found under a certain wrapper
JSCalendar.find(document.getElementById("calendar-area"));

// Will return an instance of a calendar automatically generated using JSCalendar.find()
JSCalendar.getInstance(instanceid);

// Fires an event to all calendars from a specified instance
JSCalendar.fire(event, instance, extra);

/* 
    Returns an object : 
    { 
        numberOfDays : number,  // Total number of days in the month
        firstDay : number       // Week day of the 1st of the month
    }
*/
JSCalendar.getDaysInMonth(year, month);

Instance functions

Associated with all JSCalendar instanciated objects. Chainable functions return "this" so you can chain multiple functions on one line.

// Must be called after instanciating [chainable]
calendar.init(callback)

// Previous, today, next [chainable]
// Those are called when pressing the direction buttons on the top bar. 
// The calendar will be rendered at the end
calendar.goBack();
calendar.goNow();
calendar.goNext();

// Adding an item to the matrix [chainable]
/*
    The first parameter is an object : 
    {
        at : Date,
        event : JSCalendarEventTemplate { 
            at : Date, 
            displayname : string, 
            duration : number,  
            color : string
        }
    }
*/
calendar.push(event);

// Destroy calendar reference [chainable]
calendar.destroy();

// Switch from current view to another [chainable]
/*
    First parameter is on of the following strings : 
        month
        week
        day
*/
calendar.setView(view);

// Refresh and rebuild current view [chainable]
calendar.render();

// Merge a new matrix into the current state matrix [chainable]
/*
    A matrix is an object formatted like the following :
    matrix[year][month][day] = [JSCalendarEventTemplate];
    
    The second parameter is a flag (true|false). If true, 
    the calendar will render after setting the new matrix
*/
calendar.appendMatrix(matrix, rerender);

// Set the current state matrix, and destroy the old one if any [chainable]
calendar.setMatrix(matrix, rerender);

// If a data source is specified, fetch a new matrix to append [chainable]
/*
    This will request to the data source specified with query parameters
    like the following : 
    year = current state year
    month = current state month
    day = current state day
    
    Once finished, the provided callback will be executed
    The second parameter is a flag (true|false), if set to true, will
    fetch even is a cached version of the matrix exists.
*/
calendar.fetch(callback, force);

hamoodij/js-calendar