rome

Dependency free, opt-in UI, customizable date (and time) picker!

Rome wasn't built in a day.

Demo!

You can see a live demo here.

Oh, rome synchronizes in real-time with the input, never steals focus, and its CSS is entirely customizable!

_{Not dependency free. It depends on moment. Does not depend on jQuery or other weird frameworks, though.}

Install

From npm or Bower.

npm install --save rome

bower install --save rome

Note that if you're using the standalone version, the API is published under the rome global. If you're using CJS, then you'll have to require('rome').

Setup

You can define moment yourself, using rome.standalone.js.

<script src='moment.js'></script>
<script src='rome.standalone.js'></script>

You could just use the bundled rome.js distribution, which comes with moment in it.

<script src='rome.js'></script>

If you need to do anything regarding internationalization, refer to moment for that before starting to create Rome calendar components.

API

rome.moment

Rome will use this instance of moment. It can either come from the rome.js bundle or you can choose your own by setting window.moment = value before loadingrome.standalone.js.

The API in rome exposes two methods.

rome.find(input)

Finds a previously created Rome calendar. Exactly the same as doing rome(input) after the first time. The difference is that if the first call made on an input is .find you'll get undefined, and if the first call is rome then a Rome calendar will be created and associated to the input. This association can't be undone even by .destroy()ing the rome instance, which can be .restore()d later.

rome(input, options?)

Creates a Rome calendar using a ton of options. These have reasonable defaults that are easy to adjust, too. The options are listed below.

Default Options

If you don't set an option, the default will be used. You can look up the defaults here, or below.

{
  "autoHideOnClick": true,
  "appendTo": document.body,
  "autoClose": true,
  "autoHideOnBlur": true,
  "date": true,
  "dateValidator": Function.prototype,
  "dayFormat": "DD",
  "inputFormat": "YYYY-MM-DD HH:mm",
  "invalidate": true,
  "min": null,
  "max": null,
  "monthFormat": "MMMM YYYY",
  "required": false,
  "styles": {
    "back": "rd-back",
    "container": "rd-container",
    "date": "rd-date",
    "dayBody": "days-body",
    "dayBodyElem": "day-body",
    "dayDisabled": "day-disabled",
    "dayHead": "days-head",
    "dayHeadElem": "day-head",
    "dayRow": "days-row",
    "dayTable": "rd-days",
    "month": "rd-month",
    "next": "rd-next",
    "selectedDay": "day-selected",
    "selectedTime": "time-selected",
    "time": "rd-time",
    "timeList": "time-list",
    "timeOption": "time-option"
  },
  "time": true,
  "timeFormat": "HH:mm",
  "timeInterval": 1800,
  "timeValidator": Function.prototype,
  "weekStart": 0
}

Rome API

When you create a calendar with rome(input), you'll get a cal instance back. This has a few API methods.

.show()

Shows the calendar by absolutely positioning it right below the input field.

.hide()

Hides the calendar.

.container

The DOM element that contains the calendar.

.input

The input field assigned to this calendar instance.

.getDate()

Returns the current date, as defined by the calendar, in a native Date object. If required: false you'll get null when the input field is empty.

.getDateString(format?)

Returns the current date, as defined by the calendar, using the provided options.inputFormat format string or a format of your choosing. If required: false you'll get null when the input field is empty.

.getMoment()

Returns a copy of the moment object underlying the current date in the calendar. If required: false you'll get null when the input field is empty.

.destroy()

Removes the calendar from the DOM and all of its associated DOM event listeners. The API is reduced to provide only the .restore method described below. After emitting the destroyed event, all event listeners are removed from the instance.

.restore(options?)

Restores the calendar, using the provided options (or the default options). The associated input field can't be changed.

.options(options?)

If an options object is provided, it destroys the calendar and initializes it with the provided options. Effectively the same as calling .restore(options) immediately after calling .destroy().

If no options object is provided, a copy of the current options is returned.

.options.reset()

Resets the options to the factory defaults. Effectively the same as calling .options({}).

Events

Rome calendars also provide a few events you can subscribe to. These events are published through an event emitter created using contra. These events are listed below.

Date and Time Validator

Please note that dateValidator and timeValidator both receive a native Date object as a parameter. These methods are expected to return undefined or true if the date is deemed valid, and false in case the date is invalid. If dateValidator returns false, the validation process will try to find a valid date near the desired date.

If dateValidator passes for a given date, the timeValidator will attempt to validate that date as well. If the time is invalid, the day will be probed for a valid time. This validation starts at the desired time, and grows in timeInterval increments. When the end of the day is reached, validation resumes at the start of the day instead of leaping to the next day.

License

MIT