datepicker.gtw

~~LANG:FR@frman:composants/jforms/xml/datepicker~~

If you want to have a datepicker in your form, you should use the @@E@<date>@@
element (or @@E@<datetime>@@ for date + time).

<code xml>
  <date ref="birthday">
     <label>Birthday</label>
  </date>
</code>

You can change the configuration of datapickers, and change the datepicker for
an other one with the attribute @@A@datepicker@@.


===== General configuration of datepickers =====

In the section @@forms@@ of the configuration file of jelix, you can configure
the default datepicker used by jelix:

<code ini>
[forms] 
controls.datetime.input = "menulists" 
controls.datetime.months.labels = "names" 
</code>  


@@controls.datetime.input@@ indicates the type of input: "textboxes" if you want
textboxes, or "menulists" for menulist. In both cases, an additionnal button
while be displayed and will allow you to choose the date with a calendar.
 
@@controls.datetime.months.labels@@ indicates if menulists should display
numbers, names or shortnames for monthes (respectively "numbers", "names",
"shortnames").

===== Using an other type of datepicker =====

By default, jForms uses the datepicker of jQuery UI. But you can use an other
datepicker, or configure the default one in an other manner.

Each type datepicker has its own JS and CSS file. To declare them, we are using
[[/modules/views/view-html|webassets]]. The webassets group for a datapicker should have
a name with the datepicker name and a prefix @@jforms_datepicker_@@. 
The webassets group for the datepicker @@default@@ is:

<code ini>
[webassets_common]

;...

jforms_datepicker_default.css=
jforms_datepicker_default.js[]="$jelix/jquery/ui-datepicker/i18n/datepicker-$lang.js"
jforms_datepicker_default.js[]="$jelix/js/jforms/datepickers/default/init.js"
jforms_datepicker_default.require=jquery_ui

</code>


The default datepicker to use in each form should be indicated in the
@@datepicker@@ option in the section @@forms@@. Here is the default 
configuration:

<code ini>
[forms]
;...
datepicker = default 

</code>

In a form, to indicate a specific type of datepicker, use the @@A@datepicker@@
attribute on the element @@E@<date>@@.

===== Creating a type of datepicker =====

To create a new type of datepicker, you have to create a javascript file which
contains a function. The goal of this function is to initialise the datepicker.

Its name should be @@f@jelix_datepicker_<datapicker name>@@ where
@@<datapicker name>@@ is the datepicker name (used in the webassets group etc). 

The function should accept this arguments:

   * a javascript object (@@C@jFormsJQControlDate@@ or @@C@jFormsJQControlDatetime@@ 
      with the default jforms builder) which contains some properties like the name 
      of the field (@@P@name@@), the maximum date (@@P@maxDate@@) or the minimum 
      date (@@P@minDate@@).
   * a javascript object containing this configuration parameters
     * @@P@locale@@: the language code (valueof jApp::config()->locale)
     * @@P@basePath@@: the value of basePath
     * @@P@jqueryPath@@: The URL path to the jquery library
     * @@P@jelixWWWPath@@: The URL path to the jelix-www content.

The function is called for each datepicker of the form, and should initialize
(or create) a datepicker on the different fields needed for the date. jForms
generate three fields for a datepicker (day, month, hour). Their names began by
the name of form plus the name of the control. Example, for a form
"sample.form.xml" in a module "testapp" of the application, and which contains a
control @@E@<date>@@ named "birthday", you then will have some html field:
"jforms_testapp_sample_birthday_month", "jforms_testapp_sample_birthday_day",
and "jforms_testapp_sample_birthday_year".