Overview

Clicking on a date field opens a calendar popup where users can easily select and input a date. This helps standardize date formats and prevents common mistakes.

DynaForms in ProcessMaker version 3 use the library Bootstrap 3 Datepicker to construct its datetime control. This library bases its format using the library Moment.js, a powerful JavaScript library that manages dates and formats. Take a look at the properties of this control to learn more about how to manage it.

After adding a datetime control to the DynaForm design, it looks as follows:

When running a case with this control, the date picker popup will be available:

Known Issue: Take into consideration that when there is not enough space for the calendar to display, the control will be displayed cut off.

Managing a Datetime Control

After adding a datetime to the DynaForm design, it is possible to customize its functionality and behavior, using the properties panel.

The properties set by default are the following:

  • type Set by default as "datetime". This definition can not be modified.
  • id Set by default as datetime000000000X where "X" represents the corresponding numbering of the control in the design. This numbering starts in 1. After a variable is related to this control, the ID changes to the name of the variable, nevertheless it is possible to set a new ID to work with the control using JavaScript, for example.

  • label Set by default as "datetime_X" where "X" represents the corresponding numbering of the control in the design. This numbering starts in 1.
  • display mode Set by default as "parent". See this documentation for more information of the modes available for this control.
  • format Set by default to "YYYY-MM-DD" which represents the date format "Year-Month-Day". Read the explanation of this property below to learn how to work with it.
  • initial selection date Set by default to "true" to set the current date in the date picker (when it is opened) and in the field (also when the date picker is opened).
  • datepicker view mode Set by default to "days" to show the days of the month when the date picker is opened.
  • show clear button Set by default to "hide" to not show the garbage icon in the date picker when working with the field in the form. For more information, read the explanation of this property.

DateTime Control Properties

The properties related to this web control are the following:

Property Description
Type datetime (readonly)
Variable

Click on the ... option to select the variable from the list of available variables. Check this section to learn more of how to relate a variable to a control.
Only variables of the following data types can be selected:

  • datetime

Variable Data type After a variable has been related to the control, this property shows the data type of the variable (readonly).
ID

[Required]

Field and HTML unique identifier.

Label Set the label of the control in this property
Placeholder Set the text that will be shown as help to fill the field inside the fields.
Hint Used to show help when the textbox is rendered. It is shown when the pointer of the mouse is hovered over the ? icon.
Required By checking this option, an asterisk is added in the label to indicate that the field is required. It means that an option must be selected mandatorily from the control. When a required field is not filled in with any value, it will not possible to go to the next step.
Display Mode

[Required]

Display mode:

  • parent: inherits the display mode defined in the parent container (form/grid)
  • edit: the field is enabled for edition when it is rendered.
  • view: the field can only be viewed when it is rendered. The content can’t be edited.
  • disabled: the field is displayed as disabled. The field is displayed in gray in order to indicate the disabled mode. The content can't be edited either.
Format

[Required]
Define the display format of the date. By hovering the pointer of the mouse on the ? icon the list of possible options is shown as a hint to fill this property .

Min Date Define in this property the minimum valid date which will be available in the date picker when rendering the form. The property can be set in design (using the date picker) or use a variable to define the value @@MinDate.
Max Date Define in this property the maximum valid date which will be available in the date picker when rendering the form. The property can be set in design (using the date picker) or use a variable to define the value @@MaxDate.
Initial Selection Date When this property is set as "true", it set the date picker with the current date and time.
Default Date Define the default date in the field.

To learn more how default dates work, read this documentation

Datepicker View Mode Default: 'days' Accepts: 'years','months','days' The default view to display when the picker is shown.

Note: To limit the picker to selecting, for instance the year and month, use format: MM/YYYY

Show Clear Button Default: false Show the "Clear" button in the icon toolbar. Clicking the "Clear" button will set the calendar to null.

Format

This property allows formatting the date and time selected as input. As the designer uses bootstrap, this is a more robust option. Take into account the following name and conventions to set the format.

