agjCalendar

Description

agjCalendar is a plugin for the jQuery Javascript library to deal with calendars, dates and date ranges.

agjCalendar is an agjjQuery.org plugin.

Examples

// The most basic agjCalendar integration
$.agjCalendar({
  dateSelector: '#text-input'
});

// An alternative way of doing the same thing
$('#text-input').agjCalendar();

// A more complex agjCalendar integration
$.agjCalendar({
  dateFormat:          2,
  calendarCount:       3,
  inputType:           'text',
  dateSelector:        '#start-date',
  expanderSelector:    '#start-date-icon',
  minimumDate:         '2023-01-01',
  maximumDate:         '2023-12-31',
  defaultDate:         '2023-07-09',
  defaultEndDate:      '2023-07-10',
  allowRange:          true,
  minimumRange:        1,
  maximumRange:        7,
  defaultRange:        2,
  endDateSelector:     '#end-date',
  endExpanderSelector: '#end-date-icon'
});

There are other examples included in the GitHub repository and on agjCalendar.agjjQuery.org.

Options

When intializing an agjCalendar integration you can set its configuration options by passing a JSON object of values.

// A basic agjCalendar integration that will render a calendar that uses Monday to start the week
$.agjCalendar({
  dateSelector:      '#text-input',
  startWeekOnMonday: true
});

// Alternatively you can use the $.fn.agjCalendar() function for the same result
$('#text-input').agjCalendar({
  startWeekOnMonday: true
});

A complete list of all options, their default values, valid values and notes is available below.

key|type|default|values|notes ---|----|-------|------|----- allowBlankDates|boolean|false|truefalse|If set to true blank dates (e.g. mm/dd/yyyy) will be permitted allowRange|boolean|false|truefalse|If set to true a second date can be entered with the endDateSelector option or the endMonthSelector and endDaySelector options autoSetEndDate|string|'dates'|'blanks''dates''always''never'|This option controls whether or not the end date will automatically change when the start date changes;'blanks' will only trigger when the end date is blank,'dates' will only trigger when the end date is a date,'always' will trigger for both and'never' will trigger for neither(only used when allowRange is set to true) calendarCount|integer|1|123|Defines whether the date picker uses a single, double or triple calendar (only used when calendarDisplay is set to 'inline' or 'modal') calendarDisplay|string|'inline'|'inline''modal''full'|Toggles whether the date picker is displayed as 'inline', 'modal' or 'full' dateFormat|integer|1|12345|Determines which date format is used for text inputs (only used when inputType is set to 'text')1 = MM/DD/YYYY, e.g. 01/02/20032 = MMM D, YYYY, e.g. Jan 2, 20033 = DD/MM/YYYY, e.g. 02/01/20034 = YYYY-MM-DD, e.g. 2003-01-025 = D MMMM YYYY, e.g. 2 January 2003 dateSelector|string|null||Accepts a string value for your target text element such as '#text-input' (only used when inputType is set to 'text') dayNameFormat|string|'short'|'short''medium''full'|Determines which day format is used for days of the week on the date picker'short' = one letter, e.g. F'medium' = abbreviated, e.g. Fri'full' = full name, e.g. Friday daySelector|string|null||Accepts a string value for your target day dropdown element such as '#day-select' (only used when inputType is set to 'dropdown') defaultDate|Date|string|Today’s date|A Date object, a string formatted as YYYY-MM-DD or 'blank'|The default date to prefill defaultEndDate|Date|string|Today’s date plus the defaultRange|A Date object, a string formatted as YYYY-MM-DD or 'blank'|The default end date to prefill (only used when allowRange is set to true) defaultRange|integer|0 if the minimumDate and maximumDate options are set to the same date otherwise 1|Any non-negative integer|The default date range (only used when allowRange is set to true) endDateSelector|string|null||The same as dateSelector but for the end date (only used when allowRange is set to true and inputType is set to 'text') endDaySelector|string|null||The same as daySelector but for the end date (only used when allowRange is set to true and inputType is set to 'dropdown') endExpanderSelector|string|null||The same as expanderSelector but for the end date (only used when allowRange is set to true) endMonthSelector|string|null||The same as monthSelector but for the end date (only used when allowRange is set to true and inputType is set to 'dropdown') excludeDates|array|[]|An array of Date objects and/or strings formatted as YYYY-MM-DD|Individual dates that will be excluded from the date picker expanderSelector|string|null||Accepts a string value for an additional target element to expand the calendar such as '#calendar-icon' inputType|string|'text'|'text''dropdown'|If set to 'text' will use the dateSelector option to store the date or if set to 'dropdown' will use the monthSelector and daySelector options to store the date language|string|'en'|'en''fr'|The language for the text elements on the date picker'en' = English'fr' = Français (French) maximumDate|Date|string|Today’s date plus one year|A Date object or a string formatted as YYYY-MM-DD|The maximum date that can be picked maximumRange|integer|The number of days between the minimumDate and maximumDate options|Any non-negative integer|The maximum date range (only used when allowRange is set to true) minimumDate|Date|string|Today’s date|A Date object or a string formatted as YYYY-MM-DD|The minimum date that can be picked minimumRange|integer|0 if the minimumDate and maximumDate options are set to the same date otherwise 1|Any non-negative integer|The minimum date range (only used when allowRange is set to true) monthSelector|string|null||Accepts a string value for your target month dropdown element such as '#month-select' (only used when inputType is set to 'dropdown') overwriteDayOptions|boolean|true|truefalse|If set to true the options on the daySelector and endDaySelector dropdown elements will dynamically update (only used when inputType is set to 'dropdown') overwriteMonthOptions|boolean|true|truefalse|If set to true the options on the monthSelector and endMonthSelector dropdown elements will dynamically update (only used when inputType is set to 'dropdown') startWeekOnMonday|boolean|false|truefalse|If set to true the weeks on the calendar will start on Monday instead of Sunday theme|string|null|'red''orange''yellow''green''cyan''blue''purple''pink''custom-*'|A string of one of the eight included themes or a custom theme that must begin with custom- (our online documentation has more details on the themes page)

