TABLE OF CONTENTS

• Installation
• Functionality
  • Functions of `$.xdate`:
    • format(format: string)
    • setFormat(format: string)
    • getFormat()
    • getDaysDiff(d1: Date|string, d2: Date|string)
    • getDaysBetween(d1: Date|string, d2: Date|string)
    • getWeekdaysBetween(d1: Date|string, d2: Date|string)
    • getAge(requestedBirthDate: Date|string)
    • isDateBefore(d1: Date|string, d2: Date|string)
    • isDateAfter(d1: Date|string, d2: Date|string)
    • getDateFormat(d: Date|string, format?: string)
    • getCreationDateFormat(format?: string)
    • getDate()
    • getToday()
    • dateRule(rule: string, compareTo?: Date | string |. jQuery, msg?: string)
    • getBusinessDaysBetweenThe getBusinessDaysBetween function calculates the number of business days between two dates, taking holidays into account , weekends and half-holidays.

With the free Date Utilities plugin for FORMCYCLE it is possible to use date functions, calculations and validations to be carried out.

The plugin is currently still in the testing phase and will be released upon request. Please contact  support@formcycle.de . It focuses primarily on date calculations specific to Germany. Currently there is a limitation that some validations and calculations do not work in repetitions.

Installation

The plugin must be installed via the plugin management interface provided for this purpose. All you have to do is import the corresponding Jar file or install it from the plugin store.

Functionality

The plugin contains a JavaScript library and provides a number of helper functions available via $.xdate. 

In addition, the designer offers functions for configuring date comparisons. These functions can be used to determine whether a date is before, before, after or after a specific date.

Possible values are today (the current date), creation (creation date of the form record), the name of a form element (e.g. tf1), a date in the format DD.MM.YYYY ( e.g. 03/31/2024), or a duration such as today+2y (today plus 2 years) or creation-3y2m1d (creation date minus 3 years, 2 months, 1 day) 

After configuration, the calendar automatically adjusts to display the selected days in the date picker.

In combination with calculation fields, functions such as

$.xdate.getBusinessDaysBetween([%tfHolidayFrom%], [%tfHolidayTo%], "bw")

can be called to calculate the number of working days minus holidays and weekends. Further functions can be used as follows:

Functions of `$.xdate`:

• format(format: string)

  - Description: Sets the default date format for the calculations.
  - Parameters:
  - format (string): The desired date format.
  - Example:

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

• setFormat(format: string)

  - Description: Sets the default date format.
  - Parameters:
  - format (string): The date format to set.
  - Example:

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

• getFormat()

  - Description: Gets the current default date format.
  - Return value: The current date format as a string.
  - Example:

  const format = $.xdate.getFormat();

• getDaysDiff(d1: Date|string, d2: Date|string)

  - Description: Calculates the difference in days between two dates.
  - Parameters:
  - d1 (Date|string): The first date.
  - d2 (Date|string): The second date.
  - Return value: The difference in days as an integer.
  - Example:

  const diff = $.xdate.getDaysDiff("10.06.2023", "20.06.2023");

• getDaysBetween(d1: Date|string, d2: Date|string)

  - Description: Calculates the number of days between two dates.
  - Parameters:
  - d1 (Date|string): The first date.
  - d2 (Date|string): The second date.
  - Return value: The number of days as an integer.
  - Example:

  const days = $.xdate.getDaysBetween("10.06.2023", "20.06.2023");

• getWeekdaysBetween(d1: Date|string, d2: Date|string)

  - Description: Calculates the number of business days between two dates.
  - Parameters:
  - d1 (Date|string): The first date.
  - d2 (Date|string): The second date.
  - Return value: The number of business days as an integer.
  - Example:

  const weekdays = $.xdate.getWeekdaysBetween("10.06.2023", "20.06.2023");

• getAge(requestedBirthDate: Date|string)

  - Description: Calculates age based on a birth date.
  - Parameters:
  - requestedBirthDate (Date|string): The date of birth.
  - Return value: The age as an integer.
  - Example:

  const age = $.xdate.getAge("10.06.2023");

• isDateBefore(d1: Date|string, d2: Date|string)

  - Description: Checks whether one date is before another.
  - Parameters:
  - d1 (Date|string): The first date.
  - d2 (Date|string): The second date.
  - Return value: A Boolean value indicating whether the first date is before the second.
  - Example:

  const isBefore = $.xdate.isDateBefore("10.06.2023", "20.06.2023");

• isDateAfter(d1: Date|string, d2: Date|string)

  - Description: Checks whether one date is after another.
  - Parameters:
  - d1 (Date|string): The first date.
  - d2 (Date|string): The second date.
  - Return value: A Boolean value indicating whether the first date is after the second.
  - Example:

  const isAfter = $.xdate.isDateAfter("10.06.2023", "20.06.2023");

• getDateFormat(d: Date|string, format?: string)

  - Description: Formats a date according to a specific format.
  - Parameters:
  - d (Date|string): The date to format.
  - format (optional, string): The format of the returned date. If not specified, the default format is used.
  - Return value: The date formatted as a string.
  - Example:

  const formattedDate = $.xdate.getDateFormat(new Date(), "dd.mm.yyyy" );

