Inhalt

Mit dem kostenlosen Datums-Hilfswerkzeuge-Plugin für FORMCYCLE besteht die Möglichkeit, Datumsfunktionen, Berechnungen und Validierungen durchzuführen.

Das Plugin befindet sich derzeit noch in der Erprobungsphase und ist ab Version 8.1.0 verfügbar. Es konzentriert sich hauptsächlich auf Datumsberechnungen, die speziell für Deutschland geeignet sind.

Derzeit besteht die Einschränkung, dass die Funktionalitäten nicht in Wiederholungen zur Verfügung stehen. Wiederholungen werden seit Version 1.3.0 des Plugins unterstützt.

Installation

Die Installation des Plugins ist über die dafür vorgesehene Verwaltungsoberfläche von Plugins durchzuführen. Hierbei muss lediglich die entsprechende JAR-Datei eingespielt werden bzw. das Plugin aus dem Plugin-Store Installiert werden.

Funktionalität

Das Plugin enthält eine JavaScript-Bibliothek und stellt eine Reihe von Hilfsfunktionen bereit, die über $.xdate verfügbar sind. 

Zusätzlich bietet der Designer Funktionen zur Konfiguration von Datumsvergleichen. Mit diesen Funktionen kann festgelegt werden, ob ein Datum vor, vor gleich, nach oder nach gleich einem bestimmten Datum liegt. 

Als Wert muss entweder ein festes Datum im Format TT.MM.JJJ wie 31.03.2024 eingegeben werden oder eine Datumsformel. Eine Datumsformel hat das folgende Muster:

<Datum> +/- <Zeitspanne>

Die Zeitspanne ist optional und kann verwendet werden, um das Datum anzupassen. Möglich ist die Angaben von Jahren [%$DATE%]+2y (heute plus 2 Jahre), von Monaten [%$DATE%]+2m (heute plus 2 Monate) oder von Tagen [%$DATE%]+2d (heute plus 2 Tage). Diese können auch gemischt werden, z.B. [%$FORM_DATE_CREATED%]-5y3m1d (Erstellungsdatum minus 5 Jahre, 3 Monate, 1Tag).

Nach der Konfiguration passt sich automatisch der Kalender an, um die ausgewählten Tage im Datepicker anzuzeigen. 

Zusätzlich können noch Einstellungen für die Anzeige der Tage im Kalender vorgenommen werden:

• Wochenende anzeigen: Wochenenden (Sonnabend und Sonntag) werden im Kalender rot markiert
• Feiertage anzeigen: Feiertage werden im Kalender rot markiert
• Sonnabende deaktivieren: Verbietet die Auswahl von Sonnabenden im Kalender
• Sonntage deaktivieren: Verbietet die Auswahl von Sonntagen im Kalender
• Feiertage deaktivieren: Verbietet die Auswahl von Feiertagen im Kalender

In Kombination mit Berechnungsfeldern können z.B. Funktionen wie

$.xdate.getBusinessDaysBetween("[%tfUrlaubVom%]", "[%tfUrlaubBis%]", "bw")

aufgerufen werden, um die Anzahl der Werktage abzüglich von Feiertagen und Wochenenden zu berechnen. Im folgendes werden alle Funktion des Hilfsobjekts $.xdate beschrieben.

Hilfsobjekt $.xdate:

Hinweis 1: Überall, wo der Typ von Datums-Parametern als unknown angegeben wird, sind aktuell folgende Werte möglich:

• Festes Datum als String, z.B. 12.03.2025
• Datumsformel als String, z.B. [%tf1%] + 3d
• Festes Datum als Date-Objekt
• Formularfeld, entweder als HTMLElement oder JQuery-Instanz.

Hinweis 2: Das Format des Datumsformats ist das Format des JQuery-UI-Datepickers, siehe deren Dokumentation.

Folgende Funktionen stehen zur Verfügung:

