JTSageDateBox A multi-mode date and time picker

Interacting with DateBox

There are several ways to interact with DateBox programatically.

If you are simply trying to get multiple date formats, or parts of the date, this is much easier to accomplish with the linkedField option.

DateBox provides a number of callbacks that will run automatically, exports some functions publicly, regularly bubbles it's own events up the DOM tree, and accepts some .trigger()'s.

Callbacks

This is a list of definable callbacks. Generally, all callbacks can either be a function, or a string reference to a function defined in the window namespace (If you are unfamiliar with this term, it's somewhat analagous to the global object in a browser)

Note: all callbacks are run with the widget as thier context. So, inside a callback, you can use

this.getTheDate();

rather than having to do:

$(element).datebox('getTheDate');

Note that 'this' in your function is the widget. argument[0] is a return value object, this starts on argument[1]

Default: []
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Array
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

Option can be a function, or, a string reference to a function in the window object. Function is run on press of the open button ( or call to open DateBox)

Returning false from this function will prevent DateBox from opening.

Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Function
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

This option allows you to define a custom function that is called on the generated calbox grid box of each date.

It provides an object, and expects an object in the same format.

The object provided:

{
  // boolean ( true = date is invalid )
  bad: false,

  // javaScript date object for the date
  dateObj: [Object],

  // Text to display, typically just the number
  displayText: 6,

  // Object that click events run on.  Part of htmlObj
  eventObj: [Object],

  // If the date is invalid, set to the name of the rule that caused it
  failrule: false,

  // boolean ( true = date is valid )
  good: true,

  // jQuery object to be appended.
  htmlObj: [Object],

  // boolean ( false = Date is not part of the displayed month ( underrun / overrun ) )
  inBounds: false,

  // If the date is explicitly valid, set to the name of the rule that caused it
  passrule: false,

  // Theme to be applied to the htmlObj (already applied)
  theme: "outline-secondary border-0"
}

Example function:

window.printFullDate = function( myObject ) {
  console.log( myObject.dateObj );
  return myObject;
}

Then, to link it to datebox, it could be as easy as:

<input type="text" data-role="datebox" data-datebox-mode="calbox" data-datebox-calBeforeAppendFunc="printFullData">

When given a function, DateBox will run it. When given a string, it will run window.stringContents

Requirement

There must be an element with the ".dbEvent" class, this is how clicks are triggered. Additionally, that element should include the full object as it's $.data()

Note that the context of this function is the widget, same as for calFormatter.

Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: String || Function
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): calbox
Operation mode(s) this option applies to

This option allows for a function that should return the prefered text for the calendar grid date. Typically, it's just a number.

An object is passed to the function:

{
  // the theme class to be applied to the date
  theme    : [String]

  // The date is in the current month displayed.
  inBounds : [boolean]

  // True if the date is valid
  good     : [boolean],

  // True if the date is invalid
  bad      : [boolean],

  // Set to the rule that failed the date, or false
  failrule : [boolean|String],

  // Set to the rule that passed the date, or false.
  // Note: both failrule and passrule may be empty if the date passed by default (not explicitly)
  passrule : [boolean|String],

  // The current date being processed.
  dateObj  : [JavaScript Date Object]
}

The return value must be a string, but can contain HTML. For advanced formatting, consider using calBeforeAppendFunc instead.

Example function:

window.redSingles = function( obj ) {
  // Make single digit dates red
  if ( obj.dateObj.get(2) < 10 ) {
    return "<span style='color:red'>" + obj.dateObj.get(2) + "</span>";
  } else {
    return obj.dateObj.get(2);
  }
}

Then, to link it to datebox, it could be as easy as:

<input type="text" data-role="datebox" data-datebox-mode="calbox" data-datebox-calFormatter="redSingles">

When given a function, DateBox will run it. When given a string, it will run window.stringContents

Note that this function is run with a context of the widget. So you may call things like:

if ( this.isSelectedInCalGrid() ) { ... }

Rather than having to go back to the DOM element.

Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Function
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): calbox
Operation mode(s) this option applies to

Option can be a function, or, a string reference to a function in the window object.

The first argument to the function will be an object containing:

  • date : The JavaScript date object of the current (choosen) date - Always defined, even if meaningless.
  • initDate : The JavaScript date object that holds the widget creation time/date. Always defined.
  • duration : The last entered duration, in seconds for duration modes - undefined if not.
  • cancelClose : [Close only] - If the close action was triggered by a user cancel (true), or by setting the date (false)

For more information, please see the Callbacks and Listeners section of the documentation.

Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Function
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

Note that 'this' in your function is the widget. argument[0] is a return value object, this starts on argument[1]

