Warning ! this module is no longer supported
( Please read this before considering using it)

Description

A lot of application need to deal with date computing and editing, and because there is no "ready to use" support for this, you often have to deal with many details, such as: splitting date fields in their fragments (day, month and year for example), merging them back to build something your computing language can understand, etc. There are many ways of handling this: a server side API can generates the necessary things on the fly and make your browser "data-aware" by splitting date fields into individual elements (day, month, year). If it's smart enough, it can also send some javascript to make sure end user enter valid dates.

This library aim to provide a simple 100% client-side support for date fields so that your server side code only manipulate dates through single values that follow your prefered format (MMDDYYYY, DD/MM/YYYY, etc.).

How to use it

HTML Declaration

HTML	<input mjstype="date" mjsdateformat="mmddyyyy:mm/dd/yyyy" type="text" name="date" value="01202004">	<input mjstype="date" mjsdateformat="mmddyyyy:yyyy-mm-dd" type="text" name="date" value="01202004">
	English style dates edited with / separators	English dates with ISO editing order
without date.js
with date.js

Attributes

It only consists of defining two customized attributes which you can attach to a INPUT/textfield control:

mjstype="date"

As you may have seen in other components of this library, the "mjstype" attribute defines behaviors for a given element. Here, we want the INPUT field to act as a date input control by setting the "date" value.

mjsdateformat="format" mjsdateformat="storageFormat:editingFormat"

This identifies which date format your software is using. Your server side backend will send dates according to this format, and the client will send back form values that respect the same format obviously. This format is necessary to tell the clientside code how to decode a date field (where is the 'day' part, are there separators, etc.). The table below summarizes the possible values for this attribute (case is not sensitive):

yyyy-mm-dd	ISO format with "-" separators (default)
yyyy/mm/dd	ISO format with "/" separators
mmddyyyy	english format, without separator
ddmmyyyy	french type format, without separator
yyyymmdd	ISO format
mm/dd/yyyy	english format with separators.
dd/mm/yyyy	french format with separators.

The following formats can only be choosen as editing format:

mm\|dd\|yyyy	date field is replaced by 3 separated fields, for day, month and year fragments, in the english date order (month, day, year)
dd\|mm\|yyyy	date field is replaced by 3 separated fields in the french date order.
yyyy\|mm\|dd	date field is replaced by 3 separated fields in ISO order.

You can distinguish the format that will be used for storing the dates (used with CGI interactions) form the format which will be used for editing. For example, if your backend deals with english dates (MMDDYYYY) but you want french users enter date with the french layout (DDMMYYYY), you could use the coumpound attribute: mjsdateformat="mmddyyyy:ddmmyyyy", with the left part for storage and the right side for editing.

TIP: the format is an inherited attribute; you may want to define once for all in the document by attaching it to the BODY tag. You also may want to change the default more globally by using the javascript API (see API details).

Field verification

By default, the library verifies that dates are valid by making sure they correspond to a day that exists. You may also want to perform more controls on the date, such as checking if it's in a given range. To make this possible and simple, the date module extends the form validation module ("formval") with date awareness.

HTML	<input mjstype="date" mjsdateformat="mm/dd/yyyy" mjscheck="required&max=today" type="text" name="date">	<input mjstype="date" mjsdateformat="mmddyyyy:dd\|mm\|yyyy" mjscheck="required&range=01012004...today" type="text" name="date">
UI	Enter a date anterior than today	Enter a date between Jan 1st 2004 and now

HTML

<input mjstype="date"
    mjsdateformat="mm/dd/yyyy"
    mjscheck="required&max=today"
    type="text" name="date">

<input mjstype="date"
    mjsdateformat="mmddyyyy:dd|mm|yyyy"
    mjscheck="required&range=01012004...today"
    type="text" name="date">

Date ranges (or min / max) can be set with a plain date expressed in the storage format
A few special keywords can be used instead of plain dates: "today", "tomorrow", "yesterday"

Technical notes

How it works

At initialization time, the module search for all INPUT elements having a "mjstype" attribute set to "date". For each of them, it creates 3 new fields for date fragments editing and hide the original date field. Then, it attach a "onchange" callback to every date fragment, which will be in charge to craft the date value out of its fragments every time the end user change their individual values; this ensure that the original date field is always up to date and reflect what the user entered in separated field.

CGI interactions

Your server side program will only deal with the storage date format you have choosen via the mjsdateformat attribute. As usual, don't trust verbatim client side control because they're unreliable: you shall test the date validity in your server-side code as well.

JavaScript API

mjs_setDateFormat(fmt)

The mjs_setDateFormat() function defines the default values for editing and storage date formats. Keep in mind that attribute specified within the element, or inherited form its ancestor, prevail to this global setting.

<script>
  mjs_setDateFormat("DDMMYYYY:DD-MM-YYYY"); // Set my default date format globally
</script>

mjs_setDateSplitter(str)

When one of the editing date format imposes the creation of date subfields (ex: "YYYY|MM|DD"), the date module uses the "splitter" string to separate date fragments. You can change the default "/" by something else by using this function. The passed parameter is a string containings HTML.