JTSageDateBox A multi-mode date and time picker

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

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.

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.

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.

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.

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.

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>";
}

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…

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" }, … ]

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.

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.

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.

$(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.

$(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.

This function can be used to close the control.

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

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" );

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

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

This function will disable the DateBox control.

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

This function will enable the datebox control.

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

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 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" );

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

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

This will return a specified options current value.

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

Option Name can be any datebox option.

Return the currently selected date object for any date mode.

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

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

Return the current date object for any date mode.

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

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() ) ) {
  ...
}

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" ) ) {
  ...
}

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" ) ) {
  ...
}

This function can be used to close the control.

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

$(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.

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> );

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

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.