• setFormat(format)

  - Beschreibung: Legt das Standard-Datumsformat für alle Formulare der Webseite fest.
  - Parameter:
  - format (string): Das zu setzende Datumsformat.
  - Rückgabewert: keiner
  - Beispiel:

  $.xdate.setFormat("dd.mm.yy");

• getFormat()

  - Beschreibung: Ruft das aktuelle Standard-Datumsformat für alle Formulare der Webseite ab.
  - Rückgabewert (string): Das aktuelle Datumsformat als String.
  - Beispiel:

  // Ergebnis: "dd.mm.yy"
  const format = $.xdate.getFormat();

• getDaysDifference(startDate, endDate)

  - Beschreibung: Berechnet die Differenz in Tagen zwischen zwei Datumswerten, endDate - startDate. Die Tage werden abgerundet.
  - Parameter:
  - startDate (unknown): Das Startdatum
  - endDate (unknown): Das Enddatum.
  - Rückgabewert (number): Die Differenz in Tagen als Ganzzahl.
  - Beispiel:

  // Ergebnis: 10
  const diff = $.xdate.getDaysDifference("10.06.2023", "20.06.2023");
  
  // Ergebnis: 10 (abgerundet)
  const diff = $.xdate.getDaysDifference(new Date(2023, 5, 10, 11, 0), new Date(2023, 5, 20, 23, 0));
  
  // Ergebnis: -11 (negativ, abgerundet nach negativer Unendlichkeit)
  $.xdate.getDaysDifference(new Date(2023, 5, 20, 23, 0), new Date(2023, 5, 10, 11, 0));

• getDaysBetween(endDate, startDate)

  - Beschreibung: Berechnet die Anzahl der Tage zwischen zwei Datumswerten. Das Ergebnis ist immer positiv und äquivalent zum Betrag des Ergebnisses von $.xdate.getDaysDifference.
  - Parameter:
  - endDate (unknown): Das Enddatum.
  - startDate (unknown): Das Startdatum.
  - Rückgabewert (number): Die Anzahl der Tage als nicht-negative Ganzzahl.
  - Beispiel:

  // Ergebnis: 10
  $.xdate.getDaysBetween("20.06.2023", "10.06.2023");
  
  // Ergebnis: 10 (abgerundet)
  $.xdate.getDaysBetween(new Date(2023, 5, 20, 23, 0), new Date(2023, 5, 10, 11, 0));
  
  // Ergebnis: 11 (Betrag, abgerundet nach negativer Unendlichkeit)
  $.xdate.getDaysBetween(new Date(2023, 5, 10, 11, 0), new Date(2023, 5, 20, 23, 0))

• getWeekdaysBetween(startDate, endDate)

  - Beschreibung: Berechnet die Anzahl der Werktage zwischen zwei Datumswerten. Das Anfangs- und Enddatum werden mitgezählt.
  - Parameter:
  - startDate (unknown): Das erste Datum.
  - endDate (unknown): Das zweite Datum.
  - Rückgabewert (number): Die Anzahl der Werktage als Ganzzahl.
  - Beispiel:

  // Ergebnis 7
  $.xdate.getWeekdaysBetween("10.06.2023", "20.06.2023");
  
  // Ergebnis 7
  $.xdate.getWeekdaysBetween("20.06.2023", "10.06.2023");
  
  // Ergebnis 1
  $.xdate.getWeekdaysBetween("20.06.2023", "20.06.2023")

• getAge(birthDate)

  - Beschreibung: Berechnet das Alter anhand eines Geburtsdatums. Es wird die Anzahl der Jahre zwischen dem angegebenen Geburtsdatum un dem aktuellen Datum ermittelt.
  - Parameter:
  - birthDate (unknown): Das Geburtsdatum.
  - Rückgabewert (number): Das Alter als Ganzzahl.
  - Beispiel:

  // Angenommen, heute ist der 2. September 2025
  
  // Ergebnis: 25
  $.xdate.getAge("10.06.2000");
  
  // Ergebnis: -15
  $.xdate.getAge("10.06.2040");