For more information, please see the Callbacks and Listeners section of the documentation.

Default:
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Array
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

This provides an convient way to override the built in icons. It recieves a single argument, which it the value of the icon portion of the theme setting.

Example - FontAwesome
iconFactory : function ( icnName ) {
  return "<i class=\"fa fa-" + icnName + "\"></i>";
}
Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Function
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

This can be any valid format string that linkedField will be populated with. The default value is the format that .toJSON() returns.

note: this default format includes a 'Z' - it stands for "Zulu Time", a.k.a. "GMT", a.k.a. "UTC" - it is the single instance of DateBox doing any time zone processing, it does translate the date and time to GMT. PHP only mostly understands ISO-8601, other languages do better. Backend node.js would be very happy with this format. That said, if you have not otherwise handled time zones in your application, please, please, please do not use the default setting. Note also this is relying on the useragent to have a correctly implemented toJSON - which should be there, but…

Default: %J
The default value of the option. Many options use "false" to disable them.
Data Type Expected: String
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

This is a jQuery selector of the field(s) that you want to fill with the selected date when chosen. Uses linkedFieldFormat as the format. Often used with a hidden form element to simplify backend date processing.

Alternativle, it can be passed an object of multiple fields, in the form of:

[ { id: "#someInput", format: "someFormat" }, … ]

Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: String | Object
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

Option can be a function, or, a string reference to a function in the window object.

Additionally, if this returns false, the DateBox control will immediatally close.

The first argument to the function will be an object containing:

  • date : The JavaScript date object of the current (choosen) date - Always defined, even if meaningless.
  • initDate : The JavaScript date object that holds the widget creation time/date. Always defined.
  • duration : The last entered duration, in seconds for duration modes - undefined if not.
  • cancelClose : [Close only] - If the close action was triggered by a user cancel (true), or by setting the date (false)

For more information, please see the Callbacks and Listeners section of the documentation.

Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Function
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

Note that 'this' in your function is the widget.

argument[0] is a return value object, this starts on argument[1]

For more information, please see the Callbacks and Listeners section of the documentation.

Default: []
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Array
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

This option can only be supplied as a function. It will recieve an object containing:

  • oldDate - the Date that existed prior to the control closing. The internal date
  • origDate - last confirmed, good, user set date. Does not reflect changes in the control prior to a set button being clicked.
  • newDate - should the input be re-read, this is the date the control thinks it is.
  • isGood - the input was be succesfully processed
  • isBad - the input was NOT be succesfully processed
  • input - Value of the input

The function return either:

  • A new date OBJECT to set the control today.

OR

  • false ( in fact, anything other than an object), meaning that the date is fine - and DateBox should use the value of newDate instead.

Sample:

function( obj ) {
  if ( obj.isGood ) {
    // Good date parsed, do nothing.
    return false;
  }

  var newd = chrono.parseDate(obj.input);

  if ( newd === null ) {
    return new Date();
  } else {
    return newd;
  }
}

For more information, please see the Callbacks and Listeners section of the documentation.

Default: false
The default value of the option. Many options use "false" to disable them.
Data Type Expected: Function
The datatype the option is expecting
Option is Dynamic: yes
The option can be toggled or reset after the control has loaded
Valid Mode(s): datebox, timebox, datetimeflipbox, flipbox, timeflipbox, datetimeflipbox, slidebox, calbox
Operation mode(s) this option applies to

Public Functions

These are callable functions that leveage aspects of DateBox, or allow you to change aspects of DateBox

$(input).datebox( { <option_name> : <new value> } );
$(input).datebox( <object> );

You can either send a key: value pair to set a single option, or an object of multiple options. This will not do deep object extension.

Return Type: undefined
Datatype of value returned from function
$(input).datebox( "applyMinMax" );

This refers to the actual min and max attributes, with are translated to minDate and maxDate. (ISO date strings)

DateBox does not "watch" the min/max HTML attributes, other than on widget initialization. If you programmatically change them via JavaScript, you will need to run this function to make sure the DateBox "sees" them.

Return Type: undefined
Datatype of value returned from function

This function can be used to close the control.

$(input).datebox( "close" );
Return Type: undefined
Datatype of value returned from function

Return if the selected calbox date is visible. Only valid for calbox, otherwise it will value is ambiguous.

Actually just an alias of isSelectedInCalGrid();

$(input).datebox( "dateVisible" );
Return Type: undefined
Datatype of value returned from function

This function will destroy the DateBox control and remove the enhancements it added.

$(input).datebox( "destroy" );
Return Type: undefined
Datatype of value returned from function

This function will disable the DateBox control.

$(input).datebox( "close" );
Return Type: undefined
Datatype of value returned from function

