Skip to content

Latest commit

 

History

History
382 lines (312 loc) · 15 KB

README.md

File metadata and controls

382 lines (312 loc) · 15 KB
Raw

HomeAway Calendar Widget

Example Calendar

The HomeAway Calendar Widget provides a reusable, easy to setup availability calendar and datepicker. The availability calendar and datepicker use the same calendar plugin, but with different options passed in. The HomeAway Calendar Widget uses Grunt.js to build it's JavaScript and CSS. Be sure that you have Ruby 1.9, Compass, Grunt.js, and NPM (>1.1 version) installed on your machine to before attempting to build project. To build the project run:

$ npm install
$ grunt

To see an example inline and datepicker calendar run:

$ python -m SimpleHTTPServer

and navigate to http://localhost:8000/example

See LICENSE.txt for license information.

Dependencies

Library Description
Backbone.js 0.9.2 Backbone.js gives structure to web applications by providing models with key-value binding and custom events, collections with a rich API of enumerable functions, views with declarative event handling, and connects it all to your existing API over a RESTful JSON interface.
Lo-Dash.js 0.5.2 An alternative to Underscore.js, delivering consistency, customization, performance, and extra features.
jQuery UI-Core.js 1.7.3 The core of jQuery UI, required for all interactions and widgets.
jQuery UI-Datepicker.js 1.7.3 Displays a calendar from an input or inline for selecting dates.

Usage

$('#myCalendar').calendar(options)

Options

name type default description
url String '' The url to fetch data from.
startOfWeek Number 0 The day of the week for the calendar to start on. 0 is for Sunday, 1 is for Monday, etc.
language Object English US. See below for default. The language keys to use for the datepicker. To pass in keys use the following format. Note that all keys must be provided if an alternative language is being used. They must also follow the correct ordering of months, days, etc.
defaultDate See Docs todays date The date to start the date picker on.
minDate See Docs undefined The minimum date that the calendar can select. This is applied to both start and end calendars.
minDate See Docs undefined The maximum date that the calendar can select. This is applied to both start and end calendars.
startCalendarDate Date Object undefined The date to set the start calendar datepicker to.
endCalendarDate Date Object undefined The date to set the end calendar datepicker to.
showButtonPanel Boolean false Determines if the datepicker shows the button panel.
startIsEndMinimum Boolean false Determines if the end calendars minimum date is the selected date of the first calendar.
numberOfMonths Number or Array 1 or [N, M] The number of inline calendars to show. Alternatively an array can be passed in specifying a grid of calendars.
propertyId String '' The property id to fetch data for, given an id is specific to a property.
fetch boolean true Determines if the calendar should fetch data.
calendar Object {} An object of default calendar days to add to the calendar. See the JSON schema for details.
reservations Object {} An object of default reservations that correspond to calendar days. See the JSON schema for details.
clicked Object See below for default. An object whose keys are event statuss and values are callback functions for on click of a particular event. These functions are called on click for a particular day for a given type of event. The functions are passed the jQuery element that was clicked and the calendar reservation object for the day clicked.
hovered Object See below for default. An object whose keys are represent the on and off hover of an event and whose values are callback functions for their corresponding hover events. The functions are passed the jQuery element that was hovered and an array of calendar reservation objects for the day hovered.
error Function See below for default. A function to handle error events from the model. Generally this should be used to control how to display error messages.
endCalendar String '' A jQuery selector string to the second calendar.
hoverClass String '' The class to apply to dates between the selected start and end dates when using two datepickers.
hoverClassStart String '' The class to apply to the selected start date when using two datepickers.
hoverClassEnd String '' The class to apply to the selected end date when using two datepickers.

Language Default

{ 
    closeText: 'Done',
    prevText: 'Prev',
    nextText: 'Next',
    currentText: 'Today',
    monthNames: ['January','February','March','April','May','June',
    'July','August','September','October','November','December'],
    monthNamesShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
    dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
    dayNamesShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
    dayNamesMin: ['Su','Mo','Tu','We','Th','Fr','Sa'],
    weekHeader: 'Wk'
}