• isDateBefore(date1, date2)

  - Beschreibung: Überprüft, ob das 1. Datum vor dem 2. Datum liegt. Es wird die Anzahl der vollen Tagen zwischen den Daten geprüft, siehe auch $.xdate.getDaysDifference.
  - Parameter:
  - d1 (unknown): Das erste Datum.
  - d2 (unknown): Das zweite Datum.
  - Rückgabewert (boolean): Ein boolescher Wert (true / false), der angibt, ob das erste Datum vor dem zweiten liegt.
  - Beispiel:

  // Ergebnis: false
  $.xdate.isDateBefore("20.06.2023", "10.06.2023");
  
  // Ergebnis: true
  $.xdate.isDateBefore("10.06.2023", "20.06.2023");
  
  // Ergebnis: false
  $.xdate.isDateBefore("10.06.2023", "10.06.2023");
  
  // Ergebnis: true (Anzahl der vollen Tage zwischen Daten ist -1) 
  $.xdate.isDateBefore(new Date(2023, 5, 10, 12, 0), new Date(2023, 5, 11, 8, 0));

• isDateAfter(date1, date2)

  - Beschreibung: Überprüft, ob das 1. Datum nach dem 2. Datum liegt. Es wird die Anzahl der vollen Tagen zwischen den Daten geprüft, siehe auch $.xdate.getDaysDifference.
  - Parameter:
  - date1 (unknown): Das erste Datum.
  - date2 (unknown): Das zweite Datum.
  - Rückgabewert (boolean): Ein boolescher Wert (true / false), der angibt, ob das erste Datum nach dem zweiten liegt.
  - Beispiel:

  // Ergebnis: false
  $.xdate.isDateAfter("10.06.2023", "20.06.2023");
  
  // Ergebnis: true
  $.xdate.isDateAfter("20.06.2023", "10.06.2023");
  
  // Ergebnis: false
  $.xdate.isDateAfter("10.06.2023", "10.06.2023");
  
  // Ergebnis: false (Anzahl der vollen Tage zwischen Daten ist 0) 
  $.xdate.isDateAfter(new Date(2023, 5, 11, 8, 0), new Date(2023, 5, 10, 12, 0));

  
  

• getDateFormatted(date, [format])

  - Beschreibung: Formatiert ein Datum nach einem bestimmten Format.
  - Parameter:
  - date (unknown): Das zu formatierende Datum.
  - format (string, optional): Das Format des zurückgegebenen Datums. Wenn nicht angegeben, wird das globale Standardformat verwendet, siehe $.xdate.getFormat.
  - Rückgabewert (string): Das formatierte Datum als String. Falls der angegebene Datumswert nicht zu einem Datum aufgelöst werden konnte, wird der leere String zurückgegeben.
  - Beispiel:

  // Ergebnis: "24.12.2023"
  $.xdate.getDateFormatted(new Date(2023, 11, 24), "dd.mm.yy");

• getTodayFormatted([format])

  - Beschreibung: Ermittelt aktuelle Datum des Vorgangs und formatiert das Datum im angegebenen Format. Es wird das Datum des Servers verwendet.
  - Parameter:
  - format (string, optional): Das Format des zurückgegebenen Datums. Wenn nicht angegeben, wird das globale Standardformat verwendet, siehe $.xdate.getFormat.
  - Rückgabewert (string): Das formatierte heutige Datum als String.
  - Beispiel:

  // Ergebnis: "02.09.2025"
  $.xdate.getTodayFormatted("dd.mm.yy");

