Fully document and refine what calFormatter actually does

[jtsage]

Looking at #356, there is a fair bit of intended functionality. Most of it works. document it.

Things that should be in the passed object:

• what's the first real visible date?
• what's the last real visible date?
• what's the date for the box we're working on?
• what's the date the user has selected? (a.k.a. the default or today if they haven't picked one)
• what's the internal date object (this is the one that moves around as we move the calendar around. It's not really selected yet)
• is that (the user selected one) date visible?
• is this (the one we're working on) valid with the set limits?
• what theme should be applied?

What should be returned?

• Option 1 : a string to stuff into the the framework defined HTML for this element. innerHTML probably, we should allow for "inline" HTML. (this makes knowing the theme somewhat

• Option 2 : a string to replace the framework defined HTML for this element. (more dangerous option, but should be possible)

What scope?

This currently runs detached, but it would probably make life way easier if it ran in the context of the widget, you could do:

this.setTheDate()

rather than

$(element).datebox('setTheDate', ...);

[jtsage]

Ok. bit of an update.

calFormatter is a function that gets a single argument of the display object. in it is:

{
  // 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]
}

[jtsage]

What should be returned?

• [x] Option 1 : a string to stuff into the the framework defined HTML for this element. This can contain inline HTML.

• [ ] ~Option 2 : a string to replace the framework defined HTML for this element.~ Rejected: this is what calBeforeAppendFunc is for. With the bonus that you can alter the already created HTML element.

[jtsage]

Things that should be in the passed object:

From the above list, things that are:

• [ ] what's the first real visible date?
• [ ] what's the last real visible date?
• [x] what's the date for the box we're working on?
• [ ] what's the date the user has selected? (a.k.a. the default or today if they haven't picked one)
• [ ] what's the internal date object (this is the one that moves around as we move the calendar around. It's not really selected yet)
• [ ] is that (the user selected one) date visible?
• [x] is this (the one we're working on) valid with the set limits?
• [x] what theme should be applied?

Things that are not, because they are easily accessible in the this context.

• [x] what's the first real visible date?

var firstGridDate = this.getCalStartGrid();

• [x] what's the last real visible date?

var lastGridDate = this.getCalEndGrid();

• [x] what's the date the user has selected? (a.k.a. the default or today if they haven't picked one)

// These are identical.  Note the copy, as it is a *mutable* object.
var userSelectedDate = this.originalDate.copy();
var userSelectedDate = this.getSelectedDate();

• [x] what's the internal date object (this is the one that moves around as we move the calendar around. It's not really selected yet)

// These are identical.  Note the copy, as it is a *mutable* object.
var workingDate = this.theDate.copy();
var workingDate = this.getTheDate();

• [x] is that (the user selected one) date visible?

var isSelectedVisible = this.isSelectedInCalGrid();

[jtsage]

Note:

Also changed the context of calBeforeAppendFunc() to be the widget as well, so the same rules of running datebox functions inside that callback apply.