TokenExample
MonthM1 2 ... 11 12
Mo1st 2nd ... 11th 12th
MM01 02 ... 11 12
MMMJan Feb ... Nov Dec
MMMMJanuary February ... November December
QuarterQ1 2 3 4
Day of MonthD1 2 ... 30 31
Do1st 2nd ... 30th 31st
DD01 02 ... 30 31
Day of YearDDD1 2 ... 364 365
DDDo1st 2nd ... 364th 365th
DDDD001 002 ... 364 365
Day of Weekd0 1 ... 5 6
do0th 1st ... 5th 6th
ddSu Mo ... Fr Sa
dddSun Mon ... Fri Sat
ddddSunday Monday ... Friday Saturday
Day of Week (Locale)e0 1 ... 5 6
Day of Week (ISO)E1 2 ... 6 7
Week of Yearw1 2 ... 52 53
wo1st 2nd ... 52nd 53rd
ww01 02 ... 52 53
Week of Year (ISO)W1 2 ... 52 53
Wo1st 2nd ... 52nd 53rd
WW01 02 ... 52 53
YearYY70 71 ... 29 30
YYYY1970 1971 ... 2029 2030
Week Yeargg70 71 ... 29 30
gggg1970 1971 ... 2029 2030
Week Year (ISO)GG70 71 ... 29 30
GGGG1970 1971 ... 2029 2030
AM/PMAAM PM
aam pm
HourH0 1 ... 22 23
HH00 01 ... 22 23
h1 2 ... 11 12
hh01 02 ... 11 12
Minutem0 1 ... 58 59
mm00 01 ... 58 59
Seconds0 1 ... 58 59
ss00 01 ... 58 59
Fractional SecondS0 1 ... 8 9
SS0 1 ... 98 99
SSS0 1 ... 998 999
Unix TimestampX1360013296
Unix Millisecond Timestampx1360013296123

Note: Name and format taken from [1]

For example, if the following format is set in this property:

dddd, MMMM Do YYYY, h:mm:ss a

When picking a date from the date picker, the following will be the input for the field.

Note: If the user needs to edit the hours and minutes in a datetime control, make sure to include hours and minutes in the format. For example, a format of YYYY-MM-DD hh:mm A will allow the user to directly edit the time in datetime field.
In addition, a icon will be added at the bottom of the date picker dialog if the format includes hours, minutes, seconds or AM/PM. Clicking on it will change the dialog to select the time units in the format:

Min Date

This property prevents users from making date/time selections before the date set in this property. By default, this property is not set, so no restriction is made to dates. Select the minimum date from the calendar shown by clicking on the calendar icon at the right side of the box of the property.

For example, when setting the minimum date to 03/12/2015:

As shown in the image, the dates before "03/12/2015" are not enabled and it is not possible to jump to February. If attempting to so that, the mouse cursor shows a prohibited sign.

Max Date

This property prevents users from making date/time selections after the date set in this property.By default, this property is not set, so no restriction is made to dates. Select the maximum date from the calendar shown by clicking on the calendar icon at the right side of the box of the property.

For example, when setting the maximum date to 03/17/2015:

As shown in the image, the dates after "03/17/2015" are not enabled and it is not possible to the next months. If attempting to so that, the mouse cursor shows a prohibited sign.

Initial Selection Date

This property defines the initial date/time that will be added in the value of the control when the DynaForm is rendered and the datepicker is opened the first time. When this property is set as "true", it sets the date picker with the current date and time.

The other options of this property are the following:

  • Year: It shows the datepicker and fills the box with the first day of the first month of the current year.
  • Month: It shows the datepicker and fills the box with the first day of the current month.
  • Day: It shows the datepicker and fills the box with the current day.
  • Hour: It shows the datepicker and fills the box with the current hour (it is necessary to configure the format to show also hours ).
  • Minute: It shows the datepicker and fills the box with the hour and minute (it is necessary to configure the format to show also hours and minutes).

Default Date

This property sets the default date and time when using the date picker.

This property is not set by default. To set a default date, enter it manually (taking care of the format) or, to not make mistakes, click on the calendar at the right side of the box of this property and select the default date from the datetime picker

Datepicker View Mode

This property sets the default view to display when the picker is shown. The possible values of this control are described below.

  • "Days" Shows the date picker by days.

  • "Months" Shows the date picker by months.

  • "Years" Shows the date picker by years.

This property is set by default with "Days".

Show Clear Button

This property shows the "Clear" button in the icon toolbar (represented by a garbage icon). When this button is clicked it will set the calendar to null.

Datetime Control Example

For this example add a "Datetime" control by simply dragging and dropping it into the Dynaform canvas from the Web Control located on the left panel.

After adding the control notice that immediately a new window will pop up. This window is the Create Variable window where a variable for the control can be created. For this example create a variable named "date1". Then click on the "Save" button to store the variable to the control

After the variable has been created and added click on any empty space of the control to display its properties on the left hand panel. Notice that the "variable", "variable data type" and "id" properties have the values of the variable.

For the control to have a proper name instead of "datetime_1", changed the label (for this example) to "Current Date" as seen in the image below.

Next is the "placeholder" property which adds text into the control that is used as help to fill the field. For example add the following text: "Add the current date" and the image below shows that the control will show this text until a value is added.