• getCreationDateFormatted([format])

  - Beschreibung: Ermittelt das Erstellungsdatum des Vorgangs und formatiert das Datum im angegebenen Format.
  - Parameter:
  - format (string, optional): Das Format des zurückgegebenen Datums. Wenn nicht angegeben, wird das globale Standardformat verwendet, siehe $.xdate.getFormat.
  - Rückgabewert (string): Das formatierte Erstellungsdatum als String.
  - Beispiel:

  // Ergebnis: "02.09.2025"
  $.xdate.getCreationDateFormatted("dd.mm.yy");

  
  

• getModificationDateFormatted([format])

  - Beschreibung: Ermittelt das Datum der letzten Änderung des Vorgangs und formatiert das Datum im angegebenen Format.
  - Parameter:
  - format (string, optional): Das Format des zurückgegebenen Datums. Wenn nicht angegeben, wird das globale Standardformat verwendet, siehe $.xdate.getFormat.
  - Rückgabewert (string): Das formatierte Datum der letzten Änderung als String.
  - Beispiel:

  // Ergebnis: "02.09.2025"
  $.xdate.getModificationDateFormatted("dd.mm.yy");

• getDate(date, [format])

  - Beschreibung: Löst ein Objekt in ein Date-Objekt auf. Es werden dabei folgende Werte erkannt: (a) Date-Objekt, (b) formatierter String, der dem angegebenen Datumsformat entspricht, (c) Datumsformel wie [%tf1%] + 3d, (d) HTMLElement eines Formularfelds, dessen Wert ausgelesen und ggf. mit dem angegebenen Datumsformat als Datum interpretiert wird, (e) eine JQuery-Instanz eines solchen HTMLElement.
  - Parameter:
  - date (unknown): Aufzulösendes Objekt.
  - format (string, optional): Das Format, welches bei Bedarf zum Interpretieren von als Text formatierten Daten verwendet wird. Wenn nicht angegeben, wird das globale Standardformat verwendet, siehe $.xdate.getFormat.
  - Rückgabewert (Date | undefined): Das aufgelöste Datum als Date-Objekt oder undefined, wenn das Datum nicht aufgelöst werden konnte.
  - Beispiel:

  // Ergebnis: Sun Mar 31 2024 00:00:00 GMT+0100 (Central European Standard Time)
  $.xdate.getDate("31.03.2024")
  
  // Ergebnis: Sun Mar 31 2024 00:00:00 GMT+0100 (Central European Standard Time)
  $.xdate.getDate("03/31/2024", "mm/dd/yy")
  
  // (wenn im Feld tf1 das Datum 18.09.2025 steht)
  // Ergebnis: Sun Sep 21 2025 00:00:00 GMT+0200 (Central European Summer Time)
  $.xdate.getDate("[%tf1%] + 3d")
  
  // Ergebnis: undefined (falsches Format)
  $.xdate.getDate("03/31/2024", "mm-dd-yy")
  
  // (wenn im Feld tf1 kein Datum steht)
  // Ergebnis: undefined
  $.xdate.getDate("[%tf1%] + 3d")

• getToday()

  - Beschreibung: Ruft das heutige Datum ab. Es wird das Datum des Servers verwendet.
  - Rückgabewert (Date): Das heutige Datum als Date-Objekt.
  - Beispiel:

  // Ergebnis: Tue Sep 02 2025 00:00:00 GMT+0200 (Central European Summer Time)
  $.xdate.getToday();

• getCreationDate()

  - Beschreibung: Ruft das Erstellungsdatum des Vorgangs ab.
  - Rückgabewert (Date): Das heutige Datum als Date-Objekt.
  - Beispiel:

  // Ergebnis: Tue Sep 02 2025 00:00:00 GMT+0200 (Central European Summer Time)
  $.xdate.getCreationDate();

• getModificationdate()

  - Beschreibung: Ruft das Datum der letzten Änderung des Vorgangs ab.
  - Rückgabewert (Date): Das heutige Datum als Date-Objekt.
  - Beispiel:

  // Ergebnis: Tue Sep 02 2025 00:00:00 GMT+0200 (Central European Summer Time)
  $.xdate.getModificationDate();

