[Sommaire] [Imprimer]

   1  <refentry id="{@id}" revision="$Id: DateHelper.cls 199 2006-05-05 01:52:43Z haas $">
   2   <refnamediv>
   3    <refname>DateHelper</refname>
   4    <refpurpose>Date/time pulldown menu utilities class</refpurpose>
   5   </refnamediv>
   6   <refsynopsisdiv>
   7    <author>
   8     Walt Haas
   9     <authorblurb>
  10      {@link mailto:haas@xmission.com haas@xmission.com}
  11     </authorblurb>
  12    </author>
  13   </refsynopsisdiv>
  14   {@toc}
  15   <refsect1 id="{@id intro}">
  16    <title>Introduction</title>
  17    <para>The {@link DateHelper} class provides a variety of utility
  18     methods to help construction of pulldown menus for dates and
  19     times.  Calls to DateHelper methods are generated by
  20     {@link ActiveRecordHelper::to_scaffold_tag()} in response to the
  21     <literal>php<entity>&nbsp;</entity>script/generate.php<entity>&nbsp;</entity>scaffold</literal> console
  22     command.  The call generated for each data item is chosen based 
  23     on the data type reported by the database for the corresponding
  24     column.</para>
  25  
  26    <para>There are two main groups of methods in the DateHelper class:
  27     <orderedlist>
  28      <listitem>Low level methods that generate a menu with a name and
  29       options controlled by the arguments of the method
  30       call.</listitem>
  31      <listitem>High level methods that use the name of an
  32       {@link ActiveRecord} subclass and one of its attributes to
  33       reference the database for a value.  These methods use the
  34       information from the database to construct arguments, then call
  35       corresponding low level methods to generate the HTML.</listitem>
  36     </orderedlist></para>
  37  
  38    <para>DateHelper must be instantiated before its methods can be
  39     called. For each DateHelper method called from a form, there is a
  40     corresponding function that creates an instance of DateHelper then
  41     passes its arguments to the relevant method of that instance.
  42     These functions usually have the same name as the method they call,
  43     and the functions are grouped together in the
  44     {@link date_helper.php} procedural file following the definition of
  45     the DateHelper class.</para>
  46   </refsect1>
  47   <refsect1 id="{@id low_level}">
  48    <title>Low Level Methods</title>
  49    <para>There are six basic low level methods:
  50     <itemizedlist>
  51      <listitem>{@link DateHelper::select_day() select_day()}</listitem>
  52      <listitem>{@link DateHelper::select_hour() select_hour()}</listitem>
  53      <listitem>{@link DateHelper::select_minute() select_minute()}</listitem>
  54      <listitem>{@link DateHelper::select_month() select_month()}</listitem>
  55      <listitem>{@link DateHelper::select_second() select_second()}</listitem>
  56      <listitem>{@link DateHelper::select_year() select_year()}</listitem>
  57     </itemizedlist>
  58     Each of these methods accepts two arguments, both optional:
  59  
  60     <orderedlist>  
  61      <listitem><command>First Argument: Date/Time Value</command>
  62       <cmdsynopsis><para>When the browser user fills in a
  63       form and clicks the Submit button, the browser sends a POST
  64       {@link http://en.wikipedia.org/wiki/HTTP HTTP} message to the web
  65       server with the name and value of each field of the form.  When
  66       PHP processes the POST message it puts the name and value of each
  67       field of the message into global variable
  68       {@link http://www.php.net/manual/en/reserved.variables.php#reserved.variables.request $_REQUEST}
  69       before starting execution of the Trax application.  Therefore if
  70       a value for a field is present in $_REQUEST, it is because the
  71       user specifically entered that value, or accepted a value that
  72       was already there.  This information is assumed to be more valid
  73       than the date/time value in the argument, so if a value for this
  74       field is defined in $_REQUEST, that value is used and the
  75       argument is ignored.</para>
  76  
  77       <para>If there is no defined value for the field in $_REQUEST,
  78        then the argument is used to generate the initially selected
  79        value in the menu, or if the argument is also omitted, 
  80        the current date/time is initially
  81        selected.</para></cmdsynopsis></listitem> 
  82  
  83      <listitem><command>Second Argument: Output Format Options</command>
  84       <cmdsynopsis>Specify the format of the HTML string returned by
  85       the method.  If omitted, the output will be
  86       in a default format.</cmdsynopsis></listitem>
  87     </orderedlist>
  88  
  89     Each of these methods returns a character string containing HTML
  90     defining the pulldown menu as
  91     <example>
  92  &lt;select name=...&gt;
  93  &lt;option value=...&gt; ... &lt;/option&gt;
  94  &lt;option value=...&gt; ... &lt;/option&gt;
  95  ...
  96  &lt;/select&gt;
  97     </example>
  98     This character string is ready to be inserted directly into a page.
  99    </para>
 100    <refsect2 id="{@id low_level_arg1}">
 101     <title>First Argument: Date/Time Value</title>
 102     <para>As mentioned above, if a DateHelper object is created as a
 103      result of a POST message, the values transmitted in the
 104      message will appear in $_REQUEST, so this value is assumed to be
 105      more valid than the argument value.</para>
 106  
 107     <para>However, the six low-level methods do not access this
 108      information directly from $_REQUEST.  Instead, they rely on the
 109      fact that
 110      {@link DateHelper::check_request_for_value() check_request_for_value()}
 111      was called previously to parse the contents of $_REQUEST and
 112      copy relevant values to instance variables named
 113      <literal>$request_</literal><arg choice="tute-comment">typename</arg><literal>s</literal>
 114      where <arg choice="tute-comment">typename</arg> is the type of
 115      time unit supported by the method (minute, month etc.).  The
 116      <literal>$request_</literal><arg choice="tute-comment">typename</arg><literal>s</literal>
 117      instance variables are arrays indexed by the name of the field, so
 118      that if there were two year selector fields named
 119      <literal>start_year</literal> and <literal>end_year</literal> in
 120      the POST message, <literal>check_request_for_value()</literal>
 121      would store their values in
 122      <literal>$request_years['start_year']</literal> and
 123      <literal>$request_years['end_year']</literal> respectively.</para>
 124  
 125     <para>At the time the DateHelper object is created, the name of the
 126      field that it processes is assigned to instance variable
 127      {@link Helpers::$attribute_name $attribute_name}.  So in the
 128      example of the two year fields named <literal>start_year</literal>
 129      and <literal>end_year</literal>, two DateHelper objects would be
 130      created, one with
 131      <literal>$attribute_name = 'start_year'</literal>
 132      and the other with
 133      <literal>$attribute_name = 'end_year'</literal>.  Usually this
 134      value is set in the object constructor call.  So when
 135      <literal>select_year()</literal> is called, it checks 
 136      <literal>$this->request_years[$this->attribute_name]</literal>
 137      to see if the user specified an initial value for the
 138      field whose name is in <literal>$attribute_name</literal>.
 139  .</para>
 140  
 141    <para>If the method finds no value in
 142     <literal>$request_</literal><arg choice="tute-comment">typename</arg><literal>s</literal>,
 143     it examines the first argument.  Two types of value are
 144     legitimate for this argument: a string of decimal digits of exactly
 145     the right length and value, and a date/time description in any of
 146     the formats accepted by {@link PHP_MANUAL#strtotime strtotime()}.
 147     It is often most practical to use a single date/time value for all 
 148     <literal>select_</literal><arg choice="tute-comment">typename</arg><literal>()</literal>
 149     calls, usually the SQL format
 150     <literal>YYYY-MM-DD<entity>&nbsp;</entity>HH:MM:SS</literal>.
 151     Given an argument value in this format, the method extracts that
 152     part of the argument applicable to its type.  For example:
 153  <example>
 154  $datetime = '1997-10-23 17:46:57';
 155  select_month($datetime);
 156  select_day($datetime);
 157  select_year($datetime);
 158  </example>
 159      would create three menus, a month menu with initial value 'October',
 160      a day menu with initial value '23' and a year menu with initial
 161      value '1997'.</para>
 162  
 163    <para>The options available on each menu of course depend on the
 164     type. A month menu always has twelve months, a day menu always has
 165     31 days and so forth.  In the case of the year menu, there are a
 166     potentially infinite number of possible years, so the default is to
 167     generate options in the range of the initial value plus or
 168     minus five years.  The range can be changed with the second
 169     argument.</para>
 170    </refsect2>
 171    <refsect2 id="{@id low_level_arg2}">
 172     <title>Second Argument: Output Format Options</title>
 173     <para>The second argument to a low-level method call is an array
 174      in which each key is a character string naming an option, and the
 175      value assigned to that key is the option value, which may be either a
 176      character string or boolean value depending on the option.</para>
 177  
 178     <para>Certain options are available for all method types.  One such
 179      option is <literal>include_blank</literal>.  This governs whether
 180      or not there is a blank as one option of the menu. The default
 181      value is <literal>'include_blank'=>false</literal> which prevents
 182      the blank line.  You can specify
 183      <literal>'include_blank'=>true</literal> in your options array to
 184      cause a blank line to appear as an option.  Unfortunately there is
 185      currently no way to choose that as the initially selected value,
 186      nor to insert a line with a character string value such as
 187      <literal>--Select--</literal>.</para>
 188  
 189     <para>Three options, also available for all method types, combine
 190      to set the value of the <literal>name</literal> attribute of the
 191      output <literal>&lt;select&gt;</literal>.  They are
 192      <literal>prefix</literal>, 
 193      <literal>field_name</literal> and
 194      <literal>discard_type</literal>.  The default combination is
 195      <literal>'prefix'=>null</literal>,
 196      <literal>'discard_type'=>false</literal> and 
 197      <literal>'field_name'=></literal><arg choice="tute-comment">typename</arg>.
 198      The type of <literal>select_year()</literal> is
 199      <literal>'year'</literal>, so the method call
 200      <literal>select_year();</literal> is equivalent to 
 201      <literal>select_year(null,array('prefix'=>null,'discard_type'=>false,
 202      'field_name'=>'year'));</literal> which generates as  output
 203      <literal>&lt;select<entity>&nbsp;</entity>name="year"&gt;...&lt;/select&gt;</literal>.
 204      </para>
 205  
 206     <para>A simple change is to replace the default name, so
 207      <literal>select_year(null,array('field_name'=>'start_year'));</literal>
 208      will generate
 209      <literal>&lt;select<entity>&nbsp;</entity>name="start_year"&gt;...&lt;/select&gt;</literal>.
 210      </para>
 211  
 212     <para>It is also possible to insert a prefix before the name.  The
 213      simplest case is to insert the prefix while maintaining the
 214      default name: 
 215      <literal>select_year(null,array('prefix'=>'start_date'));</literal>
 216      will generate
 217      <literal>&lt;select<entity>&nbsp;</entity>name="start_date[year]"&gt;...&lt;/select&gt;</literal>.
 218      This is a handy way to assign related names to several date/time fields.
 219      </para>
 220  
 221     <para>Finally it is possible to have the prefix replace the name
 222      completely.  This is done with the
 223      <literal>'discard_type'</literal> option, which prevents output of
 224      the value of the
 225      <literal>'field_name'</literal> option.  So the method call
 226      <literal>select_year(null,array('prefix'=>'start_date','discard_type'=>true));</literal>
 227      will generate
 228      <literal>&lt;select<entity>&nbsp;</entity>name="start_date"&gt;...&lt;/select&gt;</literal>.
 229      </para>    
 230  
 231      <para>start_year, end_year for select_year()</para>
 232  
 233    </refsect2>
 234  
 235    <refsect2 id="{@id low_level_composite}">
 236     <title>Composite Methods</title>
 237     <para>Combine or specialize calls to low level methods</para>
 238     <itemizedlist>
 239      <listitem>{@link DateHelper::select_date() select_date()}</listitem>
 240      <listitem>{@link DateHelper::select_datetime()
 241       select_datetime()}</listitem>
 242      <listitem>{@link DateHelper::select_expiration_date()
 243       select_expiration_date()}</listitem>
 244      <listitem>{@link DateHelper::select_time() select_time()}</listitem>
 245     </itemizedlist>
 246      <para>options:field_separator on to_date_select_tag(). 
 247       Discard components</para>
 248  
 249    </refsect2>
 250   </refsect1>
 251  
 252   <refsect1 id="{@id high_level}">
 253    <title>High Level Methods</title>
 254    <para>Use model data as arguments for low level methods.  Page calls
 255     function which creates DateHelper object and calls method</para>
 256    <para>All use {@link DateHelper::value()} to get data from model</para>
 257     <itemizedlist>
 258      <listitem>{@link datetime_select() datetime_select() function}
 259       calls {@link DateHelper::datetime_select() datetime_select()
 260       method}</listitem>
 261      <listitem>{@link date_select() date_select() function} calls
 262       {@link DateHelper::date_select() date_select() method}</listitem>
 263      <listitem>{@link expiration_date_select() expiration_date_select()
 264       function} calls {@link DateHelper::expiration_date_select()
 265       expiration_date_select() method}</listitem>
 266      <listitem>{@link time_select() time_select() function}
 267       calls {@link DateHelper::time_select() time_select()
 268       method}</listitem>
 269      <listitem>{@link year_select() year_select() function}
 270       calls {@link DateHelper::year_select() year_select()
 271       method}</listitem>
 272     </itemizedlist>
 273    
 274   </refsect1>
 275  <!--
 276  Local variables:
 277  mode: xml
 278  c-basic-offset: 1
 279  indent-tabs-mode: nil
 280  End:
 281  -->
 282  </refentry>