Javascript Date Selector

A Javascript Date/Time Selector Object	Return to Index

dateSelector( object_name, output_field_id, output_format, initial_time )

An easy to use & versatile javascript date/time selector for use in web pages. As javascript is primarily a client-side scripting language, it has two major advantages over date selectors written with server-side languages like perl or php: Firstly, there is much less complication in generating dates and times that correspond to that set on the user machine, rather than that set at the host server (which could be anywhere in the world, and in any case, is often innaccurate). Secondly, there is no need to render a new page each time the date is changed, which can be tiresome. Date changes made by the user are reflected instantly with no posting of values.

A javascript object has been developed to take all of the donkey work out of creating a useable date selector. It has one very unconventional feature that has facilitated its creation (as you will see). This object has been given the simple name dateSelector.

To use the dateSelector object, you must first include the file dateselector.js in the <head> section of your html code (right click on the file name to download it). Include the file in your code like this:

<script type="text/javascript" language="javascript" src="dateselector.js">
  // your code in here if you want to detect file load failure
</script>

A dateSelector object is created (inside javascript tags) like this:

var selector_1 = new dateSelector( "selector_1" );

selector_1 is a (user supplied) variable name that will refer to this new dateSelector object. Note the unconventional feature here is that the constructor function dateSelector() is supplied with its own name, i.e. new dateSelector( "selector_1" ). It is vital that this simple rule is followed for the selector to work.

Having created our date selector, we can now draw it on the web page with the object method drawDateTimeSelector() like this:

selector_1.drawDateTimeSelector();

Just the two lines of javascript code lead to the following output on the web page:

Notice how the date and time default to the current time on your computer. Try using the selector, and notice how it is impossible to enter an invalid time & date, like February 29th 2003, or April 31st (any year). The selector self-corrects to the next valid day.

Once a dateSelector has been drawn, it cannot be drawn again (the object only allows itself to be drawn once), but you can create as many separate date selectors as you like (with different variable names) on one page.

Also, you can draw the selector in different ways. Using the method drawDateTimeSelector_noTitles() like this:

var selector_name = new dateSelector( "selector_name" );
selector_name.drawDateTimeSelector_noTitles();

leads to a date/time display with no titles:

Using the method drawDateSelector() like this:

selector_name.drawDateSelector();

leads to a date with no time display:

Using the method drawDayOfYearSelector() like this:

selector_name.drawDayOfYearSelector();

leads to a date with no year display: which might be used for entering birthdays etc.

Using the method drawMonthAndYearSelector() like this:

selector_name.drawMonthAndYearSelector();

leads to a date with no day display: which might be used for selecting a particular calendar month display etc.

There are many different ways of accessing the date or components of the date from a dateSelector object, but for convenience it has its own built in mechanism for automatically outputting its current value as soon as it changes.

If you create a text field somewhere in your html document like this:

<b>Output</b> <input type="text" id="date5_output" name="date5" size="35">

and when creating the dateSelector object, you add the id of this text field as the second parameter in the constructor, like this:

var selector_name = new dateSelector( "selector_name", "date5_output" );

Depending on your layout, the resulting output on the web page can be something like this:

Output

Try altering this date to see what happens...

The resulting automatic output is a representation of the date stored in the dateSelector object. In this case you are seeing the default output format, which is the number of milliseconds since midnight, 1st January 1970. This number is how the date is stored in a javascript Date() object

Making the output field hidden, as in <input type="hidden" ... > enables you to store the current value of the date selector for posting to another page without the user having to be aware of its presence.

There are alternative output formats you can use, which can be set with a third parameter in the constructor, like this:

var selector_name = new dateSelector( "selector_name", "output_id", "gmt_str" );

Output

This specifies that the output format is to be a gmt string representation of the date (note that the exact format of the gmt display varies between browsers).

The complete list of available output formats is as follows:


3rd param	selector	output