• getEasterSunday(year, [offsetDays])

  - Beschreibung: Ermittelt das Datum des Ostersonntags in einem bestimmten Jahr und addiert das Offset hinzu, falls angegeben.
  - Parameter:
  - year (number): Jahr, von dem der Ostersonntag ermittelt werden soll.
  - offsetDays (number, optional): Anzahl an Tagen, die zu dem Datum addiert werden soll. Standardwert ist 0.
  - Rückgabewert (Date): Das berechnete Datum als Date-Objekt.
  - Beispiel:

  // Ergebnis: Sun May 12 2024 00:00:00 GMT+0200 (Central European Summer Time)
  $.xdate.getEasterSunday(2024, 42);

• getRepentanceDay(year)

  - Beschreibung: Ermittelt das Datum des Buß- und Bettag in einem bestimmten Jahr.
  - Parameter:
  - year (number): Jahr, von dem der Buß- und Bettag ermittelt werden soll.
  - Rückgabewert (Date): Das berechnete Datum als Date-Objekt.
  - Beispiel:

  // Ergebnis: Wed Nov 20 2024 00:00:00 GMT+0100 (Central European Standard Time)
  $.xdate.getRepentanceDay(2024, 42);

• getGermanHolidays(year, state)

  - Beschreibung: Ermittelt alle offiziellen Feiertage eines bestimmten Jahrs im angegebenen Bundesland der Bundesrepublik Deutschland.
  - Parameter:
  - year (number): Jahr, von dem die Feiertage ermittelt werden sollen.
  - state (string): Gliedstaat-Teil des ISO-3166-2-Codes des Bundeslands, z.B. "sn" für Sachsen (case-insensitive).
  - Rückgabewert (Date[]): Array mit allen berechneten Daten als Date-Objekte.
  - Beispiel:

  // Ergebnis: (11) [Mon Jan 01 2024 00:00:00 GMT+0100, ..., Wed Nov 20 2024 00:00:00]
  $.xdate.getGermanHolidays(2024, "sn");

• isGermanHoliday(year, state, date)

  - Beschreibung: Prüft, ob ein Datum ein offizieller Feiertag im angegebenen Jahr im angegebenen Bundesland der Bundesrepublik Deutschland ist. Achtung: Diese Funktion liefert immer false zurück, wenn das angegebene Jahr nicht mit dem Jahr des angegebenen Datums übereinstimmt.
  - Parameter:
  - year (number): Jahr, in dem die Feiertage geprüft werden sollen.
  - state (string): Gliedstaat-Teil des ISO-3166-2-Codes des Bundeslands, z.B. "sn" für Sachsen (case-insensitive).
  - date (unknown): Zu prüfendes Datum.
  - Rückgabewert (boolean): Ein boolescher Wert (true / false), der angibt, ob das Datum im angegebenen Jahr liegt und ein offizieller Feiertag im angegebenen Bundesland ist.
  - Beispiel:

  // Ergebnis: true (Buß- und Bettag ist Feiertag in Sachsen)
  $.xdate.isGermanHoliday(2024, "sn", new Date(2024, 10, 20))
  
  // Ergebnis: false (Buß- und Bettag ist kein Feiertag in Bayern)
  $.xdate.isGermanHoliday(2024, "by", new Date(2024, 10, 20))

