File: readme.txt

class DATETIME:

This is the class to manipulate date and time on a form.

It will help on any form where you need use dropdown selects for dates and/or
time. With one method of this class you can easily generate a select on the form,
and initialize its value by any variables. You also will be able to check if date 
is correct or empty, and get UNIX timestamp and date/time entered.

HOW TO:

1. Copy class DATETIME to your includes directory.
2. Create PHP script that will include this class: 
	include("datetimeclass.inc");
3. Make instance of the DATETIME object:
	$datetime = new DATETIME();
4. Before generating selects use $datetime->set_datetime_byglobal() or 
	$datetime->set_datetime_byvar() to initialize its values
5. Use $datetime->get_select_...() methods to generate select on a form.
6. Use $datetime->get_date_error() to get input errors of date and 
	$datetime->get_date_entered() or/and $datetime->get_timestamp_entered() or/and
	$datetime->get_time_entered() to retrieve entered information.

OPTIONS AND FEATURES:

1. Class has two initial arrays:
	$current_names - array of current selects names. By default names are: "year", 
	"month", "day", "hour", "ampm", "minute", "second".
	$current_selected -  array of current values of each select.
2. You may change any select name using method $datetime->set_selectname($keyname, $new_name).
	$keyname - "yearname", "monthname", "dayname", "hourname", "ampmname", 
	"minutename", "secondname";
	$new_name - new name of select
Note: use this method BEFORE select initialization and actual output.
3. For convenience, 3 methods available as wrapper for set_selectname():
	$datetime->set_datename(...) - set names of 3 selects of date (month, day, year);
	$datetime->set_timename(...) - set names of 4 selects of time (hour, minute, second, ampm);
	$datetime->set_datetimename(...) - set all names in one call.
Note: You may leave any of "new" names parameter blank and class will use "existing" name.
Note: use these methods BEFORE select initialization and actual output. 
4. Initialize selects you have 3 methods:
	$datetime->set_datetime_byvar($datetimemix) - initialize selects using
	string variable date or(and) time format, ex: "March 10, 2001 5:16 pm". Use it 
	for initialization when date is inside range "Dec 31 1969" and "Jan 18 2038".
	$datetime->set_datetime_byglobal($global) - initialize selects by global
	variables. Default value is GLOBALS. Possible values are: "GLOBALS", 
	"HTTP_POST_VARS", "HTTP_GET_VARS", "HTTP_COOKIE_VARS", "HTTP_SESSION_VARS".
	$datetime->set_datetime_bycomponents(...) - initialize selects by separate
	components of date, such as day, year, month, hour, minute, second. Use it 
	for initialization when date is out of range "Dec 31 1969" and "Jan 18 2038".
Note: You need to initialize selects before actual output on the form.
5. Output selects on the form - available in the next 8 methods:
	$datetime->get_select(...) - private method of the class, used to draw actual
	dropdown list, supports parameters:
		select_name - name of select on the form
		select_array_values - array of values
		selected_value - currently selected value
		select_first_line - first line of select (ex. "hour")
		select_style - style property for select or/and javascript code associated with it.
		select_size - size of dropdown list (multiple choice doesn't support)
	$datetime->get_select_years(...) - draw actual select of years, support:
		year_style - 2 or 4 digit representation of year (ex. 2002 or 02)
		year_from, year_to - range of values
		select_first_line, select_style, select_size - select option
		textonly - if textonly method return just value, not actual select, that
		convenient to use in script or display on the page.
	$datetime->get_select_months(...) - draw actual select of month, support:
		leading_zeros - if leading_zeros options of select will has 2 digit (ex. 01, 12)
		month_style - digit (number of month), lword (3 letter abbreviation), sword (full word)
		... - see description before
	$datetime->get_select_days(...) - draw actual select of days, support:
		... - see description before
	$datetime->get_select_hours(...) - draw actual select of hours, support:
		hour_style - 12 or 24 cycle, if use 12 hours cycle, use select am - pm
		... - see description before
	$datetime->get_select_ampm(...) - draw actual select of day time, support:
		... - see description before
	$datetime->get_select_minutes(...) - draw actual select of minutes, support:
		... - see description before
	$datetime->get_select_seconds(...) - draw actual select of seconds, support:
		... - see description before
Note: With leading zeros or without one, values of selects always actual number.
6. Get values methods include:
	$datetime->get_date_entered() - simple get date entered in format month/day/year
	$datetime->get_time_entered() - simple get time entered in format hour:min:sec
	$datetime->get_timestamp_entered() - simple get UNIX timestamp of date entered
	$datetime->get_date_error() - check date and return errors of date entered
	$datetime->is_date_empty() - check is date entered (for required fields)
7. A couple of private methods:
	$datetime->isit_numeric() - is_numeric functionality
	$datetime->hours12to24() - correct time from 12 am-pm hours to 24 hours cycle
	

Author: Viatcheslav Ivanov, E-Witness Inc., Canada;
mail: ivanov@e-witness.ca, v_iv@hotmail.com;
web: www.e-witness.ca; www.coolwater.ca; www.strongpost.net;
version: 1.30 /03.14.2002