datepicker (Datumsformat anpassen)
In diesem Abschnitt wird erklärt, wie andere Datumsformate als das für Deutschland genutzt werden können.
Grundsätzlich wird dabei wie folgt vorgegangen:
- Zur Datumsauswahl wird die Funktion datepicker der Bibliothek jQueryUI verwendet. Demo, Doku
- Anpassbare Datumsformate werden von dieser Bibliothek unterstützt.
- In der Variable jQuery.datepicker befindet sich das globale Datepicker-Objekt. Es enthält auch einige Funktionen zur Formatieren eines Datums, siehe Doku.
- In der Variable $.datepicker.regional finden sich fertige Voreinstellungen für verschiedene Länder, z.B. $.datepicker.regional["fr"] für Frankreich.
- Um das Standarddatumsformat für alle Kalender zu ändern, kann die Funktion setDefault benutzt werden, z.B. $.datepicker.setDefault($.datepicker.regional("fr")).
- Um für ein Eingabefeld das Datumsformat zu ändern, wird Eingabefeld mittels jQuery selektiert und die Funktion datepicker darauf aufgerufen: $("[name='tfDateFr']").datepicker($.datepicker.regional["fr"]).
- Zudem ist eine Änderung der Validierung des Eingabefeldes notwendig. Hierfür kann der Datentyp regulärer Ausdruck genutzt werden.
Sprache hinzufügen
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:
Die Sprachdateien können bei jQuery UI heruntergeladen werden.
Nun sollte für jede Sprachdatei eine kleine Anpassung vorgenommen werden. Am Ende der Sprachdatei wird folgende Zeile gelöscht:
Diese Sprachdateien können nun hochgeladen werden, entweder:
- als Formularressource, wenn die Sprachen nur für ein Formular benötigt werden, oder
- als Mandantressource, wenn die Sprachen für alle Formulare zur Verfügung stehen sollen.
Globales Datumsformat festlegen
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 Mandantressource hochgeladen werden, je nachdem, ob die Einstellung nur für ein Formular oder für alle Formulare geändert werden soll.
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:
// Datumsformat für die aktuelle Sprache auslesen
const locale = $.datepicker.regional[XFC_METADATA.currentLanguageTag];
// Datumsformat als Standard setzen
// Ist das Datumsformat nicht vorhanden, wird Deutsch genommen
$.datepicker.setDefaults(locale || $.datepicker.regional["de"]);
});
Für alle Eingabefeld im Xima® Formcycle-Designer, bei denen der Datentyp auf Datum gesetzt ist, wird nun das geänderte Datumsformat verwendet. Beispielsweise kann das Formulars nun wie folgt aufgerufen werden:
https://formcycle.eu/formcycle/form/provide/2152?lang=fr
# Auf Niederländisch
https://formcycle.eu/formcycle/form/provide/2152?lang=nl
Datumsformat pro Eingabefeld ändern
Um das Standardformat mittels Javascript direkt zu ändern, geht man wie folgt vor.
Beispielweise für Französisch:
Oder für Niederländisch:
Steht die gewünschte Sprache mit dem dazugehörigen Datumsformat nicht zur Verfügung, kann ein eigenes erstellt werden, siehe hierzu den Abschnitt Datumsformate hinzufügen.
Es muss zudem noch der Validator für das Eingabefeld angepasst werden, s. unten Abschnitt (e).
Ändern des Datumsformat für ein Eingabeelement
Mit javascript kann das Datumsformat geändert werden. Es muss dazu erst mit jQuery das Eingabefeld (input) selektiert werden.
Zuerst wird der momentane Datepicker entfernt:
input.datepicker("destroy") // Entfernt den Datepicker.
Anschließend wird ein Datepicker mit dem gewünschten Format erstellt:
input.datepicker($.datepicker.regional['fr']) // Fügt einen Datepicker mit französischen Datumsformat ein.
Steht das gewünschte Land/Sprache/Datumsformat nicht zur Verfügung, kann ein eigenes erstellt werden, s. unten Abschnitt (d).
Es muss noch der Validator für das Eingabefeld angepasst werden, siehe hierzu den Abschnitt Datumsformat validieren.
Eigene Datumsformate hinzufügen
Es muss ein Eintrag in der Datumsformatsliste $.datepicker.regional angelegt werden, dieser kann dann für die Funktionen wie in den vorherigen beiden Abschnitten beschrieben verwendet werden. Der Eintrag ist ein Objekt und kann folgende Einträge enthalten:
Eine Beschreibung dieser Einträge findet sich in der Doku.
Als Beispiel sei das Datumsformat für Deutschland gegeben:
clearText: 'löschen',
clearStatus: 'aktuelles Datum löschen',
closeText: 'schließen',
closeStatus: 'ohne Änderungen schließen',
prevText: 'zurück',
prevStatus: 'letzten Monat zeigen',
nextText: 'vor',
nextStatus: 'nächsten Monat zeigen',
currentText: 'heute',
currentStatus: '',
monthNames: ['Januar','Februar','März','April','Mai', 'Juni', 'Juli','August','September','Oktober','November','Dezember'],
monthNamesShort: ['Jan','Feb','Mär','Apr','Mai','Jun', 'Jul','Aug','Sep','Okt','Nov','Dez'],
monthStatus: 'anderen Monat anzeigen',
yearStatus: 'anderes Jahr anzeigen',
weekHeader: 'KW',
weekStatus: 'Woche des Monats',
dayNames: ['Sonntag','Montag','Dienstag','Mittwoch','Donnerstag','Freitag','Samstag'],
dayNamesShort: ['So','Mo','Di','Mi','Do','Fr','Sa'],
dayNamesMin: ['So','Mo','Di','Mi','Do','Fr','Sa'],
dayStatus: 'Setze DD als ersten Wochentag',
dateStatus: 'Wähle D, M d',
dateFormat: 'dd.mm.yy',
firstDay: 1,
yearSuffix: '',
showMonthAfterYear: false,
initStatus: 'Wähle ein Datum',
isRTL: false,
changeYear: true,
yearRange: '1900:' + (new Date().getFullYear() + 100),
onClose: function(){$(this).validate();}
}
Datumsformat validieren
Da die Nutzung des Kalenders nicht zwingend ist und in Formularen von Xima® Formcycle 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:
Regulären Ausdruck ändern
Siehe hierzu auch den Bereich Validatoren.
Xima® Formcycle validiert mithilfe von regulären Ausdrücken. Am <input>-Element befindet sich das Attribut vdt (=Validation Data Type). Zum Validieren wird der reguläre Ausdruck genommen, der sich in der globalen Variable XM_FORM_VRULES im Eintrag des Wertes des Attributs vdt findet. Weiterhin sollte auch der entsprechende Eintrag in der globalen Variable XM_FORM_I18N geändert werden, hier findet sich die Fehlermeldung, die erscheint, wenn ein ungültiges Datumsformat eingegeben wurde.
Beispiel für ein Datums-Eingabefeld:
Das Attribut vdt hat hier den Wert dateDE. In XM_FORM_VRULES["dateDE"] findet sich der folgende reguläre Ausdruck:
Um nun auf ein anderes Datumsformat zu validieren, wird mittels Javascript das Attribut vdt geändert und ein entsprechender Eintrag zu XM_FORM_RULES hinzugefügt.
Beispiel: Französisches Datumsformat. Ein Eingabefeld mit dem Namen tfFR sei angelegt und als Datentyp bereits Datum ausgewählt. Im Javascript fügt man dann folgendes hinzu:
fr.datepicker('destroy') // Alten Datepicker auflösen.
fr.datepicker($.datepicker.regional['fr']) // Neuen Datepicker für Französisch hinzufügen.
fr.attr("vdt","dateFR") // Attribut für Validierung setzen.
XM_FORM_VRULES["dateFR"] = /^(((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))))$/ // Regulären Ausdruck für die Validierung hinzufügen.
XM_FORM_I18N["dateFR"] = "La date doit être indiquée comme suit : année/mois/jour." // Fehlertext hinzufügen.
Eigene Fehlerfunktion schreiben
Siehe hierzu auch errorFunc().
Da reguläre Ausdrücke recht umfangreich werden können, kann auch eine javascript-Funktion für die Validierung geschrieben werden. Dies geschieht mittels der Funktion errorFunc().
Ist bereits der Datentyp im Xima® Formcycle-Designer auf Datum gesetzt, wird dieser durch Entfernen des Attributs vdt entfernt. Alternativ kann man aber auch den Datentyp auf "Text" setzen. Der Kalender wird dann mittels der Funktion datepicker hinzugefügt, siehe (d).
Beispiel für Niederländisch:
// http://stackoverflow.com/questions/6177975/how-to-validate-date-with-format-mm-dd-yyyy-in-javascript
var checkDate = function(year,month,day){
// Check the ranges of month and year
if(year < 1000 || year > 3000 || month === 0 || month > 12){return false}
var monthLength = [ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 ]
// Adjust for leap years
if(year % 400 === 0 || (year % 100 !== 0 && year % 4 === 0)){monthLength[1] = 29}
// Check the range of the day
return day > 0 && day <= monthLength[month - 1]
}
// Validierungsfunktion für Niederländisches Datum.
var nlDateValidate = function(){
var msg = "Ongeldig datumformaat."
var me = $(this)
var text = me.val()
var comp = text.match(/^(\d+)\-(\d+)\-(\d+)$/)
if (!comp){return msg};
var d = parseInt(comp[1])
var m = parseInt(comp[2])
var y = parseInt(comp[3])
if (checkDate(y,m,d)){
return true
}
else {
return msg
}
}
var nl = $('[name="tfNL"]') // Selektiert Element mit Namen "tfNL".
nl.datepicker($.datepicker.regional['nl']) // Datepicker hinzufügen.
nl.errorFunc(nlDateValidate) // Validierungsfunktion setzen.
Weitere Funktionen
Der datepicker der Bibliothek jQuery UI bietet noch vielfältige Möglichkeiten zur Interaktion und Konfiguration der Datumsauswahl. Diese sind in der Doku (englisch) ausführlich erläutert, hier sollen die häufigsten Einsatzmöglichkeiten kurz dargestellt werden.
Datum auslesen und setzen
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.
$("[name=tfDate]").datepicker("getDate").toISOString // "2017-01-04T23:00:00.000Z"
$("[name=tfDate]").datepicker("getDate").toLocaleDateString("de") // "05.01.2017"
$("[name=tfDate]").datepicker("setDate", new Date(2014,3,14)) // Setzt Datum auf 14. März 2014
Ein Datumsfeld kann wie folgt auf das derzeitige Datum des Browsers gesetzt werden.
Datum des Servers
Das aktuelle Datum von Xima® Formcycle steht als Datumsobjekt im Objekt XFC_METADATA im Eintrag serverTime. Ein Datumsfeld kann auch mit diesem Datum vorbefüllt werden. Wenn das Datumsfeld tfDate heißt, kann folgendes JavaScript genutzt werden.
Daten formatieren
Mittels der JavaScript-Funktion toLocaleDateString(locale) kann ein Datum in einem landestypischen Format ausgegeben werden.
$("[name=tfDate]").datepicker("getDate").toLocaleDateString("en") // "1/16/2017"
$("[name=tfDate]").datepicker("getDate").toLocaleDateString("fr") // "16/01/2017"
$("[name=tfDate]").datepicker("getDate").toLocaleDateString("ja") // "2017/1/16"
Um beliebige Daten nach einem beliebigen Format zu formatieren, stellt jQuery UI Zusatzfunktion im Objekt jQuery.datepicker bereit. Konkret kann hierzu die Funktion jQuery.datepicker.formatDate( format, date, options ) genutzt werden.
Der Formatierungsstring kann folgende Formatierungsanweisungen enthalten.
| Anweisung | Bedeutung |
|---|---|
| d | Tag des Monats, ohne führende Null |
| dd | Tag des Monats, zweistellig |
| o | Tag des Jahres, ohne führende Null |
| oo | Tag des Jahres, dreistellig |
| D | Kurzname des Tages, z.B. Mon oder Mi |
| DD | Langname des Tages, z.B. Montag oder Mittwoch |
| m | Monat, ohne führende Null |
| mm | Monat, zweistellig |
| M | Kurzname des Monats, z.B. Jun. oder Dez. |
| MM | Langnames des Monats, z.B. Juni oder Dezember |
| y | Jahr, zweistellig |
| yy | Jahr, viestellig |
| @ | Unixzeit (Anzahl Millisekunden seit 01.01.1970) |
| ! | Windowszeit (Anzahl von 100ns seit 01.01.0001) |
Optional kann als drittes Argument noch angegeben werden, welche Sprachvarianten für die Namen von Tagen und Monaten genutzt werden sollen.
$.datepicker.formatDate("dd.mm.yy (DD)", XFC_METADATA.serverTime) // => "16.01.2017 (Montag)"
$.datepicker.formatDate("y/m/d", $("[name=tfDate]").datepicker("getDate")) // => "17/1/5"
$.datepicker.formatDate("dd-mm-yy (DD)", new Date()) // => "16-01-2017 (Montag)"
$.datepicker.formatDate("dd-mm-yy (MM[M]-DD[D])", new Date(), {
dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
dayNames: $.datepicker.regional[ "fr" ].dayNames,
monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
monthNames: $.datepicker.regional[ "fr" ].monthNames
}) // => "16-01-2017 (janvier[janv.]-lundi[lun.])"
Daten einlesen
Analog zum Formatieren kann auch mittels Funktion jQuery.datepicker.parseDate(format, value, options ) ein Datummstring eingelesen werden. Das Datumsformat und die Optionen sind analog zu jQuery.datepicker.formatDate(format, date, options ).
$.datepicker.parseDate("dd-MM-yy", "05-Janvier-2017", {monthNames: $.datepicker.regional[ "fr" ].monthNames}) // Einlesen des Datums 5.Januar 2017