Hovered Default

{
  'on': function(element, reservations) {
  },
  'off': function(element, reservations) {
  }
}

Clicked Default

{
  'inquiry': function(element, reservation) {
  },
  'unavailable': function(element, reservation) {
  },
  'hold': function(element, reservation) {
  },
  'reserve': function(element, reservation) {
  },
  'delete': function(element, reservation) {
  }
}

Error Default

function(error) {
}

Functions

name options description
addReservations Object Used to add reservations to the calendar after instantiation. The object passed in requires the keys calendar and reservation, the same options passed into the calendar during instantiation. See the JSON Schema below for further details.
removeReservations String or Array Used to remove reservations by id from the calendar after instantiation. The parameter can either be a single reservation id or an array of reservation ids.

Examples

$('#myCalendar').calendar('addReservations', {
    calendar: {
        range: {
            "startDate": '2013-01-02',
            "endDate": '2013-01-05',
            "reservationId": "inquiry"
        }
    },
    reservations: {
        "inquiry": {
            "status": "INQUIRY"
        } 
    }
});

$('#myCalendar').calendar('removeReservations', 'INQUIRY');

Events

The Calendar widget allows users to pass in their own custom functions for on click of statuss, on error, and a custom changed event that is fired for when the start or end dates have changed for input field datepickers.

In addition, the calendar widget publishes events for on click of events and on error that can be easily subscribed to. Therefore, if you have a custom endpoint with custom event statuses you can easily subscribe to the events. Below is an example of subscribing to the on click of a reserve event and the on error event. Note the first parameter, e, is the event object.

$('#myCalendar').on('reserve', function(e, element, reservation) {
  console.log('Reserve event triggered!');
  console.log(reservation);
});

$('#myCalendar').on('error', function(e, error) {
  console.log('Error event triggered!');
  console.log(error);
});

$('#myCalendar').on('changed', function(e) {
  console.log('The calendar date was changed!');
});

Expected JSON Schema

If you decide to roll your own endpoint to serve up reservation data, the url that the HomeAway Calendar Widget hits is structured as follows:

url + propertyId + '?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD'

Where url and propertyId are options that can be passed into the HomeAway Calendar Widget and the start and end dates are automically calculated.

The calendar expects an object returned with a calendar attribute whose value is an object of events or event ranges. An event range contains a start and end date for the event as well as the event status(type of event) and a unique id. Event ranges are particularly useful when initializing the calendar with data, such as an inquiry. The JSON schema that the calendar expects is below.

{
  'calendar': {
    'YYYY-MM-DD': {
      'reservationId': '',
      'status': 'RESERVE' | 'HOLD' | 'DELETE' | 'UNAVAILALBE'
    },
    'EXAMPLE': {
      'startDate': 'YYYY-MM-DD',
      'endDate': 'YYYY-MM-DD',
      'reservationId': '',
      'status': 'RESERVE' | 'HOLD' | 'DELETE' | 'UNAVAILALBE'
    }
  },
  'reservations': {
    'reservationId': {
      'guestFirstName': '',
      'guestLastName': '',
      'status': 'RESERVE' | 'HOLD' | 'DELETE' | 'UNAVAILALBE',
      'checkinTime': '',
      'checkoutTime': ''
      'checkinDate': 'YYYY-MM-DD',
      'checkoutDate': 'YYYY-MM-DD'
    }
  }
}

A calendar event object, whose key is a date, has the following properties.

name type expected value(s) description
reservationId String '' The unique id of the event.
status String 'RESERVE' or 'HOLD' or 'DELETE' or 'UNAVAILALBE' The status of the event. Currently supported event statuses are the above.

A calendar event range object, whose key is a random value, has the following properties.

name type expected value(s) description
startDate String 'YYYY-MM-DD' The start date of the event.
endDate String YYYY-MM-DD' The end date of the event.
reservationId String '' The unique id of the event.
status String 'RESERVE' or 'HOLD' or 'DELETE' or 'UNAVAILALBE' The status of the event. Currently supported event statuses are the above.

