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 :

1. you don't get a time selector
2. 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).

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

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:

• my initial message to Crawford and the discuss list
• Kenneth's response
• My response to Kenneth

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

Using the Calendar in user forms

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