JustCal: a JavaScript Ultimate Slick Tiny Calendar

Description

JustCal stands for JavaScript Ultimate Slick Tiny CALendar (date-time picker).

It is standalone draggable multilingual calendar widget -
date and time picker.

It is easy to use, simple yet powerful
and highly configurable date-time picker
with seconds, AM-PM and keyboard support,
(about keyboard support - see section Accessibility below)
and wide-range format of input/output date/time values
(see section Format of date/time below).

It requires no extra files - no JavaScript libraries,
no any css or image files, it works just out of the box.

By default JustCal ships with 28 languages and 5 themes,
but if you do not want so many languages and themes,
you can build your own JustCal
(see sub-section Build your own JustCal in section Download below).

Also, you may fine tune any theme or add your language
by editing source code of justcal.js
(look for JustCal.getTheme and JustCal.getLang
methods in sources of the script).

JustCal is subject to MIT license, and you can use it in any product,
change source code and do what you want with it without permission.
See The MIT License (MIT) for the full text of this license.



Themes

[justcal 1] [justcal 2]
jungle
view with default options (theme:'jungle')
marine
theme: 'marine', lang: 'ru', navbar: 'compact'
[justcal 3] [justcal 4]
neutral
theme:'neutral', lang:'ja', navbar:'step'
frog
theme:'frog', lang:'hi', navbar:'select'
[justcal 5] [justcal 6]
orange
theme:'orange',lang:'nl', showExtraPane:false, format:'d-m-Y H:i:s'
only time (no theme)
onlyTime:true, format:'h:i:s'


Download

Choose download type of JustCal with 28 languages and 5 themes

JustCal normal (62.1 Kb)
JustCal minified (40.42 Kb)

Or download JustCal with only one language and one theme

Lang: Theme: Type:

Build your own JustCal

Additionally, you can download JustCal with several languages and themes.
Use Ctrl + mouse click to select/deselect several items.
Use Shift + mouse click to select a group of items.
First selected items will be set as default for lang and theme.
Please choose at least one lang and one theme before downloading
Lang: Theme: Type:


Usage

  1. Download justcal.js or justcal-min.js
  2. Put it to your desired location
  3. Make a link to it in you HTML page like this: <script src="justcal.js"></script>
Now you can use justCal(element [, options])
on almost any element where you wish your date/time should be in.
(note 'C' in uppercase in the name of this function).

If element is input element with type="text" or textarea element,
then it's value will be filled with selected date/time,
in other case it's innerHTML will be rewritten by given date/time.

Examples:
<input type="text" onclick="justCal(this, {lang:'de',persistent:true})">
or
<h3>Choose date/time</h3>
<p>
  <span id="datespan">2013-12-06 11:27:10</span>&nbsp;
  <img src="cal.png" 
    onclick="justCal('datespan',{format:'Y-m-d H:i:s',lang:'hi',theme:'frog'})"
    style="cursor:pointer">
</p>
You can pass JavaScript element as first parameter,
or you can pass a string with element id (e.g.: 'dtmId' or '#dtmId')
(hash sign (`#`) at the very beginning of the passed string will be sliced out).

The second parameter is optional, if it is omitted,
default values (see below) will be used.

If you wish to fine tune JustCal, you should pass an object
with specified properties as a second parameter to override any default setting.

Possible properties and their default values of options parameter
are shown in a table below.



Options

Note: '' in the second column stands for an empty string.


