Zeige letzte Bearbeiter
1 {{content/}}
2
3 In diesem Abschnitt wird erklärt, wie andere Datumsformate als das für Deutschland genutzt werden können.
4
5 {{figure image="designer_advanced_datepicker_de.png" width="600"}}
6 Beispiel für die Nutzung anderer Datumsformate. Für jedes Eingabefeld wird ein anderes Datumsformat eingestellt. Zudem wird die Validierung für das Datumsformat angepasst. Damit dies funktioniert, müssen zusätzlich noch die entsprechenden Sprachdateien eingebunden werden.
7 {{/figure}}
8
9 Grundsätzlich wird dabei wie folgt vorgegangen:
10
11 * Zur Datumsauswahl wird die Funktion //datepicker// der Bibliothek //jQueryUI// verwendet. [[Demo>>url:https://jqueryui.com/datepicker||rel="noopener noreferrer" target="_blank"]], [[Doku>>url:http://api.jqueryui.com/datepicker/||rel=" noopener noreferrer" target="_blank"]]
12 * Anpassbare Datumsformate werden von dieser Bibliothek unterstützt.
13 * In der Variable //jQuery.datepicker// befindet sich das globale Datepicker-Objekt. Es enthält auch einige Funktionen zur Formatieren eines Datums, [[siehe Doku>>url:http://api.jqueryui.com/datepicker/#utility-formatDate||rel="noopener noreferrer" target="_blank"]].
14 * In der Variable //$.datepicker.regional// finden sich fertige Voreinstellungen für verschiedene Länder, z.B. {{code language="javascript"}}$.datepicker.regional["fr"]{{/code}} für Frankreich.
15 * Um das Standarddatumsformat für alle Kalender zu ändern, kann die Funktion //setDefault// benutzt werden, z.B. {{code language="javascript"}}$.datepicker.setDefault($.datepicker.regional("fr")){{/code}}.
16 * Um für ein Eingabefeld das Datumsformat zu ändern, wird Eingabefeld mittels jQuery selektiert und die Funktion //datepicker// darauf aufgerufen: {{code language="javascript"}}$("[name='tfDateFr']").datepicker($.datepicker.regional["fr"]){{/code}}.
17 * Zudem ist eine Änderung der Validierung des Eingabefeldes notwendig. Hierfür kann der [[Datentyp regulärer Ausdruck>>doc:Formcycle.Designer.Form.FormElements.Input||anchor="HBedingungen"]] genutzt werden.
18
19 == Datumsformate hinzufügen ==
20
21 === Vorhandene Sprache ===
22
23 {{figure image="designer_advanced_datepicker_language_file.png" width="600"}}
24 In der heruntergeladenen Sprachdatei sollte die markierte Zeile entfernt werden. Die Sprache wird später im JavaScript des Formulars gesetzt.
25 {{/figure}}
26
27 Der Kalender wird mit den Sprachen Deutsch und Englisch bereitgestellt, die Standardsprache ist Deutsch. Zur Untersützung weiterer Sprachen muss zuerst die entsprechende Sprachdatei dem Formular hinzugefügt werden:
28
29 Die Sprachdateien [[können bei jQuery UI>>url:https://github.com/jquery/jquery-ui/tree/master/ui/i18n||rel="__blank"]] heruntergeladen werden.
30
31 Nun sollte für jede Sprachdatei eine kleine Anpassung vorgenommen werden. Am Ende der Sprachdatei wird folgende Zeile gelöscht:
32
33 {{code language="javascript"}}
34 datepicker.setDefaults( datepicker.regional.xx );
35 {{/code}}
36
37 Diese Sprachdateien können nun hochgeladen werden, entweder:
38
39 * als [[Formulardatei>>doc:Formcycle.UserInterface.MyForms.Files]], wenn die Sprachen nur für ein Formular benötigt werden, oder
40 * als [[Mandantdatei>>doc:Formcycle.UserInterface.FilesAndTemplates.Files]], wenn die Sprachen für alle Formulare zur Verfügung stehen sollen.
41
42 === Eigenes Datumsformat ===
43
44 Wenn erforderlich, kann auch ein eigenes Datumsformat erstellt werden. Hierzu kann etwa eine Sprachdatei genommen und angepasst werden. Es muss ein Eintrag in der Datumsformatsliste {{code language="javascript"}}$.datepicker.regional{{/code}} angelegt werden. Der Eintrag ist ein Objekt und kann folgende Untereinträge enthalten:
45
46 {{code language="none"}}
47 closeText, prevText, nextText,
48 currentText, monthNames, monthNamesShort,
49 dayNames, dayNamesShort, dayNamesMin,
50 weekHeader, dateFormat, firstDay,
51 isRTL, showMonthAfterYear, yearSuffix
52 {{/code}}
53
54 Eine Beschreibung dieser Einträge findet sich in der [[Doku>>url:http://api.jqueryui.com/1.8/datepicker/]].
55
56 == Datumsformat ändern ==
57
58 Nachdem die gewünschten Sprachdateien hochgeladen wurden, kann nun das Datumsformat im Formular geändert werden. Entweder kann das Standarddatumsformat für alle Eingabefelder geändert werden oder nur das Datumsformat für einige spezielle Eingabefelder. Zudem muss nach dem Ändern des Datumsformats noch die Validierung wie weiter unten beschrieben angepasst werden, sodass das neue Datumsformat korrekt erkannt wird.
59
60 === Globales Datumsformat festlegen ===
61
62 Falls das Datumsformat für alle Eingabefelder geändert werden soll, kann die Standardsprache entsprechend angepasst werden. Dazu wird eine neue JavaScript-Datei angelegt, zum Beispiel mit dem Name //datepicker-locale.js//. Diese JavaScript kann wie die Sprachdateien als Formular- oder Mandantdatei hochgeladen werden, je nachdem, ob die Einstellung nur für ein Formular oder für alle Formulare geändert werden soll.
63
64 Das Formular kann in verschiedenen Sprachen geöffnet werden. Um das Datumsformat anhand der aktuellen Sprache zu setzen, wird die JavaScript-Datei [[wie folgt befüllt>>attach:datepicker-locale.js||download="datepicker-locale.js"]]:
65
66 {{js}}
67 $(() => {
68 // Datumsformat für die aktuelle Sprache auslesen
69 const locale = $.datepicker.regional[XFC_METADATA.currentLanguageTag];
70 // Datumsformat als Standard setzen
71 // Ist das Datumsformat nicht vorhanden, wird Deutsch genommen
72 $.datepicker.setDefaults(locale || $.datepicker.regional["de"]);
73 });
74 {{/js}}
75
76 {{jsIE}}
77 $(function() {
78 // Datumsformat für die aktuelle Sprache auslesen
79 var locale = $.datepicker.regional[XFC_METADATA.currentLanguageTag];
80 // Datumsformat als Standard setzen
81 // Ist das Datumsformat nicht vorhanden, wird Deutsch genommen
82 $.datepicker.setDefaults(locale || $.datepicker.regional["de"]);
83 });
84 {{/jsIE}}
85
86 Für alle Eingabefeld im {{designer case="dat"/}}, bei denen der Datentyp auf Datum gesetzt ist, wird nun das geänderte Datumsformat verwendet. Beispielsweise kann das Formulars nun wie folgt aufgerufen werden:
87
88 {{code language="none"}}
89 # Auf Französisch
90 https://formcycle.eu/formcycle/form/provide/2152?lang=fr
91
92 # Auf Niederländisch
93 https://formcycle.eu/formcycle/form/provide/2152?lang=nl
94 {{/code}}
95
96 === Datumsformat pro Eingabefeld ändern ===
97
98 Falls die Sprache nur für einige Eingabefelder geändert werden soll, kann das Datumsformat im [[JavaScript-Bereich>>doc:WebHome]] geändert werden. Das Eingabefeld wird zuerst mit jQuery selektiert, dann wird der vorhandene Kalender entfernt und schließlich das gewünschte Datumsformat gesetzt:
99
100 {{js}}
101 // Formularfeld mit Namen "tfDateFr" auswählen
102 const tfDateFr = $("[name='tfDateFr']");
103
104 // Aktuellen Kalender entfernen
105 tfDateFr.datepicker("destroy");
106
107 // Kalender mit französischem Datumsformat aktivieren
108 tfDateFr.datepicker($.datepicker.regional.fr);
109 {{/js}}
110
111 {{jsIE}}
112 // Formularfeld mit Namen "tfDateFr" auswählen
113 var tfDateFr = $("[name='tfDateFr']");
114
115 // Aktuellen Kalender entfernen
116 tfDateFr.datepicker("destroy");
117
118 // Kalender mit französischem Datumsformat aktivieren
119 tfDateFr.datepicker($.datepicker.regional["fr"]);
120 {{/jsIE}}
121
122 == Datumsformat validieren ==
123
124 Da die Nutzung des Kalenders nicht zwingend ist und in Formularen von {{formcycle case="dat"/}} ein Datum auch direkt eingeben werden kann, ist noch eine Validierung des Datumsformats erforderlich. Standardmäßig wird auf das deutsche Datumsformat validiert. Zum Ändern gibt es zwei verschiedene Möglichkeiten:
125
126 === Mittels eigener Fehlerfunktion ===
127
128 {{warning}}
129 Bei Verwendung einer eigenen Validierungsfunktion sollte die serverseitige Validierung nicht aktiviert werden. Diese berücksichtigt selbstgeschriebene JavaScript-Logik nicht.
130 {{/warning}}
131
132 Falls nur das Standarddatumsformat geändert wurde, kann die Validierung für alle Datumsfelder mittels einer {{jsdoc page="jquery" name="errorfunc"}}eigenen Fehlerfunktion{{/jsdoc}} geändert werden. Folgender Code kann etwa mit in die [[oben erwähnte Datei datepicker-locale.js>>attach:datepicker-locale.js||download="datepicker-locale.js"]] geschrieben werden.
133
134 {{js}}
135 $(() => {
136 /**
137 * @param {JQuery} input
138 */
139 function checkDate(input) {
140 const dateFormat = input.datepicker("option", "dateFormat");
141 const settings = input.data("datepicker").settings;
142 const value = input.val();
143 try {
144 const date = $.datepicker.parseDate(dateFormat, value, settings);
145 return "";
146 }
147 catch (e) {
148 return XM_FORM_I18N.dateIntl || XM_FORM_I18N.dateDE;
149 }
150 }
151
152 $(".XTextField.hasDatepicker").each((_, el) => $(el).errorFunc(function() {
153 return checkDate($(this));
154 }));
155 });
156 {{/js}}
157
158 {{jsIE}}
159 $(function() {
160 function checkDate(input) {
161 var dateFormat = input.datepicker("option", "dateFormat");
162 var settings = input.data("datepicker").settings;
163 var value = input.val();
164 try {
165 var date = $.datepicker.parseDate(dateFormat, value, settings);
166 return "";
167 }
168 catch (e) {
169 return XM_FORM_I18N.dateIntl || XM_FORM_I18N.dateDE;
170 }
171 }
172
173 $(".XTextField.hasDatepicker").each(function(_, el) {
174 $(el).errorFunc(function() {
175 return checkDate($(this));
176 });
177 });
178 });
179 {{/jsIE}}
180
181 Hier wird geprüft, ob das eingegebene Datum ein gültiges Datum in Bezug auf das aktuelle Datumsformat ist. Ist das Datum ungültig, wird der Text der i18n-Variablen //dateIntl// ausgegeben. Diese i18n-Variable [[kann im Backend angelegt>>doc:Formcycle.UserInterface.FilesAndTemplates.I18nVariables]] und für die einzelnen Sprachen angepasst werden.
182
183 === Mittels RegExp ===
184
185 Diese Vorgehensweise empfiehlt sich, wenn das Datumsformat nur für einige Eingabefelder geändert wurde. Unter Bedingungen wird als Datentyp //regulärer Ausdruck// ausgewählt. Damit der Kalender erscheint, muss dabei manuell die Funktion {{code language="javascript"}}$.fn.datepicker{{/code}} aufgerufen worden sein. Hier kann nun das Muster für das Datumsformat und eine Fehlernachricht eingegeben werden. Für ein französisches Datumsformat etwa folgende RegExp:
186
187 {{code language="regexp"}}
188 ^(((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))))$
189 {{/code}}
190
191 == Weitere Script-Funktionen ==
192
193 Der Kalender der Bibliothek //jQuery UI// bietet noch vielfältige Möglichkeiten zur Interaktion und Konfiguration der Datumsauswahl. Diese sind in der [[Doku (englisch)>>url:http://api.jqueryui.com/datepicker/||rel="noopener noreferrer" target="_blank"]] ausführlich erläutert. Hier sollen die häufigsten Einsatzmöglichkeiten kurz dargestellt werden.
194
195 === Datum auslesen und setzen ===
196
197 Der aktuell in ein Datumsfeld eingetragene Textwert kann mittels der jQuery-Funktion //val// ausgelesen werden. Wird das Datum als Datumsobjekt benötigt, kann dies mittels der Funktion //getDate// ausgelesen und mittels JavaScript-Funktionen weiterverarbeitet werden. Analog kann ein beliebiges Datum mittels //setDate// gesetzt werden.
198
199 {{code language="javascript"}}
200 // Formatierten Wert auslesen
201 // "05.01.2017"
202 $("[name=tfDate]").val();
203
204 // Datumsobjekt auslesen
205 // "2017-01-04T23:00:00.000Z"
206 $("[name=tfDate]").datepicker("getDate").toISOString();
207
208 // Setzt Datum auf den 22. Mai 1990
209 $("[name=tfDate]").datepicker("setDate", new Date(1990,4,22));
210 {{/code}}
211
212 === Datum des Servers ===
213
214 Das aktuelle Datum von {{formcycle/}} steht als Datumsobjekt in {{jsdoc page="metadata" name="serverdate"/}}. Ein Datumsfeld kann auch mit diesem Datum vorbefüllt werden. Wenn das Datumsfeld //tfDate// heißt, kann folgendes JavaScript genutzt werden:
215
216 {{code language="javascript"}}
217 $("[name=tf1]").datepicker("setDate", XFC_METADATA.serverTime);
218 {{/code}}
219
220 === Datum formatieren ===
221
222 Mittels der JavaScript-Funktion {{code language="javascript"}}toLocaleDateString(locale){{/code}} kann ein Datum in einem landestypischen Format ausgegeben werden.
223
224 {{code language="javascript"}}
225 $("[name=tfDate]").datepicker("getDate").toLocaleDateString("de") // "05.01.2017"
226 $("[name=tfDate]").datepicker("getDate").toLocaleDateString("en") // "1/16/2017"
227 $("[name=tfDate]").datepicker("getDate").toLocaleDateString("fr") // "16/01/2017"
228 $("[name=tfDate]").datepicker("getDate").toLocaleDateString("ja") // "2017/1/16"
229 {{/code}}
230
231 Um beliebige Daten nach einem beliebigen Format zu formatieren, stellt jQuery UI eine Zusatzfunktion bereit:
232
233 {{code language="javascript"}}
234 $.datepicker.formatDate( format, date, options );
235 {{/code}}
236
237 Der Formatierungsstring kann folgende Formatierungsanweisungen enthalten.
238
239 {{table}}
240 |=Anweisung|=Bedeutung
241 |d|Tag des Monats, ohne führende Null
242 |dd|Tag des Monats, zweistellig
243 |o|Tag des Jahres, ohne führende Null
244 |oo|Tag des Jahres, dreistellig
245 |D|Kurzname des Tages, z.B. //Mon// oder //Mi//
246 |DD|Langname des Tages, z.B. //Montag// oder //Mittwoch//
247 |m|Monat, ohne führende Null
248 |mm|Monat, zweistellig
249 |M|Kurzname des Monats, z.B. //Jun.// oder //Dez.//
250 |MM|Langnames des Monats, z.B. //Juni// oder //Dezember//
251 |y|Jahr, zweistellig
252 |yy|Jahr, vierstellig
253 |@|Unixzeit (Anzahl Millisekunden seit 01.01.1970~)
254 |!|Windowszeit (Anzahl von 100ns seit 01.01.0001~)
255 {{/table}}
256
257 Optional kann als drittes Argument noch angegeben werden, welche Sprachvarianten für die Namen von Tagen und Monaten genutzt werden sollen.
258
259 {{code language="javascript"}}
260 // "16.01.2017 (Montag)"
261 $.datepicker.formatDate("dd.mm.yy (DD)", XFC_METADATA.serverTime);
262
263 // "17/1/5"
264 $.datepicker.formatDate("y/m/d", XFC_METADATA.serverTime);
265
266 // "16-01-2017 (Montag)"
267 $.datepicker.formatDate("dd-mm-yy (DD)", XFC_METADATA.serverTime);
268
269 // Französisches Datumsformat
270 // "16-01-2017 (janvier[janv.]-lundi[lun.])"
271 $.datepicker.formatDate("dd-mm-yy (MM[M]-DD[D])", new Date(), {
272 dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
273 dayNames: $.datepicker.regional[ "fr" ].dayNames,
274 monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
275 monthNames: $.datepicker.regional[ "fr" ].monthNames
276 });
277 {{/code}}
278
279 === Datum einlesen ===
280
281 Analog zum Formatieren kann mittels jQuery UI auch Text als Datum eingelesen werden:
282
283 {{code language="javascript"}}
284 $.datepicker.parseDate(format, value, options )
285 {{/code}}
286
287 Die Übergabeparameter für Datumsformat und die Optionen verhalten sich wie beim Formatieren eines Datums.
288
289 {{code language="javascript"}}
290 // Einlesen des Datums "5.Januar 2017"
291 $.datepicker.parseDate("dd-MM-yy", "05-Januar-2017", {
292 monthNames: $.datepicker.regional["de"].monthNames,
293 });
294
295 // Einlesen des Datums "05-Janvier-2017"
296 $.datepicker.parseDate("dd-MM-yy", "05-Janvier-2017", {
297 monthNames: $.datepicker.regional["fr"].monthNames,
298 });
299 {{/code}}