• getCreationDateFormat(format?: string)

  - Description: Gets the creation date of the document in the specified format.
  - Parameters:
  - format (optional, string): The format of the returned date. If not specified, the default format is used.
  - Return value: The creation date formatted as a string.
  - Example:

  const creationDate = $.xdate.getCreationDateFormat("dd.mm.yyyy");

• getDate()

  - Description: Gets the current date.
  - Return value: The current date as a string in standard format.
  - Example:

  const currentDate = $.xdate.getDate();

• getToday()

  - Description: Gets today's date.
  - Return value: Today's date as a string in standard format.
  - Example:

  const today = $.xdate.getToday();

• dateRule(rule: string, compareTo?: Date | string |. jQuery, msg?: string)

  - Description: Adds a validation rule for dates based on a comparison operator and a comparison date.
  - Parameters:
  -- rule (string): The comparison operator for validation. Possible values are "<", ">", "<=", ">=", "BEFORE" and "AFTER".
  -- compareTo (Date | string | jQuery, optional): The comparison date. Can be a fixed date, a date string in the format "dd.mm.yyyy" or be a jQuery object pointing to an input element.
  -- msg (string, optional): The custom error message returned if the date is invalid.
  - Example:

  // Future (creation date today or XFC_METADATA.currentProcess.creationDate)
  $('[name=tfFuture]').dateRule();
  
  // Future (after today's date)
  $('[name=tfFuture1]').dateRule('AFTER', $.xdate.getToday());
  
  // Past and Today (Creation Date today or XFC_METADATA.currentProcess.creationDate)
  $('[name=tfPast]').dateRule('<=');
  
  // After a specific date
  $('[name=tfAfter1]').dateRule('AFTER', '11.03.2022');
  
  // Before a specific date
  $('[name=tfBefore1]').dateRule('BEFORE', '11.03.2022');
  $('[name=tfBefore2]').dateRule('<', '10.03.2022');
  
  // Input
  $('[name=tf1]').dateRule('<=');
  $('[name=tf2]').dateRule('BEFORE', $('[data-name="tf1"]')) ;
  
  // Between two date fields
  $('[name=tf3]').dateRule('AFTER', 'tf1');
  $('[name=tf3]').dateRule('BEFORE', '25.03.2022');
  
  // Check minimum age
  var m18 = $.xdate.getCreationDate();
  m18.setFullYear(m18.getFullYear() - 18);
  $('[data-name="tf4"]').dateRule('BEFORE', m18, "You must be at least 18 years old, i.e. before '%' be born!");

• getBusinessDaysBetween
  The getBusinessDaysBetween function calculates the number of business days between two dates, taking holidays into account , weekends and half-holidays.

  
  getBusinessDaysBetween(d1: Date | string, d2: Date | string, state: string, considerHalfHolidays: boolean = false, additionalHolidays: Date[] = [])
  - Description: Calculates the number of business days between the specified dates.
  - Parameters:
  - d1 (Date | string): The start date as a Date object or as a string in the format "dd.mm.yyyy".
  - d2 (Date | string): The end date as a Date object or as a string in the format "dd.mm.yyyy".
  - state(string): The federal state for which the holidays should be taken into account. Supported values:
  • 'bw': Baden-Württemberg
  • 'by': Bayern
  • 'he': Hesse
  • 'nw': North Rhine-Westphalia
  • 'rp': Rhineland-Palatinate
  • 'sl': Saarland
  • 'bb': Brandenburg
  • 'mv': Mecklenburg-Western Pomerania
  • 'sn': Saxony
  • 'st': Saxony-Anhalt
  • 'th': Thuringia
• considerHalfHolidays (boolean, optional): Specifies whether half holidays should be taken into account. Defaults to false.- additionalHolidays(Date[], optional): An optional list of additional holidays as Date objects to be included. By default, an empty list.- Return Value: The number of business days between the specified dates.- Example:

  const startDate = new Date('2024-06-01');
  const endDate = new Date('15.06.2023');
  const state = 'bw'; // Baden-Württemberg
  const workDays = $.xdate.getBusinessDaysBetween(startDate, endDate, state);
  console.log(workDays); // Output: 10

  Extended examples:

  // With half holidays and additional holidays
  const startDate2 = new Date('2024-05-28');
  const endDate2 = new Date('2024-06-02');
  const state2 = 'by'; // Bavaria
  const additionalHolidays2 = [new Date('2024-06-01')]; // Additional holiday: June 1st, 2024
  const workDays2 = $.xdate.getBusinessDaysBetween(startDate2, endDate2, state2, true, additionalHolidays2);
  console.log(workDays2); // Issue: 4 (3 working days between May 28th and June 2nd, 2024, with June 1st being a half holiday)
  
  // With another federal state and without taking half-holidays into account
  const startDate3 = new Date('2024-07-01');
  const endDate3 = new Date('2024-07-10');
  const state3 = 'nw'; // North Rhine-Westphalia
  const workDays3 = $.xdate.getBusinessDaysBetween(startDate3, endDate3, state3, false);
  console.log(workDays3); // Edition: 6 (10 working days between July 1st and July 10th, 2024 in North Rhine-Westphalia)