PropertyDefaultDescription
format'' Format of date/time.
Resembles format of PHP function `date()` with some restrictions
(for full set of possible values see section Format of date and time).
If not specified (is an empty string), it will be fetched from defaultFormat of current lang.
value''Predefined value for starting date/time which if set here will be used
instead of the value in target element.
showTime:falseUse time in picker.
time12Mode:falseAM/PM availability and 12-hours mode.
showSeconds:falseUse time with seconds.
showExtraPane:trueExtra panel with OK/Cancel buttons.
If false, simple click on date will choose it (insert into target element) and close widget.
If true (default), clicking on a date selects it, and when OK pressed, selected date will be inserted into target element.
navbar'both'Type of navigation bar: 'step', 'select', 'both' or 'compact'
See demo below.
dateLimit''May be 'future', 'past' or an empty string ('')
(if specified, allows to pick dates in the future or in the past only)
See demo below.
fromDate''Strings in format `Y-m-d` (e.g. '2010-05-23') (YYYY-MM-DD) which define limit of available dates for picking
By default all dates from Jan,1 of fromYear to Dec,31 of toYear (or dateLimit's past/future limits, if specified) are available to be picked.
toDate''
fromYear'-12'Values for the first/latest year in a drop down year selection.
Years could be 4-digit numbers of definite year
or offsets from the current year
(with `+` sign for toYear and `-` sign for fromYear).
toYear'+7'
dow-1First day of the week: 0 - Sun, 1 - Mon ... 6 - Sat
When not specified (e.g. == -1) it will be fetched from the dow property of the current lang.
weekChars2Number of characters for a week day to show in a header (Su, Mo or Sun, Mon).
autoTimetrueAuto turn on showTime, time12Mode and showSeconds
according to output format.
onlyTimefalseUse only time picker.
closeOnESCtrueHide widget when ESC key is pressed.
persistentfalseIf true, prevents hiding widget on clicking outside it.
draggabletrueAllows our widget to be dragged (default).
leftOffset12Left offset relative to current position of target element
(can be negative value).
topOffset-12Top offset relative to current position of target element
(can be negative value).
lang'en'Localization, can be one of the following strings:
'en', 'ru', 'fr', 'de', 'zh', 'ja', 'ko', 'es', 'pt', 'it', 'fi', 'sv', 'uk', 'pl', 'ar', 'cs', 'ka', 'he', 'hi', 'th', 'tr', 'nl', 'id', 'bn', 'sr', 'hy', 'fa', 'el'
See demo and section Localizations below.
Note: if you do not want to have so many localizations, you can download JustCal with only one or several langs (see sub-section Build your own JustCal in section Download above).
theme'jungle'Theme to use, available are:
'jungle', 'neutral', 'marine', 'frog', 'orange'
See demo below and section Themes above.
Note: if you do not want to have all these themes, you can download JustCal with only one or several themes (see sub-section Build your own JustCal in section Download above).


Format of date and time

Input/output format that JustCal uses resembles format
of date function in PHP language but with some restrictions.
For full list of possible values in it see the table below.

Note 1: Characters which are not shown in this table will be left untouched.

Note 2: All textual representations of months and week days and AM/PM strings are localized for respective localization (they are marked by * sign).


Format characterDescriptionExample returned values
Day
dDay of the month, 2 digits with leading zeros01 to 31
DA textual representation of a day, three lettersMon through Sun*
jDay of the month without leading zeros1 to 31
l (lowercase 'L')A full textual representation of the day of the weekSunday through Saturday*
wNumeric representation of the day of the week0 (for Sunday) through 6 (for Saturday)
Month
FA full textual representation of a month, such as January or MarchJanuary through December*
mNumeric representation of a month, with leading zeros01 through 12
MA short textual representation of a month, three lettersJan through Dec*
nNumeric representation of a month, without leading zeros1 through 12
Year
YA full numeric representation of a year, 4 digits1999 or 2003
yA two digit representation of a year99 or 03
Time
aLowercase Ante meridiem and Post meridiemam or pm*
AUppercase Ante meridiem and Post meridiemAM or PM*
g12-hour format of an hour without leading zeros1 through 12
G24-hour format of an hour without leading zeros0 through 23
h12-hour format of an hour with leading zeros01 through 12
H24-hour format of an hour with leading zeros00 through 23
iMinutes with leading zeros00 to 59
sSeconds, with leading zeros00 through 59


Demo and test

In this section you may try JustCal with different options,
such as lang, theme, navbar, dateLimit and others.

Change values in a form below and test JustCal.
options
showExtraPane: format: value:
lang: theme: navbar:
dateLimit: fromDate: toDate:
persistent: closeOnESC: onlyTime:
dow: topOffset: leftOffset:
Test JustCal Calendar (with options from above)
Enter date/time in this field:
[cal]
Or use this output:
03/23/2017 [cal]


Accessibility

JustCal can be accessed by keyboard only.

It supports cursor movements to select date by cursor keys and Enter key for submit selected date. Also it can be closed on ESC press by default.

So you are able to avoid using mouse at all with such code for example:
  <input name="datetime" onfocus="justCal(this,{format:'Y-m-d H:i:s'})">
When such input field catches focus (either by keyboard Tab press, or by mouse click)
JustCal datetime picker will pop up and you will be able to use cursor keys to move selected date
and press Enter to insert this date into text input, or press ESC to cancel.

Also you can change hours, minutes, seconds and AM/PM select box
by keyboard, accessing them by Tab key.


Localizations

JustCal supports many languages.
By now there are 28 localizations, which include
You can switch between languages dynamically, passing parameter lang in options:
justCal('dateAdd', { lang: 'he' });
In this example JustCal widget will be popped up with Hebrew language on the board:
[scr7]

Each localization includes textual representations of months and week days.
It can also include native AM/PM string if applicable
(in textAMPM property of the langs, defaults to ['AM','PM']),
and first day of the week (dow), which is equal to 0 (Sunday) for
en, zh, ja, ko, he, hi, th and is equal to 6 (Saturday) for
ar and fa localizations. For others it defaults to 1 (Monday).

Notice that you can change dow dynamically, passing its value from 0 to 6 in options parameter,
but you can not change textual string textAMPM in such a way.

All localizations were written with a little help from Moment.js (http://momentjs.com),
Google translator (http://translate.google.com)
and DateTime-Locale-0.45 on CPAN (http://search.cpan.org/~drolsky/DateTime-Locale-0.45)

If you find any error or discrepancy in these translations please report to justcal@beotiger.com.

JustCal uses UTF-8 without BOM encoding, so if you need to use it in different encoding, you should change character encoding properly. You can use iconv tool to do this, e.g. encode justcal.js to EUC-JP (Japanese):
iconv -f UTF-8 -t EUC-JP justcal.js > justcal-jp.js
Notice that changing default encoding can lead to broken symbols that are in non-ASCII character set.

Troubleshooting

If JustCal widget is not positioned correctly or broken,
check that your html page has correct layout - that is,
it should have a string <!DOCTYPE html> or alike at its very beginning,
or some browsers can render such page in quirks mode which should be avoided mostly.

  If you still need help, email to justcal@beotiger.com

Notes for JavaScript programmers: script justcal.js (or justcal-min.js)
spawns two global variables - window.justcal which represents JustCal class instance,
and function variable window.justCal (note uppercase 'C' in the name),
which is called to create a new instance of JustCal class and show JustCal widget.

So you should avoid using these names (justcal and justCal)
in global scope of your page that has JustCal widget.

Also notice that changing values of input or textarea elements by JustCal widget
triggers onchange event for the element.

Thank you for using JustCal