js_timestamp		millisecs since 1/1/1970
php_timestamp		secs since 1/1/1970 (for php date)
sql_date		sql date format
sql_datetime		sql date & time format
gmt_str		gmt string (varies with browser)
locale_str		locale string (varies with browser)

If you want the output field to contain the correct dateselector output value when the page is first loaded, you need to call the method refresh_outputs() like this:

selector_name.refresh_outputs();

This needs to be done after the page has finished loading, using the onload property in the <body> tag. As there may be other tasks to do with javascript when the page is first loaded, it is best to do this in a page initialisation function in the <head> of the document like this:

function init()
{
  selector_name.refresh_outputs();
  ... other javascript task;
  ... other javascript task;
}

and call init() like this:

<body ...  onload="javascript:init();">

The output field is then automatically filled when the page finishes loading:

You can set the initial value of the dateSelector object to any value you want with the fourth parameter in the constructor, like this:

var selector_name = new dateSelector( "selector_name", output_id, output_type, 1085609280000 );

Which leads to:

Output

This fourth parameter is a javascript date value, which is the number of milliseconds since midnight Jan 1st 1970. This might be posted from a previous page (note that if you use a date generated in php code, it is the number of seconds since 1/1/70 and so would just need multiplying by 1000).

You can also set the individual elements of a dateSelector object. Suppose we create a selector with an SQL date/time output like this:

var selector_name = new dateSelector( "selector_name", output_id, "sql_datetime" );

You can set the year range for the selector using the method setYearRange( startYear, endYear ) like this:

selector_name.setYearRange( 1960, 2010 );

Output

Note that the year range must be set before the year selector is drawn

You can create your own date layout by calling the individual elements of the selector display with these methods:

selector_name.drawDaySelector()
selector_name.drawMonthSelector()
selector_name.drawYearSelector()
selector_name.drawHourSelector()
selector_name.drawMinuteSelector()			Output

Note that you can call each of the above methods only once for each dateSelector object.

There are also other ways of getting an output value from the selector apart from using an output field using javascript. This would typically be done in a javascript function called when a link is activated, or any other event occurs on the page that can trigger a function call (like onchange="javascript:func()" or onclick="javascript:func()" inside an <input ... > tag). Values you can easily access are:

selector_name.day		day of month (1 to 31)
selector_name.month		month (0 to 11)
selector_name.year		year (4 digits)
selector_name.hour		hour (0 to 59)
selector_name.minute		minute (0 to 59)

Note that you could also set any of these values as well as just getting them, but if you do, you must call the method selector_name.updateDateFromParams() to correct and update the object, and then call selector_name.refresh_outputs() to update any displays. On the whole it is better not to set any of these values unless you can see and understand how the dateSelector object works.

At the core of the dateSelector object is a standard javascript Date object. This can be accessed using selector_name.date, to which you can apply any of the normal Date object functions. For instance, if you wanted to get the javascript timestamp (millisecs since 1/1/70) from the object, you would use selector_name.date.getTime()

Most of the values you might need are readily available from the dateSelector object, but two other standard Date object functions might come in useful. These are:

selector_name.date.getDay() which returns the day of the week (0 to 6, 0 being Sunday)

selector_name.date.getTimezoneOffset() which returns the minutes offset of the client machine from GMT (an approximate method of determining user longitude, which could be used for setting language version or currency type initial settings on a web page).

Other useful inspection functions are:

selector_name.get_sql_datetime()   which returns a string like
selector_name.get_sql_date()   which returns a string like
selector_name.get_php_secs()   which returns a number like
selector_name.get_timestamp()   which returns a number like

Other useful setting functions are:

selector_name.addDay()   where
selector_name.addDay( 3 )   where
selector_name.addDay( -7 )   where

selector_name.addWeek()   where
selector_name.addWeek( 4 )   where
selector_name.addWeek( -5 )   where

selector_name.addMonth( 14 )   where
selector_name.addMonth( -24 )   where
selector_name.addMonth( 12 )   where

selector_name.addYear()   where
selector_name.addYear( 3 )   where
selector_name.addYear( -10 )   where

Output End Time