The "hint" property is used to show help by adding an icon on the right side corner of the control. An example text for showing help can be the following: "Select the current date". As seen in the image below when running a case there will be an icon next to the control, hover the pointer of the mouse to display the hint added.

The next property is the "required" property which adds an asterisk in the label to indicate that the field is required therefore when running a case and if/when an option isn't selected then an error message will be displayed (This field is required).

The "display mode" property has different options and each of those options can make the following alterations to the control:

The following field is the "format" property which will define the display format of the date. By default it is set to show the year, then the month and finally the day but there are several options that can be added. Hover your mouse over the questions mark icon to learn more about it or read more about this in the following page. For this example try adding the following text to the "format" property: "dddd, MMMM Do YYYY, hh:mm:ssa"; this will show the day of the week, the current month, the date and the time. Observe the results in the image below.

Next, the "min date" property defines the minimum valid date. This can be set by clicking on the calendar of the control and choosing which will be the minimum valid date shown when running a case. For example if the first day of November is chosen then when running a case the control won't show a date before November 1st. and if the user tries to pick a date before November it is not going to be possible. As seen in the image below the arrow to go back a month will appear as disabled.

The "max date" property is similar to the "min date" property but it defines maximum valid date that can be chosen. For example, choose the last day of November as maximum valid date and when running the control won't show a date after November and the arrow to go forward a month will appear as disabled.

Moving on, the "initial selection date" property defines the initial selection date that display the datepicker. By default is set on true which does not make any bigger changes to the control. Learn more about how to use this property by clicking on the question mark icon.

The first change that can be done in the "initial selection date" property is choosing the "year" option which will show the first day of the current year as observed in the image below.

The second change in the "initial selection date" property can be choosing the "month" option which will show the first day of the current month.

The third change in the "initial selection date" property can be choosing the "day" option which shows the current day as seen in the image below.

Note: For the moment the options "hour" and "minute" do not have the proper functionality but they will be fixed for next versions.

After this comes the "default value" property which defines the default date in the field. Click on the small calendar icon in the property to choose a default date and this date chosen will be shown automatically when running a case as observed in the image below.

The "datepicker view mode" property will select the default view to display when the picker is shown and can select days, months or years. For this example, try one by one. The default is set to days and it is shown as the image below.

Choose the "datepicker view mode" to "months" and observe the results in the image below.

Then, change it to "years" and observe the alterations made in the control.

Now the "show clear button" property is the final one in the Datetime list of properties. This property provides two options which are:

  • Show: Shows the "Clear" button when choosing a date which looks like an small garbage can. Clicking the "Clear" button will set the calendar to null.
  • Hide: It won't show the "Clear" button in the control.

JavaScript in Datetimes

To learn how to manipulate DynaForm controls using JavaScript, see JavaScript in DynaForms.

Datetime controls in ProcessMaker 3 have the following field components:

  • Label: The text displayed above or to the left of the field to identify it to the user.
  • Text: The datetime displayed to the user, as configured by the format property.
  • Value: The stored value for the field in standard "YYYY-MM-DD" format for dates and "YYYY-MM-DD hh:mm:ss" format for datetimes. Examples: "2010-01-01", "1999-07-25 04:01:01", "2015-12-31 23:59:59"

JavaScript Methods

Some of the JavaScript methods to manipulate datetime controls include:

Method Description
jQuery("#fieldID").getControl()

Use this function to obtain the control's input field, rather its DIV which is obtained with $("#id")

jQuery("#fieldID").disableValidation() Disable the validation of the field, so it doesn't check whether the field is required when the form is submitted.
jQuery("#fieldID").enableValidation() Enable validation of the field, so it will check whether the field is required when the form is submitted.
jQuery("#fieldID").getValue() Returns the stored datetime of the field in "YYYY-MM-DD hh:mm:ss" format.
jQuery("#fieldID").getText() Returns the displayed text of the datetime in the configured format.
jQuery("#fieldID").getLabel() Returns the field's label, which is the text displayed above or to the left of the field to identify it.
jQuery("#fieldID").setValue("newValue") Sets a new value in the field. Make sure to "YYYY-MM-DD" format for dates and "YYYY-MM-DD hh:mm:ss" format for datetimes.
jQuery("#fieldID").setText("newText") Sets a new text in the field, which is the displayed datetime. The datetime should be in the same format as configured by the format property.
jQuery("#fieldID").setLabel("newLabel") Change the field's label, which is the text displayed above or to the left of the field to identify it.
jQuery("#fieldID").setOnchange(
function(newVal, oldVal){...})
Define a change event handler, which is a custom function that executes after the value of the field changes. The function may contain the following parameters:

  • newVal: The new value that has just been set in the field.
  • oldVal: The old value which was changed.

