Feature Proposal: JSCalendarContrib shall be corrected to allow usage of the built-in Time-Picker
Motivation
The feature already exists in the Javascript object displaying the Calendar, except that
JSCalendarContrib initialises the javascript forcing it to be never displayed. This is inconsistent with the documentation of
JSCalendarContrib that allows date
and time format specifiers. When you pass a format string including a string such as "%e %B %Y - %H:%M",
pub/System/JSCalendarContrib/foswiki.js
hardcodes and forces
cal.showsTime=false
even though the time format passed to the Contrib may contain hours and minutes, which is wrong.
The result is that the calendar does not display the time fields despite the fact that, according to the documentation of
JSCalendarContrib you can pass a format string such as:
%e %B %Y - %H:%M
If you do that in Foswiki, there are two problems :
- you don't get a time selector
- after you click on a date, the date and time according to the format you entered is displayed, i.e.: a time you haven't been able to define yourself, because the calendar was not allowing it
I believe that deactivation of the display of the time selection, by forcing always only dates is a
bug, since date and time format specification are allowed in the
JSCalendarContrib, and since what the user gets is an arbitrary time instead of a time he can select.
It is not acceptable to keep the
JSCalendarContrib in this state.
In addition to correcting a bug, this behaviour of the
JSCalendarContrib will allow us to use the pop-up Calendar to obtain a date and time, using a "date, 15, , %e %B %Y - %H:%M" in an with a
single column and formatted exactly as we need it.
Description and Documentation
Already documented time specifiers:
There are currently as many as 8 documented specifiers relating to time in Foswiki's
JSCalendarContrib documentation:
%H - hour ( 00 .. 23 )
%I - hour ( 01 .. 12 )
%k - hour ( 0 .. 23 )
%l - hour ( 1 .. 12 )
%M - minute ( 00 .. 59 )
%p - "PM" or "AM"
%P - "pm" or "am"
%S - second ( 00 .. 59 )
(in fact, 9 with the
%s
- number of seconds since Epoch)
As for the Foswiki documentation of
EditTablePlugin, it talks about "DHTML date format" without describing it effectively, and later refers to
JSCalendarContrib when talking about the default values.
My suggestion is that:
- JSCalendarContrib displays the Calendar's built-in time picker when the passed format descriptions includes hours, minutes or am or pm specifiers (i.e.:
%H, %I, %k, %l, %M, %p, %P
),
- and otherwise display the calendar normally with only dates if anything else or no format description is passed.
The documentation of
JSCalendarContrib should be updated to clarify this possible use. It would be good also that the documentation of
EditTablePlugin, is made more explicit about "DHTML date format", and the result produced when the date format includes times.
Explanation about the selected format specifiers :
- all hour and minutes specifiers are included (that is:
%H, %I, %k, %l, %M
)
- I am including
%p, %P
(PM/AM or pm/am) since selection of a time could be used to determine a date in the afternoon or in the morning
- I am not including
%S
(seconds) since JSCalendarContrib only allows selection of hours and minutes.
- I am not including
%s
(number of seconds since Epoch) since JSCalendarContrib would not, in any case, be second accurate
Examples
%EDITTABLE{header="| *Name* | *Appointment description* | *From* | *To* |" format="| text, 10 | textarea | date, 16, , %Y-%m-%d %H:%M | date, 16, , %Y-%m-%d %H:%M |" changerows="on" javascriptinterface="on"}%
Results in this:
- Use of Calendar to select time and date of a meeting:
%EDITTABLE{header="| *Name %BR% vacations* | *From* | *To* |" format="| text, 10 | date, 11 | date, 11 |" changerows="on" javascriptinterface="on"}%
Results in this:
- Customary use of the Calendar for selecting dates only:
Impact
This
should not impact the existing uses of
JSCalendarContrib, since without this change the time specifiers are not usable (despite they are documented).
Implementation
Proposed patch:
The implementation of this change is trivial. The following patch works against the current Trunk
diff --git a/JSCalendarContrib/pub/System/JSCalendarContrib/foswiki.js b/JSCalendarContrib/pub/System/JSCalendarContrib/foswiki.js
index f78759d..c79975c 100644
--- a/JSCalendarContrib/pub/System/JSCalendarContrib/foswiki.js
+++ b/JSCalendarContrib/pub/System/JSCalendarContrib/foswiki.js
@@ -1,4 +1,4 @@
function showCalendar(id,format){var el=document.getElementById(id);if(_dynarch_popupCalendar!=null){_dynarch_popupCalendar.hide();}else{var cal=new Calendar
(1,null,function(cal,date){cal.sel.value=date;if(cal.sel.onchange!=null)
cal.sel.onchange();if(cal.dateClicked)
-cal.callCloseHandler();},function(cal){cal.hide();_dynarch_popupCalendar=null;});cal.showsTime=false;cal.showsOtherMonths=true;_dynarch_popupCalendar=cal;cal
.setRange(1900,2070);cal.create();}
-_dynarch_popupCalendar.setDateFormat(format);_dynarch_popupCalendar.parseDate(el.value);_dynarch_popupCalendar.sel=el;_dynarch_popupCalendar.showAtElement(el
,"Br");return false;}
\ No newline at end of file
+cal.callCloseHandler();},function(cal){cal.hide();_dynarch_popupCalendar=null;});if(format.search(/%H|%I|%k|%l|%M|%p|%P/)!=-1){cal.showsTime=true;}else{cal.s
howsTime=false;}cal.showsOtherMonths=true;_dynarch_popupCalendar=cal;cal.setRange(1900,2070);cal.create();}
+_dynarch_popupCalendar.setDateFormat(format);_dynarch_popupCalendar.parseDate(el.value);_dynarch_popupCalendar.sel=el;_dynarch_popupCalendar.showAtElement(el
,"Br");return false;}
--
Contributors: RaulFRodriguez - 13 Mar 2010
Discussion
I initially reported this as
Tasks.Item8677. There
PaulHarvey and
CrawfordCurrie expressed their support to the correction of this, in the context described in
Tasks.Item8677.
I am filing this as a Feature Proposal as per
KennethLavrsen suggestion on the discuss list.
You may want to review:
--
RaulFRodriguez - 13 Mar 2010
Off-topic, but, I am still looking for a decent jQuery datepicker that also does time. Some options there but it would be nice to get something that used JQuery::UI
--
PaulHarvey - 13 Mar 2010
I think it is a decent, fully compatible, and very minor enhancement.
What is important to me as a user of this contrib everywhere is that the default behavior remains without the time. In most of my applications we are dealing with dates only.
As I understand Raul's description the time will only be shown in the UI and the resulting string when I add the time to the format. And that is perfect.
Raul - as you take on this task (which I am 99% sure will not raise concern) - could I kindly ask you to add documentation to the
JSCalendarContrib topic so the formats get documented. It is horrible that users have to visit the Mishoo site and navigate around quite a lot to find the syntax for the formats.
It should really be in the contrib documentation. And
EditTablePlugin can then also point to
JSCalendarContrib.
--
KennethLavrsen - 13 Mar 2010
Paul: have you had a look at
http://milesich.com/timepicker/ a
demo is also there. It supports a
showTime
setting also, to allow for selection of the regular date-picker only, or selection of the date-picker augmented with the time-picker additional interface when
showTime
is set to
true
. In one of the comments on this page, the author states, about the license that "It should have the same license as jQuery UI components so Dual licensed under the MIT and GPL licenses". No license statement is otherwise included in the source code in the current version.
Kenneth: thanks for your supporting comments. Yes, this Feature Proposal is not supposed to change the default behaviour. Regarding the documentation:
- the time format specifiers I refer to in the Feature Proposal above are already documented as existing specifiers in JSCalendarContrib (though they are not easy to find from EditTablePlugin)
- I suggest to add to the documentation of JSCalendarContrib the following clarification (hereafter in red):
An alternative to commonTagsHandler
is postRenderingHandler
which is more efficient since it is called less often.
Using the Calendar for picking dates only or picking times and dates
The calendar is able to display a time-picker, in addition to the default date-picker, depending on the optional date format passed.
- the calendar displays the built-in time picker when the passed format descriptions includes hours, minutes or am or pm specifiers (i.e.:
%H, %I, %k, %l, %M, %p, %P
),
- and otherwise display the calendar normally with only dates if anything else or no format description is passed.
You can also use the calendar directly in your own hand-built forms, without
- I suggest to add a small reference in System.EditTablePlugin#DateField which is the section in the documentation of this plugin where you are taken to, following the link in the "Per Table Settings" saying "(see Date Field Type)", which is supposed to give an explanation about the DHTML format (currently, it doesn't) - addition is in red colour:
Date Field Type
The date
field type allows one to choose a date with a popup calendar. Popup calendar works with all modern browsers. The date picker button is inactive if the browser cannot support the popup calendar or if javascript is disabled.
The optional DHTML date format specifiers are described in JSCalendarContrib. When time specifiers are used, the calendar allows one to choose a date and a time.
I suggest to add an anchor to the relevant
JSCalendarContrib section so that the user lands directly where needed.
--
RaulFRodriguez - 13 Mar 2010
My fault, yes the documentation is there today. I looked at the svn pseudo-install and missed the %$POD% that adds the actual documentation. Strange way to do this.
--
KennethLavrsen - 13 Mar 2010
Accepted by 14-day rule.
--
KennethLavrsen - 30 Mar 2010
I have checked-in the changes to Trunk (
Tasks.Item8677).
A test is available there
http://trunk.foswiki.org/Sandbox/TestJSCalendarContrib and seems to work well.
--
RaulFRodriguez - 01 Apr 2010