joomla/joomla-cms — pull request #4203 by purplebeanie (2014-09-01 00:33:23+00:00)
Title: RFC: Change to Datepicker / Calendar Fields

I'm a little nervous to fire off this PR as it turned out to to be a lot more complicated than I first thought.... But here goes.

This PR will need more work before it is ready but I wanted to get some feedback from others on the approach I have taken with the languages and the best way to demonstrate was with code. I have put some discussion questions at the end which was where I was seeking most feedback.

## The problem I'm trying to solve ##

* The current Joomla calendar picker is quite old, and based on feedback from an earlier question to the devcms list does not natively have support for non-Gregorian calendars.
* The current Joomla calendar picker has a fairly weak time picker that is not enabled, and currently cannot be turned on without changing the calendar behaviour.

## The calendar I have used ##

A user on the CMS list (Elvis) turned up the Keith Woods calendar picker from here (http://keith-wood.name/calendarsPicker.html). This is a modern, maintained calendar picker that includes:

* Support for RTL
* Support for non-Gregorian calendars
* Extensive localisation already done out of the box
* A good underlying calendaring JS library to allow conversions from one calendar to another

## The approach I have taken ##

After feedback from @Bakual I have included ALL calendars and localisation files as part of the base PR. The relevant language and localisation file is then loaded based on the language.

This PR introduces a new attribute to the Calendar form field XML caltype. This is set to one of the calendar types that the Keith Wood jQuery calendar plugin has support for. See the files in `/media/calendar/js` for complete listing. By default these are named jquery-calendars.persian.js etc.

If no caltype is specified a Gregorian calendar will be used.

Presently if using a calendar type other than Gregorian the conversion is done on the client side and the dates converted. I found doing some conversion on the server and some on the client resulted in drift due to the Browser time zone. Conversion needs to be done either all on the server, or all on the client. The reason for choosing client meant that the changes could all be contained within the JS injected by the Calendar behaviour.

## To test ##

Install this PR and go to a content item.

Focus on or click the button beside a calendar field and the new calendar picker will popup. This is the redmond theme which seemed the closest match for the present Joomla admin. There are a few css fixes in `/media/calendars/css/joomla-css-fixes.css`

![keith-picker-1](https://cloud.githubusercontent.com/assets/721410/4103682/228eb3a2-316e-11e4-92ae-e587936e2b78.png)

To use with a different language install the relevant Joomla language pack and login using the desired language. The calendar will load the correct localisation pack based on the language. These are from the calendar picker widget so may not be the same as the calendar strings defined in the Joomla language file.

To use with a different calendar open the form xml and add a `caltype="persian"` to the form attribute. For example if using a content article from administratator open `administrator/components/com_content/models/forms/article.xml` and for arguments sake set the created field to:

`
`

**A note for testing ** when loading the JS files using JHtml::_('script') I have used the / instead of the DIRECTORY_SEPERATOR constant. Is this okay or will this cause breaks? I also test for a file path using `if (!file_exists(JPATH_BASE.'/media/calendars/js/jquery-calendars-'. $langTag .'.js'))` again is this okay? or will they break on Windows?**

## Discussion Questions ##

* Presently the calendar is swapped per field based on using the caltype attribute in the form XML. Is this the best way?
* Is there a reason why a user would want to have several different calendar types in a form or should I swap this based on the user language as well?
* Is it safe to define a calendar based on language type? Would a Persian user for example want to use a Gregorian calendar?
* Is client side JS the best place to do conversion to / from Gregorian and chosen calendar?