Hide last authors
gru 1.1 1 {{content/}}
2
sas 5.1 3 By default, the German date format is used. This section explains how you can use other date formats.
gru 1.1 4
sas 5.1 5 {{figure image="designer_advanced_datepicker_en.png" width="600"}}
6 An example for using other date formats. For each input field, you can set a different date format via JavaScript. This requires that you include a language file. You also need to make sure you change the validation appropriately so that it accounts for the new date format.
gru 1.1 7 {{/figure}}
8
sas 5.1 9 The following steps are necessary, explained in detail below:
gru 1.1 10
sas 5.1 11 * The user can select a date via a popup calendar. This is done with the function //datepicker// from the library //jQueryUI//: [[demo>>url:https://jqueryui.com/datepicker||rel="noopener noreferrer" target="_blank"]], [[docs>>url:http://api.jqueryui.com/datepicker/]]. This library supports different date formats.
12 * The global datepicker object is stored in //jQuery.datepicker//. It contains some utility functions for parsing and formatting a date, [[see for datepicker.formatdate>>url:http://api.jqueryui.com/datepicker/#utility-formatDate||rel="noopener noreferrer" target="_blank"]].
13 * Date format settings for different regions are stored in //$.datepicker.regional//, such as {{code language="javascript"}}$.datepicker.regional["fr"]{{/code}} for the French date format.
14 * To set the default date format, you can use the function //setDefault//: {{code language="javascript"}}$.datepicker.setDefault($.datepicker.regional("fr")){{/code}}.
15 * To change the date format for a single input field, select it and call the datepicker method: {{code language="javascript"}}$("[name='tfDateFr']").datepicker($.datepicker.regional["fr"]){{/code}}.
16 * You also need to modify the validation process so that it accounts for the new date format. This can be achieved with the datatype [[regular expression>>doc:Formcycle.Designer.Form.FormElements.Input||anchor="HBedingungen"]], or by setting up a custom {{jsdoc page="jquery" name="errorfunc"/}}.
gru 1.1 17
sas 5.1 18 == Adding a date format ==
gru 1.1 19
sas 5.1 20 === Existing language ===
gru 1.1 21
22 {{figure image="designer_advanced_datepicker_language_file.png" width="600"}}
sas 5.1 23 A language file containing the date format for a different region. You should delete the highlighted line in the language file. We will set the language to be used later in the form.
gru 1.1 24 {{/figure}}
25
sas 5.1 26 By default, the calendar ships with support for the two languages English and German, with German being the default. To support more languages or regions, you need to add the corresponding language file to the form:
gru 1.1 27
sas 5.1 28 You can download language files for many languages [[from the jQuery UI pages>>url:https://github.com/jquery/jquery-ui/tree/master/ui/i18n||rel="__blank"]].
gru 1.1 29
sas 5.1 30 For each language file you download, you should make a small edit: Delete the following line at the end of the language file:
gru 1.1 31
32 {{code language="javascript"}}
33 datepicker.setDefaults( datepicker.regional.xx );
34 {{/code}}
35
sas 5.1 36 Now you can upload the lanugage files, either
gru 1.1 37
sas 5.1 38 * as a [[form file>>doc:Formcycle.UserInterface.MyForms.Files]] when you only need them for a single form, or
39 * as a [[client file>>doc:Formcycle.UserInterface.FilesAndTemplates.Files]] to make it available for all forms.
gru 1.1 40
sas 5.1 41 === Own date format ===
gru 1.1 42
sas 5.1 43 If necessary, you can create and add your own custom date format. The easiest way to do so is to take an existing language files and edit it. You need to add an entry to the list of the date format in {{code language="javascript"}}$.datepicker.regional{{/code}}. This entry must be an object with the options for the date format. It may contain the following entries:
gru 1.1 44
45 {{code language="none"}}
46 closeText, prevText, nextText,
47 currentText, monthNames, monthNamesShort,
48 dayNames, dayNamesShort, dayNamesMin,
49 weekHeader, dateFormat, firstDay,
50 isRTL, showMonthAfterYear, yearSuffix
51 {{/code}}
52
sas 5.1 53 See the [[documentation>>url:http://api.jqueryui.com/1.8/datepicker/]] for more information on these options.
gru 1.1 54
sas 5.1 55 == Changing the date format ==
gru 1.1 56
sas 5.1 57 Once you added the language files, you can now change the date format for the form. You have two options: change the default date format or specify a different date format only for a certain input field. After you did that, you should also make sure the date format gets validated correctly, see below.
gru 1.1 58
sas 5.1 59 === Global date format ===
gru 1.1 60
sas 5.1 61 In case you would like to change the date format for all input fields, you can set the default language. Create a new JavaScript file and name it, for example, //datepicker-locale.js//. Upload this file as a client or form file, depending on whether you want the changes to apply to all forms or only a specific form.
gru 1.1 62
sas 5.1 63 Users may open the form in different languages. To set the date format depending on the current language, [[add the following code to the JavaScript file>>attach:datepicker-locale.js||download="datepicker-locale.js"]]:
gru 1.1 64
65 {{js}}
66 $(() => {
sas 5.1 67 // Get the date format for the current language
gru 1.1 68 const locale = $.datepicker.regional[XFC_METADATA.currentLanguageTag];
sas 5.1 69 // Set it as the default date format
70 // If no such date format was found, fall back to English
71 $.datepicker.setDefaults(locale || $.datepicker.regional["en"]);
gru 1.1 72 });
73 {{/js}}
74
75 {{jsIE}}
76 $(function() {
sas 5.1 77 // Get the date format for the current language
gru 1.1 78 var locale = $.datepicker.regional[XFC_METADATA.currentLanguageTag];
sas 5.1 79 // Set it as the default date format
80 // If no such date format was found, fall back to English
81 $.datepicker.setDefaults(locale || $.datepicker.regional["en"]);
gru 1.1 82 });
83 {{/jsIE}}
84
sas 5.1 85 The code above changes the default date format for all those input fields for which the datatype was set to //date//. Now users may open the form as follows:
gru 1.1 86
87 {{code language="none"}}
sas 5.1 88 # In French
gru 1.1 89 https://formcycle.eu/formcycle/form/provide/2152?lang=fr
90
sas 5.1 91 # In Dutch
gru 1.1 92 https://formcycle.eu/formcycle/form/provide/2152?lang=nl
93 {{/code}}
94
sas 5.1 95 === Specific input field ===
gru 1.1 96
sas 5.1 97 In case you only wish to change the date format for a single input field, go to the [[JavaScript tab>>doc:Formcycle.Designer.Form.CodingPanel.ScriptTab.WebHome]]. Select the input field with jQuery and call the datepicker method from jQuery UI:
gru 1.1 98
99 {{js}}
sas 5.1 100 // Select the input field named "tfDateFr"
gru 1.1 101 const tfDateFr = $("[name='tfDateFr']");
102
sas 5.1 103 // Remove the current calendar
gru 1.1 104 tfDateFr.datepicker("destroy");
105
sas 5.1 106 // Activate calendar with French date format
gru 1.1 107 tfDateFr.datepicker($.datepicker.regional.fr);
108 {{/js}}
109
110 {{jsIE}}
sas 5.1 111 // Select the input field named "tfDateFr"
gru 1.1 112 var tfDateFr = $("[name='tfDateFr']");
113
sas 5.1 114 // Remove the current calendar
gru 1.1 115 tfDateFr.datepicker("destroy");
116
sas 5.1 117 // Activate calendar with French date format
gru 1.1 118 tfDateFr.datepicker($.datepicker.regional["fr"]);
119 {{/jsIE}}
120
sas 5.1 121 == Validating the date format ==
gru 1.1 122
sas 5.1 123 Users may not use the calendar and enter the date directly, so you should validate the input and whether it represents a valid date according to the date format. By default, the validation process only checks for the German date format. To change it, there are two options.
gru 1.1 124
sas 5.1 125 === Via a custom error function ===
gru 1.1 126
127 {{warning}}
sas 5.1 128 When you use a custom error function, do not activate the option to validate the data on the server. It will not know about the JavaScript logic you added.
gru 1.1 129 {{/warning}}
130
sas 5.1 131 Use this method if you only changed the default date format. Add a custom {{jsdoc page="jquery" name="errorfunc"/}} to the date input fields. The following code can be added to the [[file datepicker-locale.js mentioned above>>attach:datepicker-locale.js||download="datepicker-locale.js"]]:
gru 1.1 132
133 {{js}}
134 $(() => {
135 /**
136 * @param {JQuery} input
137 */
138 function checkDate(input) {
139 const dateFormat = input.datepicker("option", "dateFormat");
140 const settings = input.data("datepicker").settings;
141 const value = input.val();
142 try {
143 const date = $.datepicker.parseDate(dateFormat, value, settings);
144 return "";
145 }
146 catch (e) {
147 return XM_FORM_I18N.dateIntl || XM_FORM_I18N.dateDE;
148 }
149 }
150
151 $(".XTextField.hasDatepicker").each((_, el) => $(el).errorFunc(function() {
152 return checkDate($(this));
153 }));
154 });
155 {{/js}}
156
157 {{jsIE}}
158 $(function() {
159 function checkDate(input) {
160 var dateFormat = input.datepicker("option", "dateFormat");
161 var settings = input.data("datepicker").settings;
162 var value = input.val();
163 try {
164 var date = $.datepicker.parseDate(dateFormat, value, settings);
165 return "";
166 }
167 catch (e) {
168 return XM_FORM_I18N.dateIntl || XM_FORM_I18N.dateDE;
169 }
170 }
171
172 $(".XTextField.hasDatepicker").each(function(_, el) {
173 $(el).errorFunc(function() {
174 return checkDate($(this));
175 });
176 });
177 });
178 {{/jsIE}}
179
sas 5.1 180 This code checks whether the entered date is valid, according to the current date format of the date input field. In case the entered date is invalid, show the error message from the i18n variable //dateIntl//. This i18n variable can be created or edited [[in the backend configuration>>doc:Formcycle.UserInterface.FilesAndTemplates.I18nVariables]]. You can use a different error message for each language.
gru 1.1 181
sas 5.1 182 === Via a regexp ===
gru 1.1 183
sas 5.1 184 Use this method in case you only changes the date format for a specific input field. Go to the constraints sections of the properties panel of the {{designer/}} and select the datatype //regular expression//. To get the calendar to show up, you need to call the method {{code language="javascript"}}$.fn.datepicker{{/code}} manually (this is also where you can specify the date format to be used). Now you can enter the regexp to validate the date format, and also enter a custom error message. For a french date:
gru 1.1 185
186 {{code language="regexp"}}
187 ^(((0[1-9]|[12]\d|3[01])\/(0[13578]|1[02])\/((19|[2-9]\d)\d{2}))|((0[1-9]|[12]\d|30)\/(0[13456789]|1[012])\/((19|[2-9]\d)\d{2}))|((0[1-9]|1\d|2[0-8])\/02\/((19|[2-9]\d)\d{2}))|(29\/02\/((1[6-9]|[2-9]\d)(0[48]|[2468][048]|[13579][26])|((16|[2468][048]|[3579][26])00))))$
188 {{/code}}
189
sas 5.1 190 == Additional script functions ==
gru 1.1 191
sas 5.1 192 The datepicker of the library jQuery UI offers some additional utility methods for working with dates, see also [[documentation>>url:http://api.jqueryui.com/datepicker/||rel="noopener noreferrer" target="_blank"]]. Here are some often used functions.
gru 1.1 193
sas 5.1 194 === Read and set the date ===
gru 1.1 195
sas 5.1 196 The text in the date input field is the formatted date and can be read via the jQuery function //$.fn.val//. If you need the date as a (parsed) date object for other custom JavaScript logic, you can read it via the method //getDate//, or set it with the method //setDate//.
gru 1.1 197
198 {{code language="javascript"}}
sas 5.1 199 // Read the formatted value
gru 1.1 200 // "05.01.2017"
201 $("[name=tfDate]").val();
202
sas 5.1 203 // Read the date as a date object
gru 1.1 204 // "2017-01-04T23:00:00.000Z"
205 $("[name=tfDate]").datepicker("getDate").toISOString();
206
sas 5.1 207 // Set the date to the 22nd of May, 1990
gru 1.1 208 $("[name=tfDate]").datepicker("setDate", new Date(1990,4,22));
209 {{/code}}
210
sas 5.1 211 === Server date ===
gru 1.1 212
sas 5.1 213 To access the current date of the server, independent of the browser, use {{jsdoc page="metadata" name="serverdate"/}}. You could also prefill a date input field with the current date:
gru 1.1 214
215 {{code language="javascript"}}
sas 5.1 216 // Write the current date to the input field named "tfDate"
217 $("[name=tfDate]").datepicker("setDate", XFC_METADATA.serverTime);
gru 1.1 218 {{/code}}
219
sas 5.1 220 === Format date ===
gru 1.1 221
sas 5.1 222 Use the utility function from jQuery UI to format a date according to a given date format:
gru 1.1 223
224 {{code language="javascript"}}
225 $.datepicker.formatDate( format, date, options );
226 {{/code}}
227
sas 5.1 228 For the third optional argument (the options) you can use one of the date format entries in {{code language="javascript"}}$.datepicker.regional{{/code}}. The first argument is a format string that may contain the following patterns:
gru 1.1 229
230 {{table}}
sas 5.1 231 |=Pattern|=Explanation
232 |d|Day of the month, without a leading zero
233 |dd|Day of the month, with a leading zero (two digits)
234 |o|Day of the year, without a leading zero
235 |oo|Day of the year, with a leading zero (three digits)
236 |D|Short day name, eg. //Mon// or //Wed//
237 |DD|Long day name, eg. //Monday// or //Wednesday//
238 |m|Month, without a leading zero
239 |mm|Month, with a leading zero (two digits)
240 |M|Short month name, eg. //Jun.// or //Dec.//
241 |MM|Long month name, eg. //June// or //December//
242 |y|Year, two digits
243 |yy|Year, four digits
244 |@|Unix time (milliseconds since 01.01.1970~)
245 |!|Windows time (Time since 01.01.0001~, in units of 100ns)
gru 1.1 246 {{/table}}
247
sas 5.1 248 For example:
gru 1.1 249
250 {{code language="javascript"}}
sas 5.1 251 // "16.01.2017 (Monday)"
gru 1.1 252 $.datepicker.formatDate("dd.mm.yy (DD)", XFC_METADATA.serverTime);
253
254 // "17/1/5"
255 $.datepicker.formatDate("y/m/d", XFC_METADATA.serverTime);
256
sas 5.1 257 // "16-01-2017 (Monday)"
gru 1.1 258 $.datepicker.formatDate("dd-mm-yy (DD)", XFC_METADATA.serverTime);
259
sas 5.1 260 // Force french date format
gru 1.1 261 // "16-01-2017 (janvier[janv.]-lundi[lun.])"
262 $.datepicker.formatDate("dd-mm-yy (MM[M]-DD[D])", new Date(), {
263 dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
264 dayNames: $.datepicker.regional[ "fr" ].dayNames,
265 monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
266 monthNames: $.datepicker.regional[ "fr" ].monthNames
267 });
268 {{/code}}
269
sas 5.1 270 === Parse date ===
gru 1.1 271
sas 5.1 272 Similar to how you can format a date, you can also parse a string as a date:
gru 1.1 273
274 {{code language="javascript"}}
275 $.datepicker.parseDate(format, value, options )
276 {{/code}}
277
sas 5.1 278 The first and third argument work the same way as with the function for formatting a date. For example:
gru 1.1 279
280 {{code language="javascript"}}
sas 5.1 281 // Read the date "05-Januar-2017"
gru 1.1 282 $.datepicker.parseDate("dd-MM-yy", "05-Januar-2017", {
283 monthNames: $.datepicker.regional["de"].monthNames,
284 });
285
sas 5.1 286 // Read the date "05-Janvier-2017"
gru 1.1 287 $.datepicker.parseDate("dd-MM-yy", "05-Janvier-2017", {
288 monthNames: $.datepicker.regional["fr"].monthNames,
289 });
290 {{/code}}