Bootstrap Date Paginator jQuery plug-in for UI design of date selection as input

A jQuery plugin which takes Twitter Bootstrap’s already great pagination component and injects a bit of date based magic. In the process creating a hugely simplified and modularised way of paging date based results in your application.

Dates are selectable, scrollable and with the optional calendar select option thanks to eternicode bootstrap-datepicker, you can easily jump to any calendar date.

Requirements

If you haven’t already, you’ll need to download and setup the following dependencies.

• Bootstrap v3.0.3
• jQuery v2.0.3
• Moment.js v2.4.0
• bootstrap-datepicker.js v1.2.0

Where provided these are the actual versions bootstrap-datepaginator has been tested against. Other versions should work but you use them as your own risk.

Please note this component currently only supports Bootstrap 3. If you want to request support for Bootstrap2, tweet me @jondmilesand if I get enough requests I will consider adding support.

Usage

Thanks to sensible defaults and the date based nature of this component, you can get up and running with just a few lines of code.

That is of course once you’ve downloaded and setup the required dependencies: Twitter Bootstrap, jQuery, Moment.js and bootstrap-datepicker. Slightly more than I would have liked but there’s no point re-inventing the wheel, these are all great components in their own right!

Example, minimum usage:

<!-- Required Stylesheets -->
<link href="./css/bootstrap.min.css" rel="stylesheet" media="screen">
<link href="./css/bootstrap-datetimepicker.css" rel="stylesheet" media="screen">

<!-- Markup - paginator will be injected as html into this div -->
 id="example">

<!-- Required Javascript -->
 type="text/javascript" src="./js/jquery.js">
 type="text/javascript" src="./js/moment.js">
 type="text/javascript" src="./js/bootstrap-datetimepicker.js">
 type="text/javascript" src="./js/bootstrap-datepaginator.js">

<!-- Basic initialization using defaults -->
 type='text/javascript'>
  $('#example').datepaginator();

The constructor also takes an options object which allows for extensive customization of lookup and feel, as well as behaviour.

Example, with initialization options:

<!-- Initialization with options -->
 type='text/javascript'>
  var options = {
    selectedDate: '2013-01-01',
    selectedDateFormat: 'YYYY-MM-DD'
  }
  $('#example').datepaginator(options);

Options

endDate

Sets the latest date that may be selected, all later dates will be disabled.

Expects: String, or Moment. Default: End of time

endDateFormat

Sets the date format used when parsing string representations of endDate.

Expects: String. Default: 'YYYY-MM-DD'

highlightSelectedDate

Whether or not to distinguish visually the selected date.

Expects: Boolean. Default: true

highlightToday

Whether or not to distinguish visually today’s date.

Expects: Boolean. Default: true

hint

Format used for on hover hint. String tokens are parsed against a given date.

Expects: String. Default: 'dddd, Do MMMM YYYY'

injectStyle

By default the required styles are injected into the DOM automatically and no external css reference is required. In the event that you want to override and customize the default style, set injectStyle to false and ensure that bootstrap-datepaginator.css (or your modified .css) is referenced.

Expects: Boolean. Default: truePlease note – where multiple paginators are applied to the same page, all must be set to injectStyle false otherwise the DOM injected style takes precedence.

itemWidth

Minimum width specified in pixels for an item.

Expects: Integer. Default: 35

navItemWidth

Minimum width specified in pixels for the nav items e.g. left and right arrows

Expects: Integer. Default: 20

offDays

Sets days of the week to be considered off days, visually greyed out.

Expects: String (csv). Default: 'Sat,Sun'

offDaysFormat

Sets the format used when evaluating offDays. For example, ‘ddd’ formats as a 3 letter abbreviation representing the day of the week, therefore Saturday becomes ‘Sat’.

Expects: String. Default: 'ddd'Please review Moment.js formatting guide for a full list of supported options.

selectedDate

Sets the initial selected date, provided as either a Moment.js moment object or String.

Expects: String, or Moment. Default: moment(), equivalent to new Date()*If you’re planning on providing a String, please ensure you review the dateFormat option.

selectedDateFormat

Sets the date format used throughout the components lifecycle when parsing the selected date object.

Expects: String. Default: 'YYYY-MM-DD'

selectedItemWidth

Minimum width specified in pixels for the selected item.

Expects: Integer. Default: 120

showCalendar

Whether or not to display the clickable calendar icon visible on selected date. By setting to false you are effectively removing the calendar date select functionality from the user.

Expects: Boolean. Default: true

showOffDays

Whether or not to display off days.

Expects: Boolean. Default: true

showStartOfWeek

Whether or not to display the start of week divider.

Expects: Boolean. Default: true

size

Sets the height of the paginator component. Accepts small, normal, large.

Expects: String. Default: normal

startDate

Sets the earliest date that may be selected, all earlier dates will be disabled.

Expects: String, or Moment. Default: Beginning of time

startDateFormat

Sets the date format used when parsing string representations of startDate.

Expects: String. Default: 'YYYY-MM-DD'

startOfWeek

Sets for display purposes the start of the week, visually illustrated by a thicker dividing line betweeen dates.

Expects: String. Default: 'Mon'

startOfWeekFormat

Sets the format used when evaluating startOfWeek. For example, ‘ddd’ formats as a 3 letter abbreviation representing the day of the week, therefore Saturday becomes ‘Sat’.

Expects: String. Default: 'ddd'Please review Moment.js formatting guide for a full list of supported options.

squareEdges

Toggles the border radius between Bootstrap’s default rounded edges (border-radius: 4px) and overridden square edges (border-radius: 0px).

Expects: Boolean. Default: false

text

Format used for item text i.e. date format. String tokens are parsed against a given date.

Expects: String. Defaults: 'ddd<br/>Do'

textSelected

Format used for the selected items text. String tokens are parsed against a given date.

Expects: String. Defaults: 'dddd<br/>Do, MMMM YYYY'

width

By default the paginator will automatically fill the entire width of it’s container. However, if you require more control over the component you can specify any given width in pixels e.g. width: 400.

Expects: Integer. Default: 0 (auto)

Methods

setSelectedDate

Sets the selected date, triggering a refresh to reflect the new state.

$('#datepaginator').datepaginator('setSelectedDate', ['2013-10-05', 'YYYY-MM-DD']);

If called without passing a format argument, selectedDateFormat will be used.

$('#datepaginator').datepaginator('setSelectedDate', '2013-10-05');

remove

Removes the date paginator component. Removing attached events, internal attached objects, and added HTML elements.

$('#datepaginator').datepaginator('remove');

Events

selectedDateChanged

Fired when the selected date changes. You can bind to it using either the callback handler or the standard jQuery .on method

Example: callback handler

var options = {
  onSelectedDateChanged: function(event, date) {
    // Your logic goes here
  }
}
$('#event-example').datepaginator(options);

Example: jQuery .on method

$('#event-example').on('selectedDateChanged', function(event, date) {
  // Your logic goes here
});