• getBusinessDaysBetween(startDate, endDate, state, [considerHalfHolidays], [additionalHolidays])
  - Beschreibung: Berechnet die Anzahl der Werktage zwischen zwei Daten unter Berücksichtigung von Feiertagen, Wochenenden und halben Feiertagen.
  - Parameter:
  - startDate (unknown): Das Startdatum.
  - endDate (unknown): Das Enddatum.
  - state(string): Gliedstaat-Teil des ISO-3166-2-Codes des Bundeslands, z.B. "sn" für Sachsen (case-insensitive).
  - considerHalfHolidays (boolean, optional): Gibt an, ob halbe Feiertage (als nummerischer Wert 0,5 statt 1,0) in der Berechnung berücksichtigt werden sollen. Standardwert ist false.
  - additionalHolidays (Date[], optional): Eine optionale Liste zusätzlicher Feiertage als Date-Objekte, die berücksichtigt werden sollen. Standardwert ist eine leere Liste.
  - Rückgabewert: Die Anzahl der Werktage zwischen den angegebenen Daten.
  - Beispiel:

  // Ergebnis: 10
  $.xdate.getBusinessDaysBetween("01.06.2024", "15.06.2024", "bw");
  
  // Ergebnis: 5
  // 5 Werktage zwischen 13.05. und 17.05.2024, keine zusätzlichen Feiertage
  $.xdate.getBusinessDaysBetween("13.05.2024", "17.05.2024", "by", false, []);
  
  // Ergebnis: 4
  // 4 Werktage zwischen 13.05. und 17.05.2024, 15.05. soll zusätzlicher Feiertag sein
  $.xdate.getBusinessDaysBetween("13.05.2024", "17.05.2024", "by", false, [new Date(2024, 4, 15)]);
  
  // Ergebnis: 3
  // 2 volle Werktage zwischen 23.12. und 28.12.2024, 24.12.wird als Arbeitstag gezählt
  $.xdate.getBusinessDaysBetween("23.12.2024", "28.12.2024", "nw", false);
  
  // Ergebnis: 2.5
  // 2 volle Werktage zwischen 23.12. und 28.12.2024, 24.12.wird als halber Feiertag gezählt
  $.xdate.getBusinessDaysBetween("23.12.2024", "28.12.2024", "nw", true);

• dateRule(rule, [compareTo], [msg])

  - Beschreibung: Fügt eine Validierungsregel für Datumsangaben hinzu, basierend auf einem Vergleichsoperator und einem Vergleichsdatum. Es werden wiederholte Felder unterstützt.:Falls im Vergleichsdatum auf ein anderes Feld verwiesen wird, muss dieses andere Feld sich entweder in der gleichen Elementwiederholung befinden oder nicht wiederholt sein.
  - Parameter:
  -- rule (string): Der Vergleichsoperator für die Validierung. Mögliche Werte sind "<", ">", "<=", ">=". Zudem gibt es die Aliase "before" (<), "beforeequal" (<=), "after" (>) und "afterequal" (>=).
  -- compareTo (unknown, optional): Das Vergleichsdatum.
  -- msg (string, optional): Eine benutzerdefinierte Fehlermeldung, die am Formularfeld angezeigt wird, wenn das Datum ungültig ist.
  - Beispiel:

  // Zukunft (nach dem heutigen Datum)
  $.xdate.dateRule("tfFuture", ">", "[%$DATE%]");
  
  // Zukunft (nach dem Datum der letzten Änderung des Vorgangs)
  $.xdate.dateRule("tfFuture", ">", "[%$FORM_DATE_MODIFIED%]");
  
  // Vor einem bestimmten Datum
  $.xdate.dateRule("tfPast", "<=", "11.03.2022");
  
  // Zwischen 2 Daten
  $.xdate.dateRule("tfBetween", ">", "10.03.2022");
  $.xdate.dateRule("tfBetween", "<", "26.03.2022");
  
  // Vor einem anderen eingegebenen Datum
  $.xdate.dateRule("tf2", "<", "[%tf1%]");
  
  // Zwischen zwei Datumsfeldern
  $.xdate.dateRule("tf3", ">", "[%tf1%]");
  $.xdate.dateRule("tf3", "<", "[%tf2%]");
  
  // Mindestalter überprüfen
  $.xdate.dateRule("tf4", "<", "[%$FORM_DATE_CREATED%] - 18y", "Sie müssen mindestens 18 Jahre alt sein, also vor dem '%' geboren sein!");