This function will enable the datebox control.

$(input).datebox( "enable" );
Return Type: undefined
Datatype of value returned from function

Return the beginning date of the currently visible calbox grid.

If the calendar has not yet been open, or not in calbox, it'll return false.

$(input).datebox( "getCalStartDate" );
Return Type: undefined
Datatype of value returned from function

Return the ending date of the currently visible calbox grid.

If the calendar has not yet been open, or not in calbox, it'll return false.

$(input).datebox( "getCalEndDate" );
Return Type: undefined
Datatype of value returned from function

Get the last set duration in a durationbox or durationflipbox as an integer.

$(input).datebox( "getLastDur" );
Return Type: undefined
Datatype of value returned from function

This will return a specified options current value.

$(input).datebox( "getOption", <Option_Name> );

Option Name can be any datebox option.

Return Type: undefined
Datatype of value returned from function

Return the currently selected date object for any date mode.

getTheDate is a better option usually, except for CalBox mode.

$(input).datebox( "getSelectedDate" );
Return Type: undefined
Datatype of value returned from function

Return the current date object for any date mode.

$(input).datebox( "getTheDate" );
Return Type: undefined
Datatype of value returned from function

Boolean if the specified date (object) appears in the visible calendar grid.

If the calendar has not yet been open, or not in calbox, it'll return false.

if ( $( "#datebox" ).datebox( "isInCalGrid", new Date() ) ) {
  ...
}
Return Type: undefined
Datatype of value returned from function

Boolean if the selected date appears in the visible calendar grid.

If the calendar has not yet been open, or not in calbox, it'll return false.

If you are using calOnlyMonth, use isSelectedInBounds instead.

if ( $( "#datebox" ).datebox( "isSelectedInCalGrid" ) ) {
  ...
}
Return Type: undefined
Datatype of value returned from function

Boolean if the selected date appears in the visible calendar month (not in previous / next month underrun / overrun dates).

If the calendar has not yet been open, or not in calbox, it'll return false.

if ( $( "#datebox" ).datebox( "isSelectedInBounds" ) ) {
  ...
}
Return Type: undefined
Datatype of value returned from function

This function can be used to close the control.

$(input).datebox( "open" );
Return Type: undefined
Datatype of value returned from function
$(input).datebox( "parseDate", <String format>, <String Date> );

This will use the DateBox formatter library to parse a string Date and return a JavaScript Date Object.

Return Type: undefined
Datatype of value returned from function

This function can be used to refresh (rebuild) the control.

$(input).datebox( "refresh" );

This will set the date, with two options of passed argument:

  • Date Object : JavaScript Date() object (PREFERRED!)
  • Formatted String : String, formatted in the same format that DateBox is currently outputting.
$(input).datebox( "setTheDate", <Date Object> );
$(input).datebox( "setTheDate", <Formatted String> );
Return Type: undefined
Datatype of value returned from function

Listeners

These are events that happen in the DOM because of something that DateBox has done. i.e., These are the cause, you choose the effect.

This trigger is bubbled when the DateBox control is cleared.

$(input).bind( "datebox", function ( e, passed ) { 
  if ( passed.method === "clear" ) {
    alert( "Datebox was cleared!" );
  }
});

The object will contain a "method" key set to "clear".

This trigger is bubbled when DateBox enhancment completes.

$(document).on( "dateboxaftercreate", function() {
  alert( "A DateBox has been made" );
});

This trigger is bubbled on every page if DateBox is loaded. Pretty much useless. Could be used to check that the script has loaded. Testing for jQuery.jtsage.datebox would be easier.

$(document).on( "dateboxbeforecreate", function() {
  alert( "DateBox is loaded?" );
});

This trigger is bubbled a DateBox is enhanced - but thrown prior to initialization.
Useful only to check if there is a DateBox on the page.

$(document).on( "dateboxcreate", function() {
  alert( "A DateBox is being made" );
});

This trigger is bubbled when the DateBox control is disabled

$(input).bind( "datebox", function ( e, passed ) { 
  if ( passed.method === "disable" ) {
    alert( "Datebox was disabled!" );
  }
});

The object will contain a "method" key set to "clear".

This only fires for calbox mode, and means an view change has occured (the offset listener may still fire), but the user selected date has not changed. The view has changed

In the payload is -