Javascript Functions

The majority of the functionality for the agjCalendar plugin is self-contained but there are four functions that are added to extend jQuery. We use the dollar sign ($) instead of the jQuery global for documentation but either can be referenced.

$.agjCalendar([options])

var integration = $.agjCalendar({
  dateSelector: '#text-input'
});
if (integration) {
  alert('The integration was a success!');
} else {
  alert('The integration failed; check your Javascript console for details.');
}

The $.agjCalendar() function accepts an options JSON object of values to initialize a new agjCalendar integration. Returns true if the integration was successful or false if it was not.

$.fn.agjCalendar([options])

$('#text-input').agjCalendar();

The $.fn.agjCalendar() function works similar to the $.agjCalendar() function but does not require the dateSelector option as you would be selecting the element and calling this function directly off of it. Returns the element to allow for chaining. We recommend using the $.agjCalendar() function if possible to be able to examine the return value to determine a successful integration.

$.agjCalendar.deactivate()

$.agjCalendar.deactivate();

The $.agjCalendar.deactivate() function will deactivate any active date pickers.

$.agjCalendar.isActive()

if ($.agjCalendar.isActive()) {
  alert('There is a date picker currently active!');
} else {
  alert('There are no date pickers currently active.');
}

The $.agjCalendar.isActive() function will determine whether or not any date pickers are active. Returns true if a date picker is active or false if none are.

Usage/Installation

You will need an HTML reference to jQuery in order for the the plugin to function.

<!-- Reference to the jQuery Javascript library -->
<script type="text/javascript" src="//code.jquery.com/jquery-3.7.1.js"></script>

With npm or Yarn

This plugin offers support for the npm and Yarn dependency managers. You can find the agjCalendar package online on npmjs.com.

Install using npm

Run this command to install the plugin using npm:

npm install agjcalendar

Install using Yarn

Run this command to install the plugin using Yarn:

yarn add agjcalendar

Once installed you can start using agjCalendar within your project by adding HTML references to the plugin’s Javascript and CSS stylesheet files.

<!-- Reference to the agjCalendar jQuery plugin -->
<script type="text/javascript" src="./node_modules/agjcalendar/source/agjCalendar/jquery.agjCalendar.js"></script>

<!-- Reference to the agjCalendar CSS stylesheet -->
<style type="text/css">@import './node_modules/agjcalendar/source/agjCalendar/jquery.agjCalendar.css';</style>

With Bower

This plugin also offers support for the now-deprecated Bower dependency manager.

Install using Bower

Run this command to install the plugin using Bower:

bower install andrewgjohnson/agjCalendar --save

Once installed you can start using agjCalendar within your project by adding HTML references to the plugin’s Javascript and CSS stylesheet files.

<!-- Reference to the agjCalendar jQuery plugin -->
<script type="text/javascript" src="./bower_components/agjCalendar/source/agjCalendar/jquery.agjCalendar.js"></script>

<!-- Reference to the agjCalendar CSS stylesheet -->
<style type="text/css">@import './bower_components/agjCalendar/source/agjCalendar/jquery.agjCalendar.css';</style>

Without npm, Yarn or Bower

To use without npm, Yarn or Bower add HTML references to the Javascript source and the CSS source which you will need to download and host.

<!-- Reference to the agjCalendar jQuery plugin -->
<script type="text/javascript" src="jquery.agjCalendar.min.js"></script>

<!-- Reference to the agjCalendar CSS stylesheet -->
<style type="text/css">@import 'jquery.agjCalendar.min.css';</style>

Help Requests

Please post any questions in the discussions area on GitHub if you need help.

If you discover a bug please enter an issue on GitHub. When submitting an issue please use our issue templates.

Contributing

Please read our contributing guidelines if you want to contribute.

You can contribute financially by becoming a patron at patreon.com/agjopensource to support agjCalendar and other agjjQuery.org plugins.

Acknowledgements

This plugin was started by Andrew G. Johnson (@andrewgjohnson).

Full list of contributors:

• Andrew G. Johnson (@andrewgjohnson)

Our security policies and procedures comes via the atomist/samples project. Our issue templates comes via the tensorflow/tensorflow project. Our pull request template comes via the stevemao/github-issue-templates project. The forest photo comes via Radek Homola.

Changelog

You can find all notable changes in the changelog.