PHPonTrax
[ class tree: PHPonTrax ] [ index: PHPonTrax ] [ all elements ]
Prev Next
DateHelper

DateHelper

Date/time pulldown menu utilities class

Table of Contents

Introduction

The DateHelper class provides a variety of utility methods to help construction of pulldown menus for dates and times. Calls to DateHelper methods are generated by ActiveRecordHelper::to_scaffold_tag() in response to the php script/generate.php scaffold console command. The call generated for each data item is chosen based on the data type reported by the database for the corresponding column.

There are two main groups of methods in the DateHelper class:

  1. Low level methods that generate a menu with a name and options controlled by the arguments of the method call.
  2. High level methods that use the name of an ActiveRecord subclass and one of its attributes to reference the database for a value. These methods use the information from the database to construct arguments, then call corresponding low level methods to generate the HTML.

DateHelper must be instantiated before its methods can be called. For each DateHelper method called from a form, there is a corresponding function that creates an instance of DateHelper then passes its arguments to the relevant method of that instance. These functions usually have the same name as the method they call, and the functions are grouped together in the date_helper.php procedural file following the definition of the DateHelper class.

Low Level Methods

There are six basic low level methods:

Each of these methods accepts two arguments, both optional:
  1. 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.

  2. 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_typenames where typename is the type of time unit supported by the method (minute, month etc.). The $request_typenames 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_typenames, 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_typename() 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'=>typename. 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


High Level Methods

Use model data as arguments for low level methods. Page calls function which creates DateHelper object and calls method

All use DateHelper::value() to get data from model

Prev   Next
ActiveRecord Router

Documentation generated on Thu, 04 May 2006 19:46:55 -0600 by phpDocumentor 1.3.0RC4