Low Level Methods
There are six basic low level methods:
Each of these methods accepts two arguments, both optional:
- First Argument: Date/Time Value
When the browser user fills in a
form and clicks the Submit button, the browser sends a POST
HTTP message to the web
server with the name and value of each field of the form. When
PHP processes the POST message it puts the name and value of each
field of the message into global variable
$_REQUEST
before starting execution of the Trax application. Therefore if
a value for a field is present in $_REQUEST, it is because the
user specifically entered that value, or accepted a value that
was already there. This information is assumed to be more valid
than the date/time value in the argument, so if a value for this
field is defined in $_REQUEST, that value is used and the
argument is ignored.
If there is no defined value for the field in $_REQUEST,
then the argument is used to generate the initially selected
value in the menu, or if the argument is also omitted,
the current date/time is initially
selected.
- Second Argument: Output Format Options
Specify the format of the HTML string returned by
the method. If omitted, the output will be
in a default format.
Each of these methods returns a character string containing HTML
defining the pulldown menu as
<select name=...>
<option value=...> ... </option>
<option value=...> ... </option>
...
</select>
This character string is ready to be inserted directly into a page.
First Argument: Date/Time Value
As mentioned above, if a DateHelper object is created as a
result of a POST message, the values transmitted in the
message will appear in $_REQUEST, so this value is assumed to be
more valid than the argument value.
However, the six low-level methods do not access this
information directly from $_REQUEST. Instead, they rely on the
fact that
check_request_for_value()
was called previously to parse the contents of $_REQUEST and
copy relevant values to instance variables named
$request_
s
where is the type of
time unit supported by the method (minute, month etc.). The
$request_
s
instance variables are arrays indexed by the name of the field, so
that if there were two year selector fields named
start_year
and end_year
in
the POST message, check_request_for_value()
would store their values in
$request_years['start_year']
and
$request_years['end_year']
respectively.
At the time the DateHelper object is created, the name of the
field that it processes is assigned to instance variable
$attribute_name. So in the
example of the two year fields named start_year
and end_year
, two DateHelper objects would be
created, one with
$attribute_name = 'start_year'
and the other with
$attribute_name = 'end_year'
. Usually this
value is set in the object constructor call. So when
select_year()
is called, it checks
$this->request_years[$this->attribute_name]
to see if the user specified an initial value for the
field whose name is in $attribute_name
.
.
If the method finds no value in
$request_
s
,
it examines the first argument. Two types of value are
legitimate for this argument: a string of decimal digits of exactly
the right length and value, and a date/time description in any of
the formats accepted by http://www.php.net/strtotime.
It is often most practical to use a single date/time value for all
select_
()
calls, usually the SQL format
YYYY-MM-DD HH:MM:SS
.
Given an argument value in this format, the method extracts that
part of the argument applicable to its type. For example:
$datetime = '1997-10-23 17:46:57';
select_month($datetime);
select_day($datetime);
select_year($datetime);
would create three menus, a month menu with initial value 'October',
a day menu with initial value '23' and a year menu with initial
value '1997'.
The options available on each menu of course depend on the
type. A month menu always has twelve months, a day menu always has
31 days and so forth. In the case of the year menu, there are a
potentially infinite number of possible years, so the default is to
generate options in the range of the initial value plus or
minus five years. The range can be changed with the second
argument.
Second Argument: Output Format Options
The second argument to a low-level method call is an array
in which each key is a character string naming an option, and the
value assigned to that key is the option value, which may be either a
character string or boolean value depending on the option.
Certain options are available for all method types. One such
option is include_blank
. This governs whether
or not there is a blank as one option of the menu. The default
value is 'include_blank'=>false
which prevents
the blank line. You can specify
'include_blank'=>true
in your options array to
cause a blank line to appear as an option. Unfortunately there is
currently no way to choose that as the initially selected value,
nor to insert a line with a character string value such as
--Select--
.
Three options, also available for all method types, combine
to set the value of the name
attribute of the
output <select>
. They are
prefix
,
field_name
and
discard_type
. The default combination is
'prefix'=>null
,
'discard_type'=>false
and
'field_name'=>
.
The type of select_year()
is
'year'
, so the method call
select_year();
is equivalent to
select_year(null,array('prefix'=>null,'discard_type'=>false,
'field_name'=>'year'));
which generates as output
<select name="year">...</select>
.
A simple change is to replace the default name, so
select_year(null,array('field_name'=>'start_year'));
will generate
<select name="start_year">...</select>
.
It is also possible to insert a prefix before the name. The
simplest case is to insert the prefix while maintaining the
default name:
select_year(null,array('prefix'=>'start_date'));
will generate
<select name="start_date[year]">...</select>
.
This is a handy way to assign related names to several date/time fields.
Finally it is possible to have the prefix replace the name
completely. This is done with the
'discard_type'
option, which prevents output of
the value of the
'field_name'
option. So the method call
select_year(null,array('prefix'=>'start_date','discard_type'=>true));
will generate
<select name="start_date">...</select>
.
start_year, end_year for select_year()
Composite Methods
Combine or specialize calls to low level methods
options:field_separator on to_date_select_tag().
Discard components