Show
Ignore:
Timestamp:
02/23/06 20:09:13 (6 years ago)
Author:
john
Message:

added in phpDoc commenting tests docs - Walt

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/trax/vendor/trax/action_view/helpers/active_record_helper.php

    r128 r138  
    11<?php 
    2 # $Id$ 
    3 # 
    4 # Copyright (c) 2005 John Peterson 
    5 # 
    6 # Permission is hereby granted, free of charge, to any person obtaining 
    7 # a copy of this software and associated documentation files (the 
    8 # "Software"), to deal in the Software without restriction, including 
    9 # without limitation the rights to use, copy, modify, merge, publish, 
    10 # distribute, sublicense, and/or sell copies of the Software, and to 
    11 # permit persons to whom the Software is furnished to do so, subject to 
    12 # the following conditions: 
    13 # 
    14 # The above copyright notice and this permission notice shall be 
    15 # included in all copies or substantial portions of the Software. 
    16 # 
    17 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
    18 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
    19 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
    20 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 
    21 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
    22 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 
    23 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 
    24  
     2/** 
     3 *  File containing ActiveRecordHelper class and support functions 
     4 * 
     5 *  (PHP 5) 
     6 * 
     7 *  @package PHPonTrax 
     8 *  @version $Id$ 
     9 *  @copyright (c) 2005 John Peterson 
     10 * 
     11 *  Permission is hereby granted, free of charge, to any person obtaining 
     12 *  a copy of this software and associated documentation files (the 
     13 *  "Software"), to deal in the Software without restriction, including 
     14 *  without limitation the rights to use, copy, modify, merge, publish, 
     15 *  distribute, sublicense, and/or sell copies of the Software, and to 
     16 *  permit persons to whom the Software is furnished to do so, subject to 
     17 *  the following conditions: 
     18 * 
     19 *  The above copyright notice and this permission notice shall be 
     20 *  included in all copies or substantial portions of the Software. 
     21 * 
     22 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
     23 *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
     24 *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
     25 *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 
     26 *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
     27 *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 
     28 *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 
     29 */ 
     30 
     31/** 
     32 * 
     33 *  @package PHPonTrax 
     34 */ 
    2535class ActiveRecordHelper extends Helpers { 
    2636     
    2737    public $scaffolding = 0; 
    2838 
    29     # Returns a default input tag for the type of object returned by the method. Example 
    30     # (title is a VARCHAR column and holds "Hello World"): 
    31     #   input("post", "title") => 
    32     #     <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> 
     39    /** 
     40     *  Returns a default input tag for the type of object returned by the method. Example 
     41     *  (title is a VARCHAR column and holds "Hello World"): 
     42     *   input("post", "title") => 
     43     *     <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> 
     44     */ 
    3345    function input($object_name, $attribute_name, $options = array()) { 
    3446        return $this->to_tag($object_name, $attribute_name, $options);         
    3547    } 
    3648     
     49    /** 
     50     * 
     51     */ 
    3752    function input_scaffolding($object_name, $attribute_name, $options = array()) { 
    3853        return $this->to_scaffold_tag($object_name, $attribute_name, $options);         
    3954    } 
    4055 
    41     # Returns an entire form with input tags and everything for a specified Active Record object. Example 
    42     # (post is a new record that has a title using VARCHAR and a body using TEXT): 
    43     #   form("post") => 
    44     #     <form action='/post/create' method='post'> 
    45     #       <p> 
    46     #         <label for="post_title">Title</label><br /> 
    47     #         <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> 
    48     #       </p> 
    49     #       <p> 
    50     #         <label for="post_body">Body</label><br /> 
    51     #         <textarea cols="40" id="post_body" name="post[body]" rows="20"> 
    52     #           Back to the hill and over it again! 
    53     #         </textarea> 
    54     #       </p> 
    55     #       <input type='submit' value='Create' /> 
    56     #     </form> 
    57     # 
    58     # It's possible to specialize the form builder by using a different action name and by supplying another 
    59     # block renderer. Example (entry is a new record that has a message attribute using VARCHAR): 
    60     # 
    61     #   form("entry", array('action' => "sign", 'input_block' =>  
    62     #        'foreach($record->content_columns() as $column_name => $column) $contents .= Inflector::humanize($column_name) . ": " . input($record, $column) . "<br />"')) => 
    63     # 
    64     #     <form action='/post/sign' method='post'> 
    65     #       Message: 
    66     #       <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /><br /> 
    67     #       <input type='submit' value='Sign' /> 
    68     #     </form> 
    69     # 
    70     # It's also possible to add additional content to the form by giving it a block, such as: 
    71     # 
    72     #   form("entry", array('action' => "sign", 'block' => 
    73     #     content_tag("b", "Department") . 
    74     #     collection_select("department", "id", $departments, "id", "name")) 
    75     #   ) 
     56    /** 
     57     * Returns an entire form with input tags and everything for a specified Active Record object. Example 
     58     * (post is a new record that has a title using VARCHAR and a body using TEXT): 
     59     *   form("post") => 
     60     *     <form action='/post/create' method='post'> 
     61     *       <p> 
     62     *         <label for="post_title">Title</label><br /> 
     63     *         <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> 
     64     *       </p> 
     65     *       <p> 
     66     *         <label for="post_body">Body</label><br /> 
     67     *         <textarea cols="40" id="post_body" name="post[body]" rows="20"> 
     68     *           Back to the hill and over it again! 
     69     *         </textarea> 
     70     *       </p> 
     71     *       <input type='submit' value='Create' /> 
     72     *     </form> 
     73     * 
     74     *  It's possible to specialize the form builder by using a different action name and by supplying another 
     75     *  block renderer. Example (entry is a new record that has a message attribute using VARCHAR): 
     76     * 
     77     *   form("entry", array('action' => "sign", 'input_block' =>  
     78     *        'foreach($record->content_columns() as $column_name => $column) $contents .= Inflector::humanize($column_name) . ": " . input($record, $column) . "<br />"')) => 
     79     * 
     80     *     <form action='/post/sign' method='post'> 
     81     *       Message: 
     82     *       <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /><br /> 
     83     *       <input type='submit' value='Sign' /> 
     84     *     </form> 
     85     * 
     86     *  It's also possible to add additional content to the form by giving it a block, such as: 
     87     * 
     88     *   form("entry", array('action' => "sign", 'block' => 
     89     *     content_tag("b", "Department") . 
     90     *     collection_select("department", "id", $departments, "id", "name")) 
     91     *   ) 
     92     */ 
    7693    function form($record_name, $options = array()) { 
    7794        $record = $this->object($record_name); 
    … …  
    89106    } 
    90107 
    91     /* # Returns a string containing the error message attached to the +method+ on the +object+, if one exists. 
    92     # This error message is wrapped in a DIV tag, which can be specialized to include both a +prepend_text+ and +append_text+ 
    93     # to properly introduce the error and a +css_class+ to style it accordingly. Examples (post has an error message 
    94     # "can't be empty" on the title attribute): 
    95     # 
    96     #   <?= error_message_on("post", "title") ?> => 
    97     #     <div class="formError">can't be empty</div> 
    98     # 
    99     #   <?= error_message_on "post", "title", "Title simply ", " (or it won't work)", "inputError" ?> => 
    100     #     <div class="inputError">Title simply can't be empty (or it won't work)</div> */ 
     108    /** 
     109     *  Returns a string containing the error message attached to the +method+ on the +object+, if one exists. 
     110     *  This error message is wrapped in a DIV tag, which can be specialized to include both a +prepend_text+ and +append_text+ 
     111     *  to properly introduce the error and a +css_class+ to style it accordingly. Examples (post has an error message 
     112     *  "can't be empty" on the title attribute): 
     113     * 
     114     *   <?= error_message_on("post", "title") ?> => 
     115     *     <div class="formError">can't be empty</div> 
     116     * 
     117     *   <?= error_message_on "post", "title", "Title simply ", " (or it won't work)", "inputError" ?> => 
     118     *     <div class="inputError">Title simply can't be empty (or it won't work)</div> 
     119     */ 
    101120    function error_message_on($object_name, $attribute_name, $prepend_text = "", $append_text = "", $css_class = "formError") { 
    102121        $this->object_name = $object_name; 
    … …  
    108127    } 
    109128 
    110     # Returns a string with a div containing all the error messages for the object located as an instance variable by the name 
    111     # of <tt>object_name</tt>. This div can be tailored by the following options: 
    112     # 
    113     # * <tt>header_tag</tt> - Used for the header of the error div (default: h2) 
    114     # * <tt>id</tt> - The id of the error div (default: errorExplanation) 
    115     # * <tt>class</tt> - The class of the error div (default: errorExplanation) 
     129    /** 
     130     *  Returns a string with a div containing all the error messages for the object located as an instance variable by the name 
     131     *  of <tt>object_name</tt>. This div can be tailored by the following options: 
     132     * 
     133     * <tt>header_tag</tt> - Used for the header of the error div (default: h2) 
     134     * <tt>id</tt> - The id of the error div (default: errorExplanation) 
     135     * <tt>class</tt> - The class of the error div (default: errorExplanation) 
     136     */ 
    116137    function error_messages_for($object_name, $options = array()) { 
    117138        if(is_object($object_name)) { 
    … …  
    136157    } 
    137158 
     159    /** 
     160     * 
     161     */ 
    138162    function all_input_tags($record, $record_name, $options) { 
    139163        //if($record_name) $this->object_name = $record_name; 
    … …  
    153177    } 
    154178 
     179    /** 
     180     * 
     181     */ 
    155182    function default_input_block() { 
    156183        if($this->scaffolding) { 
    … …  
    161188    } 
    162189     
     190    /** 
     191     * 
     192     */ 
    163193    function to_tag($object_name, $attribute_name, $options = array()) { 
    164194        $this->object_name = $object_name; 
    … …  
    200230    } 
    201231 
     232    /** 
     233     * 
     234     */ 
    202235    function to_scaffold_tag($object_name, $attribute_name, $options = array()) { 
    203236        $this->object_name = $object_name; 
    … …  
    237270    } 
    238271 
     272    /** 
     273     * 
     274     */ 
    239275    function object($object_name = null) { 
    240276        $object_name = $object_name ? $object_name : $this->object_name; 
    … …  
    244280    } 
    245281 
     282    /** 
     283     * 
     284     */ 
    246285    function tag_without_error_wrapping() { 
    247286        $args = func_get_args(); 
    … …  
    249288    } 
    250289 
     290    /** 
     291     * 
     292     */ 
    251293    function tag($name, $options = array()) { 
    252294        if(count($this->object()->errors)) { 
    … …  
    257299    } 
    258300 
     301    /** 
     302     * 
     303     */ 
    259304    function content_tag_without_error_wrapping() { 
    260305        $args = func_get_args(); 
    … …  
    262307    } 
    263308 
     309    /** 
     310     * 
     311     */ 
    264312    function content_tag($name, $value, $options = array()) { 
    265313        if (count($this->object()->errors)) { 
    … …  
    270318    } 
    271319 
     320    /** 
     321     * 
     322     */ 
    272323    function to_date_select_tag_without_error_wrapping() { 
    273324        $form = new DateHelper($this->object_name, $this->attribute_name); 
    … …  
    276327    } 
    277328 
     329    /** 
     330     * 
     331     */ 
    278332    function to_date_select_tag($options = array()) { 
    279333        if (count($this->object()->errors)) { 
    … …  
    284338    } 
    285339 
     340    /** 
     341     * 
     342     */ 
    286343    function to_datetime_select_tag_without_error_wrapping() { 
    287344        $form = new DateHelper($this->object_name, $this->attribute_name); 
    … …  
    290347    } 
    291348 
     349    /** 
     350     * 
     351     */ 
    292352    function to_datetime_select_tag($options = array()) { 
    293353        if (count($this->object()->errors)) { 
    … …  
    298358    } 
    299359 
     360    /** 
     361     * 
     362     */ 
    300363    function error_wrapping($html_tag, $has_error) { 
    301364        return ($has_error ? '<span class="fieldWithErrors">' . $html_tag . '</span>' : $html_tag); 
    302365    } 
    303366 
     367    /** 
     368     * 
     369     */ 
    304370    function error_message() { 
    305371        return $this->object()->errors[$this->attribute_name]; 
    306372    } 
    307373 
     374    /** 
     375     * 
     376     */ 
    308377    function column_type() { 
    309378        $column = $this->object()->column_for_attribute($this->attribute_name); 
    … …  
    313382} 
    314383 
    315 ################################################################################################ 
    316 ## Avialble functions for use in views 
    317 ################################################################################################ 
    318 # error_message_on($object, $attribute_name, $prepend_text = "", $append_text = "", $css_class = "formError") 
     384/** 
     385 * Avialble functions for use in views 
     386 * error_message_on($object, $attribute_name, $prepend_text = "", $append_text = "", $css_class = "formError") 
     387 */ 
    319388function error_message_on() { 
    320389    $ar_helper = new ActiveRecordHelper(); 
    … …  
    323392} 
    324393 
    325 # error_messages_for($object_name, $options = array()) 
     394/** 
     395 * error_messages_for($object_name, $options = array()) 
     396 */ 
    326397function error_messages_for() { 
    327398    $ar_helper = new ActiveRecordHelper(); 
    … …  
    330401} 
    331402 
    332 # form($record_name, $options = array()) 
     403/** 
     404 *  form($record_name, $options = array()) 
     405 */ 
    333406function form() { 
    334407    $ar_helper = new ActiveRecordHelper(); 
    … …  
    337410} 
    338411 
    339 # Returns a default input tag for the type of object returned by the method. Example 
    340 # (title is a VARCHAR column and holds "Hello World"): 
    341 #   input("post", "title") => 
    342 #     <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> 
     412/** 
     413 *  Returns a default input tag for the type of object returned by the method. Example 
     414 *  (title is a VARCHAR column and holds "Hello World"): 
     415 *   input("post", "title") => 
     416 *    <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> 
     417 */ 
    343418function input() { 
    344419    $ar_helper = new ActiveRecordHelper(); 
    … …  
    347422} 
    348423 
     424/** 
     425 * 
     426 */ 
    349427function input_scaffolding() { 
    350428    $ar_helper = new ActiveRecordHelper();