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.
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
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.
Usage
Download justcal.js or justcal-min.js
Put it to your desired location
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.
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.
Property
Default
Description
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:
false
Use time in picker.
time12Mode:
false
AM/PM availability and 12-hours mode.
showSeconds:
false
Use time with seconds.
showExtraPane:
true
Extra 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
-1
First 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.
weekChars
2
Number of characters for a week day to show in a header (Su, Mo or Sun, Mon).
autoTime
true
Auto turn on showTime, time12Mode
and showSeconds
according to output format.
onlyTime
false
Use only time picker.
closeOnESC
true
Hide widget when ESC key is pressed.
persistent
false
If true, prevents hiding widget on clicking outside it.
draggable
true
Allows our widget to be dragged (default).
leftOffset
12
Left offset relative to current position of target element
(can be negative value).
topOffset
-12
Top 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 character
Description
Example returned values
Day
d
Day of the month, 2 digits with leading zeros
01 to 31
D
A textual representation of a day, three letters
Mon through Sun*
j
Day of the month without leading zeros
1 to 31
l (lowercase 'L')
A full textual representation of the day of the week
Sunday through Saturday*
w
Numeric representation of the day of the week
0 (for Sunday) through 6 (for Saturday)
Month
F
A full textual representation of a month, such as January or March
January through December*
m
Numeric representation of a month, with leading zeros
01 through 12
M
A short textual representation of a month, three letters
Jan through Dec*
n
Numeric representation of a month, without leading zeros
1 through 12
Year
Y
A full numeric representation of a year, 4 digits
1999 or 2003
y
A two digit representation of a year
99 or 03
Time
a
Lowercase Ante meridiem and Post meridiem
am or pm*
A
Uppercase Ante meridiem and Post meridiem
AM or PM*
g
12-hour format of an hour without leading zeros
1 through 12
G
24-hour format of an hour without leading zeros
0 through 23
h
12-hour format of an hour with leading zeros
01 through 12
H
24-hour format of an hour with leading zeros
00 through 23
i
Minutes with leading zeros
00 to 59
s
Seconds, with leading zeros
00 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.
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:
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
en - English (English)
ru - Russian (русский)
fr - French (français)
de - German (Deutsche)
zh - Chinese (中国的)
ja - Japanese (日本の)
ko - Korean (韓国の)
es - Spanish (español)
pt - Portuguese (portugués)
it - Italian (italiano)
fi - Finnish (suomi)
sv - Swedish (svensk)
uk - Ukrainian (український)
pl - Polish (polski)
ar - Arabic (عربي)
cs - Czech (český)
ka - Georgian (საქართველოს)
he - Hebrew (עִברִי)
hi - Hindi (हिंदी)
th - Thai (ภาษาไทย)
tr - Turkish (Türk)
nl - Dutch (Nederlands)
id - Indonesian (Indonesia)
bn - Bengali (বঙ্গ)
sr - Serbian (српски)
hy - Armenian (հայկական)
fa - Persian (فارسی)
el - Greek (ελληνικός)
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:
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):
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.