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.
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 });