A reservation object, whose key is a reservationId from a calendar object, has the following properties.

name type expected value(s) description
guestFirstName String '' The guests first name associated with the event.
guestLastName String '' The guests last name associated with the event.
checkinTime
checkoutTime
checkinDate String YYYY-MM-DD The checkin date for the reservation.
checkoutDate String YYYY-MM-DD The checkout date for the reservation.
status String 'RESERVE' or 'HOLD' or 'DELETE' or 'UNAVAILALBE' The status of the event. Currently supported event statuses are the above.

Example JSON.

{
  'calendar': {
    "range": {
        "startDate": '2013-01-02',
        "endDate": '2013-01-05',
        "reservationId": "inquiry"
    },
    "2013-02-11": {
        "status": "RESERVE",
        "reservationId": "24ba2024-f0dd-4c7d-a744-57396d56fd42"
    },
    "2013-02-12": {
        "status": "RESERVE",
        "reservationId": "24ba2024-f0dd-4c7d-a744-57396d56fd42"
    },
    "2013-02-13": {
        "status": "RESERVE",
        "reservationId": "24ba2024-f0dd-4c7d-a744-57396d56fd42"
    }
  },
  'reservations': {
    "24ba2024-f0dd-4c7d-a744-57396d56fd42": {
        "guestFirstName": "Jane",
        "guestLastName": "Doe",
        "checkinDate": "2013-02-11",
        "checkoutDate": "2013-02-14",
        "checkinTime": "01:30",
        "checkoutTime": "21:00",
        "status": "RESERVE"
    },
    "inquiry": {
        "status": "INQUIRY"
        "guestFirstName": "John",
        "guestLastName": "Doe",
        "checkinDate": "2013-01-02",
        "checkoutDate": "2013-01-05",
        "checkinTime": "02:30",
        "checkoutTime": "6:45",
    }
  }
}

Examples

Include the HomeAway Calendar Widget CSS and JS.

<link href="calendar-widget.min.css" rel="stylesheet">
<script src="calendar-widget.min.js"></script>

As with the jQuery UI Datepicker if the datepicker is given a div for it's binding element it will create an inline datepicker. If given an input field as it's binding element it will create a datepicker.

Availabilty Calendar

Create a div to bind the calendar to.

<div id="myCalendar"></div>

Create the calendar.

$('#myCalendar').calendar({
  numberOfMonths:     2,
  propertyId:       'c584729e-441a-464a-9f24-2e7cc7294568',
  clicked: {
    reserve: function(element, reservation) {
      console.log("Reserve status event clicked!");
      console.log(reservation);
    },
    hold: function(element, reservation) {
      console.log("Hold status event clicked!");
      console.log(reservation);
    }
  },
  hovered: {
    on: function(element, reservations) {
      console.log("Event hovered on!");
    },
    off: function(element, reservations) {
      console.log("Event hovered off!");
    }
  }
  error: function(error) {
    console.log('There was an error!');
    console.log(error);
  }
});

Datepicker Calendar

Create an input field to bind to.

<input type="text" placeholder="Calendar" class="calendar">

Create the calendar.

$('.calendar').calendar({
    'fetch': false
});

Datepicker Calendar Using 2 Inputs

Create two input fields to bind to.

<input type="text" placeholder="Start Calendar" class="start-calendar">
<input type="text" placeholder="End Calendar" class="end-calendar">

Create the calendars.

Note passing in a jQuery selector for the end calendar and all classes for the highlighting of days in the calendars.

$('.start-calendar').calendar({
    'fetch': false,
    'endCalendar': '.end-calendar',
    'hoverClass': 'full-reserve',
    'hoverClassStart': 'pm-reserve',
    'hoverClassEnd': 'am-reserve'
});

Customization

The HomeAway Calendar Widgets colors can be fully customizable by modifying the colors in the _variables.scss file in the sass folder. To recompile the sass into css run:

$ npm install
$ grunt

Contribute

The HomeAway Calendar Widget is built with love by Phillip Whisenhunt(JavaScript@pwhisenhunt) and Martin Note(CSS). Feel free to contribute.