To see code examples for these methods, see JavaScript Functions and Methods.

Note: The setValue() method cannot be used to clear the value of a datetime control. See this workaround for clearing datetime controls with JavaScript.

Dynamic dates using variables

The default date, min date, and max date properties used by a datetime control can be set dynamically by using case variables. The properties of the datetime control will be set according to the variables (as long as these variables are set in a prior trigger or in fields in a prior DynaForm). The variables should use the format "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS", such as "1999-01-01" or "2016-12-31 23:59:59".

Example setting to the current datetime:

A datetime control whose variable is named "currentDate" needs to be set to the current datetime. First, create a trigger which is set to fire before the DynaForm, which uses the getCurrentDate() and getCurrentTime() functions to set the current datetime in YYYY-MM-DD HH:MM:SS format:

@@currentDate = getCurrentDate() . ' ' . getCurrentTime();

When the DynaForm is loaded, the datetime control associated with the @@currentDate variable will automatically have the current datetime. If the user shouldn't be able to change the value of the datetime field, then set its mode property to disabled.

Example setting 3 relative Dates:

In this example, the @@minDate, @@maxDate and @@defaultDate variables are inserted in the min date, max date, and default date properties, respectively.

The following trigger which executes before the DynaForm sets the three variables. If the user set the @@dueDate variable in a prior DynaForm, the trigger sets min date to the first day of the month of the @@dueDate, the max date to the last day of the month @dueDate and the default date to the middle of the month of the dueDate. If no value was selected for the @@dueDate, then the trigger sets the three variables to the first day, last day and middle day of the next month, respectively:

if (!isset(@@dueDate) or empty(@@dueDate)) {
   @@minDate = date('Y-m-01', strtotime('+1 month'));
   @@maxDate = date('Y-m-t', strtotime('+1 month'));
   @@defaultDate = date('Y-m-15', strtotime('+1 month'));
}
elseif {
   @@minDate = date('Y-m-01', strtotime(@@dueDate));
   @@maxDate = date('Y-m-t', strtotime(@@dueDate));
   @@defaultDate = date('Y-m-15', strtotime(@@dueDate));
}

Managing and Comparing Dates

To manipulate dates in Javascript, the data needs to be converted into Date objects. To facilitate this, ProcessMaker has integrated the moment.js JavaScript library.

moment.js simplifies date and time related manipulation, plus it is supported by ProcessMaker Desktop, ProcessMaker Mobile for iOS and ProcessMaker Mobile for Android. Please, read the official Moment.js Documentation to discover more functions of this library.

Example - Time from current date:

The code below retrieves how much time exists between an specific date entered by the user and the current date.

function checkTime(){
        var startDt = $('#datetimeVar').getValue();
        var rest= moment(startDt).fromNow();
        $("#textVar").setValue(rest);
};
$('#button0000000004').click(checkTime);

Example - Comparing two dates:

The following example compares two instances of DateTime and returns an alert message that indicates whether the first date is earlier than, the same as, or later than the second date.

function comparingDates(){
        var startDt = $('#datetimeVar').getValue();
        var endDt = $('#datetimeVar2').getValue();
        if(moment(startDt).isBefore(endDt)){
        alert('1rst Date is earlier than 2nd date.');
        }
        else if(moment(startDt).isAfter(endDt)) {
            alert('2nd date is earlier than 1rst date.');
        }
        else if(moment(startDt).isSame(endDt)) {       
        alert('Both dates are the same.');
        }
}
$('#button0000000001').click(comparingDates);

The following code does the same thing using Date and .getTime() to manipulate the dates and converting date strings into Date objects. Nevertheless, take into consideration that the example below does not work with ProcessMaker Mobile for iOS, because Safari does not recognize the ISO format returned by the method .getValue().

Example:

function comparingDates(){
        var startDt = $('#datetimeVar').getValue();
        var endDt = $('#datetimeVar2').getValue();
        var newstartDt = startDt.replace(/ /g,'T');
        var newendDt = endDt.replace(/ /g,'T');
        if(new Date(newstartDt).getTime() < new Date(newendDt).getTime()){
        alert('1rst Date is earlier than 2nd date.');
        }
 
        else if (new Date(newstartDt).getTime() > new Date(newendDt).getTime()) {
                alert('2nd date is earlier than 1rst date.');
        }
       
        else if (new Date(newstartDt).getTime() == new Date(newendDt).getTime()) {
                alert('Both dates are the same.');
        }
}
$('#button0000000001').click(comparingDates);