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
$('#text-input').agjCalendar();

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

// A more complex agjCalendar integration
$.agjCalendar({
  dateFormat:          'M j, Y',
  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.

Date Format Options

The plugin uses common date formating for the dateFormat, dateFormatDate, dateFormatDateTooltip, dateFormatDayInput, dateFormatDayOfWeekTooltip, dateFormatMonthDropdown, dateFormatMonthInput and dateFormatMonthLabel options. You can choose any combination of the below characters to format dates for users. The characters are based on PHP’s DateTime::format function which is in turn based on C Standard Library’s strftime function.

Warning: This plugin does not support timezones, all dates and times are treated timezone agnostically

Javascript Functions

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

$.agjCalendar([options])

var integration = $.agjCalendar({
  dateSelector: '#text-input'
});
if (integration !== -1) {
  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] [, callback])

var integration;
$('#text-input').agjCalendar({
  dateFormat: 'Y-m-d'
}, function(returnValue) {
  integration = returnValue;
});
if (integration !== -1) {
  alert('The integration was a success!');
} else {
  alert('The integration failed; check your Javascript console for details.');
}

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. This function also has an optional callback parameter that will be executed on completion of the integration attempt and will pass the integration attempt outcome into the callback’s first and only parameter.

$.agjCalendar.addRegexTextPattern(regexTextPattern)

$.agjCalendar.addRegexTextPattern('\u3040-\u30FF');

The $.agjCalendar.addRegexTextPattern() function will add a regular expression pattern to the plugin’s text checks. This function should be used if custom unicode characters are being used in custom translations. Our online documentation has more details on the translations page.

$.agjCalendar.dateToString(date, dateFormat[, translations])

var formattedDate = $.agjCalendar.dateToString(new Date(), 'j F Y');

The $.agjCalendar.dateToString() function will accept a date & date format and return a formatted string. It also accepts an optional translations parameters which is an object of translations (including day and month names) which will be used in the string, if no translations are passed the included English translations will be used. Read more about date format options and custom translations.

$.agjCalendar.deactivate()

$.agjCalendar.deactivate();

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

$.agjCalendar.disable(position)

var integration = $.agjCalendar({
  dateSelector: '#text-input'
});
if (integration !== -1) {
  $.agjCalendar.disable(integration);
}

The $.agjCalendar.disable() function will disable an agjCalendar integration after it has been initialized.

$.agjCalendar.disableEmojiSupport()

$.agjCalendar.disableEmojiSupport();

The $.agjCalendar.disableEmojiSupport() function will disable emoji support for custom translations.

Warning: Emoji support will have issues with older versions of Microsoft Internet Explorer specifically 6, 7, 8, 9, 10 and 11 as they don’t support ECMAScript 2018. To support older browsers we recommend using $.agjCalendar.addRegexTextPattern() and passing each emoji character you want to use.

$.agjCalendar.enableEmojiSupport()

$.agjCalendar.enableEmojiSupport();

The $.agjCalendar.enableEmojiSupport() function will enable emoji support for custom translations.

Warning: Emoji support will have issues with older versions of Microsoft Internet Explorer specifically 6, 7, 8, 9, 10 and 11 as they don’t support ECMAScript 2018. To support older browsers we recommend using $.agjCalendar.addRegexTextPattern() and passing each emoji character you want to use.

$.agjCalendar.getIncludedTranslations(language)

var dateInFrench = $.agjCalendar.dateToString(
  new Date(),
  'j F Y',
  $.agjCalendar.getIncludedTranslations('fr')
);

The $.agjCalendar.getIncludedTranslations() function will return an object of translations for one of the plugin’s included translations.

$.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.

$.agjCalendar.stringToDate(string, dateFormat[, translations])

var extractedDate = $.agjCalendar.stringToDate('1 January 2000', 'j F Y');
if (extractedDate !== -1) {
  alert('Date successfully extracted: ' + extractedDate);
} else {
  alert('The date extraction failed.');
}

The $.agjCalendar.stringToDate() function will accept a string & date format and return a date object. It also accepts an optional translations parameters which is an object of translations (including day and month names) which will be used in parsing the string, if no translations are passed the included English translations will be used. Read more about date format options and custom translations.

Usage/Installation

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

<!-- Reference to the jQuery Javascript library -->
<script type="text/javascript" src="//code.jquery.com/jquery-3.7.1.min.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. Run these commands to download them via the terminal:

curl -o jquery.agjCalendar.min.css 'https://agjCalendar.agjjQuery.org/source/agjCalendar/jquery.agjCalendar.min.css'
curl -o jquery.agjCalendar.min.js 'https://agjCalendar.agjjQuery.org/source/agjCalendar/jquery.agjCalendar.min.js'

Once downloaded, you must reference the files in your HTML:

<!-- 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>

Backwards Compatibility

The plugin strives to keep backwards compatibiltiy with all past releases. New features should be off by default with few exceptions. Changes to existing features should continue to support past options/values/configurations so older integrations of agjCalendar will continue to function without any need for change if their core plugin is updated.

List of Backward Compatibility Changes

Older Versions of jQuery

The plugin is designed to work with the newest version of jQuery (3.7.1) but will also work with older versions of jQuery 3.x as well as jQuery 2.x (tested up to 2.2.4) and jQuery 1.x (tested up to 1.12.4). We recommend using the newest version of jQuery.

Unit Testing

The plugin uses jQuery’s QUnit framework for unit testing. All units tests are located in the qunit.js file. The unit tests can be run online in-browser at agjCalendar.agjjQuery.org/tests/index.html. We strive to cover all public facing functions and API’s to ensure all permutations of parameters, options, fail scenarios, success scenarios, etc. are covered. Many novel scenarios are included in the unit tests to achieve high code coverage.

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.