{
  // Method happening, in this case "displayChange"
  method             : "displayChange",

  // The date that the user has selected, or the default, or today
  selectedDate       : [JavaScript Date Object],

  // The date that is shown (place where the calculations begin)

  shownDate          : [JavaScript Date Object],

  // Which part of the date to change: y,m,d,h,i,s,a OR 'p' (a picker was used)
  thisChange         : [char : y|m|d|i|s|a|p], 

  // How much to change OR null (for pickers)
  thisChangeAmount   : [integer]

  // What is the date (object) where the grid starts? (ignores calOnlyMonth)
  gridStart          : [JavaScript Date Object],

  // What is the date (object) where the grid ends? (ignore calOnlyMonth)
  gridEnd            : [JavaScript Date Object],

  // Is the selected date in the grid / view (might be part of previous/next month)
  selectedInGrid     : [boolean],

  // Is the selected date in bound - so, must be in view, cannot be part of the previous or
  // next month.  selectedInBounds cannot be true without selectedInGrid being true, hoever, 
  // selectedInGrid may be true and selectedInBounds false.

  // If you are using calOnlyMonth, isSelectedInBounds is a better test for visibility.
  selectedInBounds   : [boolean]
}

This trigger is bubbled when the DateBox control is enabled.

$(input).bind( "datebox", function ( e, passed ) { 
  if ( passed.method === "enable" ) {
    alert( "Datebox was enabled!" );
  }
});

This trigger is bubbled when the datebox control is changed.

$(input).bind( "datebox", function ( e, passed ) { 
  if ( passed.method === "offset" ) {
    alert("New datet: " + passed.newDate);
    alert("Field offset: " + passed.type);
    alert("Offset amount: " + passed.amount);
  }
});
Arguments Recieved
  • newDate : JavaScript Date() object of the new date
  • type : Field Changed
  • y - Year
  • m - Month
  • d - Date
  • h - Hour
  • i - Minute
  • s - Second
  • a - Meridiem
  • amount: Amount of change, +/-

This trigger is bubbled when datebox has been refreshed.

$(input).bind( "datebox", function ( e, passed ) { 
  if ( passed.method === "refresh" ) {
    alert( "Datebox was refreshed!" );
  }
});

This is bubbled when the DateBox is set.

```js $(input).bind( "datebox", function ( e, passed ) { if ( passed.method === "set" ) { alert( "Formatted value is: " + passed.value ); alert( "JavaScript Date object is: " + passed.date ); } });

Return Values:
  • value - Formatted date string
  • date - JavaScript Date() object

Triggers

These are events that change something about DateBox.

This trigger will close the DateBox control

$(input).trigger( "datebox", { "method" : "close" });

This trigger will change the internal date of datebox. Functionally identical to hitting a +/- button in the control, or sliding/flipping a value

$(input).trigger( "datebox", {
  "method" : "dooffset",
  "amount" : <INTEGER amount>,
  "type": <CHARACTER field>
});

Required Arguments:

  • INTEGER amount : Integer amount to offset, +/-
  • CHARACTER field : Date part to change:
  • y - Year
  • m - Month
  • d - Date
  • h - Hour
  • i - Minute
  • s - Second

This trigger will refresh the datebox control. Functionally equivalent to the public refresh function

$(input).trigger( "datebox", { "method" : "dorefresh" });

This trigger will refresh / populate the value of the original input

$(input).trigger( "datebox", { "method" : "doset" });

This trigger will close the DateBox control

$(input).trigger( "datebox", { "method" : "open" });

This trigger will set the date for the DateBox control.

$(input).trigger( "datebox", { "method" : "set", "value" : <STRING Date> });

This is similar to setTheDate, however, this traditionally expects a formatted date string, but will accept a Date() object. It is far, far preferable to use the setTheDate function.

Example - Linked Dateboxes

Source - Script
function linker(obby, nextDatebox) {
    var setDate = obby.date;

    setDate.adj(2, 1); // Add One Day

    // Format the date for min/max attribute
    minDateString = this.callFormat('%Y-%m-%d', setDate);

    // Set min date and a default on "next" datebox
    // We set the min to not allow dates before a day after checkin to be picked.
    // We set the default to make sure the view is appropriate.

    // In this case, should you want to "suggest" a one week stay, add 6 more days to
    // setDate, *after* pulling the minimum date ISO string.
    $('#' + nextDatebox).datebox({
        minDate      : minDateString,
        defaultValue : setDate
    });

    // Open "next" datebox
    $('#' + nextDatebox).datebox('open');
}
Source - HTML
<div class="form-group">
    <label for="in_date">Check In Date</label>
    <input id="in_date" class="form-control" data-role="datebox" data-options='{"mode":"calbox","afterToday":true,"closeCallback":"linker","closeCallbackArgs":["out_date"]}' type="text">
</div>
<div class="form-group">
    <label for="out_date">Check Out Date</label>
    <input id="out_date" class="form-control" data-role="datebox" data-options='{"mode":"calbox"}' type="text">
</div>
JTSage DateBox Documentation v.5.1.4