Changeset 199 for trunk/trax/vendor/trax/action_view

Timestamp:

05/04/06 19:52:43 (6 years ago)

Author:

haas

Message:

many fixes, documentation improvements

Location:

trunk/trax/vendor/trax/action_view

Files:

• helpers.php (modified) (1 prop)
• helpers/active_record_helper.php (modified) (1 diff, 1 prop)
• helpers/asset_tag_helper.php (modified) (13 diffs, 1 prop)
• helpers/date_helper.php (modified) (7 diffs, 1 prop)
• helpers/form_helper.php (modified) (1 prop)
• helpers/form_options_helper.php (modified) (1 prop)
• helpers/form_tag_helper.php (modified) (1 prop)
• helpers/javascript_helper.php (modified) (1 prop)
• helpers/url_helper.php (modified) (14 diffs, 1 prop)

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

@@ -204 +204 @@
      *  @todo Document this method
      *  @uses scaffolding
+     *  @uses input_scaffolding()
      */
     function default_input_block() {

trunk/trax/vendor/trax/action_view/helpers/asset_tag_helper.php

@@ -30 +30 @@
 
 /**
- *  @todo Document this class
+ *  Utility to help build HTML/XML link tags for public assets
  */
 class AssetTagHelper extends Helpers {
 
     /**
+     *  @var string[]
+     */
+    var $javascript_default_sources = null;
+
+    /**
      *  @todo Document this method
      *
+     *  @uses javascript_default_sources
      */
     function __construct() {
         parent::__construct();
-        $this->javascript_default_sources = $GLOBALS['JAVASCRIPT_DEFAULT_SOURCES'] ? $GLOBALS['JAVASCRIPT_DEFAULT_SOURCES'] : array('prototype', 'effects', 'dragdrop', 'controls');    
-    }
-    
-    /**
-     *   @todo Document this method
-     *
+        $this->javascript_default_sources =
+            array_key_exists('JAVASCRIPT_DEFAULT_SOURCES',$GLOBALS)
+            ? $GLOBALS['JAVASCRIPT_DEFAULT_SOURCES']
+            : array('prototype', 'effects', 'dragdrop', 'controls');    
+    }
+    
+    /**
+     *  Compute public path to an asset
+     *
+     *  Build the public path, suitable for inclusion in a URL, to an
+     *  asset.  Arguments are the filename, directory and extension of
+     *  the asset.
+     *  @param string  Filename of asset
+     *  @param string  Default directory name, if none in $source
+     *  @param string  Default file extension, if none in $source
+     *  @return string Public path to the asset
+     *  @uses controller_object
+     *  @uses ActionController::asset_host
      */
     private function compute_public_path($source, $dir, $ext) {
+ 
+        //  Test whether source is a URL, ie. starts something://
         if(!preg_match('/^[-a-z]+:\/\//', $source)) {
+
+            //  Source is not a URL.
+            //  If path doesn't start with '/', prefix /$dir/
             if($source{0} != '/') {
                 $source = "/{$dir}/{$source}";
             }
+
+            //  If no '.' in source file name, add '.ext'
             if(!strstr($source, '.')) {
                 $source = "{$source}.{$ext}";
             }
+
+            //  If TRAX_URL_PREFIX non-null, prefix it to path
             if(!is_null(TRAX_URL_PREFIX)) {
                 $prefix = TRAX_URL_PREFIX;
@@ -60 +87 @@
                     $prefix = "/$prefix";
                 }
-                $source = $prefix . ((substr($prefix, -1) == "/") ? substr($source, 1) : $source);
+                $source = $prefix . ((substr($prefix, -1) == "/")
+                                     ? substr($source, 1) : $source);
             }            
         }
-        return $this->controller_object->asset_host . $source;
-    }
-    
-    /**
-     * Returns path to a javascript asset. Example:
-     *
-     *  javascript_path "xmlhr" # => /javascripts/xmlhr.js
+
+        //  If controller defined and has asset_host value
+        //  prefix that to path
+        //  FIXME: won't this cause a problem if $source was http://...?
+        if ( isset($this->controller_object)
+             && isset($this->controller_object->asset_host) ) {
+            $source = $this->controller_object->asset_host . $source;
+        }
+        return $source;
+    }
+    
+    /**
+     *  Compute public path to a javascript asset
+     *
+     *  Build the public path, suitable for inclusion in a URL, to a
+     *  javascript asset.  Argument is the filename of the asset.
+     *  Default directory to 'javascripts', extension to '.js'
+     *  @param string  Filename of asset, in one of the formats
+     *                 accepted as the $filename argument of
+     *                 {@link compute_public_path()}
+     *  @return string Public path to the javascript asset
+     *  @uses compute_public_path()
      */
     function javascript_path($source) {
@@ -76 +119 @@
     
     /**
-     * Returns a script include tag per source given as argument. Examples:
-     *
-     *  javascript_include_tag("xmlhr") # =>
+     *  Return script include tag for one or more javascript assets
+     *
+     *  javascript_include_tag("xmlhr"); =>
      *   <script type="text/javascript" src="/javascripts/xmlhr.js"></script>
      *
-     *  javascript_include_tag("common.javascript", "/elsewhere/cools") # =>
+     *  javascript_include_tag("common.javascript", "/elsewhere/cools"); =>
      *   <script type="text/javascript" src="/javascripts/common.javascript"></script>
      *   <script type="text/javascript" src="/elsewhere/cools.js"></script>
      *
-     *  javascript_include_tag("defaults") # =>
+     *  javascript_include_tag("defaults"); =>
      *   <script type="text/javascript" src="/javascripts/prototype.js"></script>
      *   <script type="text/javascript" src="/javascripts/effects.js"></script>
      *   <script type="text/javascript" src="/javascripts/controls.js"></script>
      *   <script type="text/javascript" src="/javascripts/dragdrop.js"></script>   
+     *  @param mixed  The arguments are zero or more strings, followed
+     *                by an optional array containing options
+     *  @return string
+     *  @uses content_tag()
+     *  @uses javascript_default_sources
+     *  @uses javascript_path()
      */
     function javascript_include_tag() {
         if(func_num_args() > 0) {
             $sources = func_get_args();     
-            $options = (is_array(end($sources)) ? array_pop($sources) : array());          
+            $options = (is_array(end($sources))
+                        ? array_pop($sources) : array());          
             if(in_array('defaults', $sources)) {
                 if(is_array($this->javascript_default_sources)) {
-                    $sources = array_merge($this->javascript_default_sources, $sources);    
+                    $sources = array_merge($this->javascript_default_sources,
+                                           $sources);    
                 }                  
                 if(file_exists(TRAX_PUBLIC. "/javascripts/application.js")) {
@@ -108 +159 @@
             foreach($sources as $source) {
                 $source = $this->javascript_path($source);
-                $contents[] = $this->content_tag("script", "", array_merge(array("type" => "text/javascript", "src" => $source), $options));
+                $contents[] = $this->content_tag("script", "",
+                     array_merge(array("type" => "text/javascript",
+                                       "src" => $source), $options));
             }
             return implode("", $contents);
@@ -115 +168 @@
     
     /**
-     * Returns path to a stylesheet asset. Example:
-     *
-     *  stylesheet_path("style") # => /stylesheets/style.css
+     *  Compute public path to a stylesheet asset
+     *
+     *  Build the public path, suitable for inclusion in a URL, to a
+     *  stylesheet asset.  Argument is the filename of the asset.
+     *  Default directory to 'stylesheets', extension to '.css'
+     *  @param string  Filename of asset, in one of the formats
+     *                 accepted as the $filename argument of
+     *                 {@link compute_public_path()}
+     *  @return string Public path to the stylesheet asset
      *  @uses compute_public_path()
      */
     function stylesheet_path($source) {
-        return $this->compute_public_path($source, 'stylesheets', 'css'); #should be stylesheets
-    }
-    
-    /**
-     * Returns a css link tag per source given as argument. 
-     *
-     * Examples:
-     *
-     *  stylesheet_link_tag("style") # =>
-     *   <link href="/stylesheets/style.css" media="screen" rel="Stylesheet" type="text/css" />
-     *
-     *  stylesheet_link_tag("style", array("media" => "all")) # =>
-     *   <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css" />
-     *
-     *  stylesheet_link_tag("random.styles", "/css/stylish") # =>
-     *   <link href="/stylesheets/random.styles" media="screen" rel="Stylesheet" type="text/css" />
-     *   <link href="/css/stylish.css" media="screen" rel="Stylesheet" type="text/css" />
+        return $this->compute_public_path($source, 'stylesheets', 'css');
+    }
+    
+    /**
+     *  Build link tags to one or more stylesheet assets
+     *
+     *  @param mixed  One or more assets, optionally followed by an
+     *                array describing options to apply to the tags
+     *                generated for these assets.<br>  Each asset is a
+     *                string in one of the formats accepted as value
+     *                of the $source argument of
+     *                {@link stylesheet_path()}.<br>  The optional last
+     *                argument is an array whose keys are names of
+     *                attributes of the link tag and whose corresponding
+     *                values are the values assigned to each
+     *                attribute.  If omitted, options default to:
+     *                <ul>
+     *                  <li>"rel" => "Stylesheet"</li>
+     *                  <li>"type" => "text/css"</li>
+     *                  <li>"media" => "screen"</li>
+     *                  <li>"href" => <i>path-to-source</i></li>
+     *                </ul>
+     *  @return string  A link tag for each asset in the argument list
      *  @uses stylesheet_path()
      *  @uses tag()
@@ -144 +209 @@
         if(func_num_args() > 0) {
             $sources = func_get_args();     
-            $options = (is_array(end($sources)) ? array_pop($sources) : array());
+            $options = (is_array(end($sources))
+                        ? array_pop($sources) : array());
             $contents = array();
             foreach($sources as $source) {
                 $source = $this->stylesheet_path($source);
-                $contents[] = $this->tag("link", array_merge(array("rel" => "Stylesheet", "type" => "text/css", "media" => "screen", "href" => $source), $options));
+                $contents[] = $this->tag("link",
+                   array_merge(array("rel" => "Stylesheet",
+                                     "type" => "text/css",
+                                     "media" => "screen",
+                                     "href" => $source), $options));
             }
             return implode("", $contents);
@@ -155 +225 @@
     
     /**
-     * Returns path to an image asset. Example:
-     *
-     * The src can be supplied as a...
-     * * full path, like "/my_images/image.gif"
-     * * file name, like "rss.gif", that gets expanded to "/images/rss.gif"
-     * * file name without extension, like "logo", that gets expanded to "/images/logo.png"
-     *  @uses compute_public_path
+     *  Compute public path to a image asset
+     *
+     *  Build the public path, suitable for inclusion in a URL, to a
+     *  image asset.  Argument is the filename of the asset.
+     *  Default directory to 'images', extension to '.png'
+     *  @param string  Filename of asset, in one of the formats
+     *                 accepted as the $filename argument of
+     *                 {@link compute_public_path()}
+     *  @return string Public path to the image asset
+     *  @uses compute_public_path()
      */
     function image_path($source) {
-        return $this->compute_public_path($source, 'images', 'png'); #should be images
-    }
-    
-    /**
-     * Returns an image tag converting the $options instead html options on the tag, but with these special cases:
-     *
-     * * <tt>:alt</tt> - If no alt text is given, the file name part of the src is used (capitalized and without the extension)
-     * * <tt>:size</tt> - Supplied as "XxY", so "30x45" becomes width="30" and height="45"
-     *
-     * The src can be supplied as a...
-     * * full path, like "/my_images/image.gif"
-     * * file name, like "rss.gif", that gets expanded to "/images/rss.gif"
-     * * file name without extension, like "logo", that gets expanded to "/images/logo.png"
-     *  @uses Inflector::capitalize()
+        return $this->compute_public_path($source, 'images', 'png');
+    }
+    
+    /**
+     *  Build image tags to an image asset
+     *
+     *  @param mixed  An image asset optionally followed by an
+     *                array describing options to apply to the tag
+     *                generated for this asset.<br>The asset is a
+     *                string in one of the formats accepted as value
+     *                of the $source argument of
+     *                {@link image_path()}.<br>  The optional second
+     *                argument is an array whose keys are names of
+     *                attributes of the image tag and whose corresponding
+     *                values are the values assigned to each
+     *                attribute.  The image size can be specified in
+     *                two ways: by specifying option values "width" =>
+     *                <i>width</i> and "height" => <i>height</i>, or
+     *                by specifying option "size" => "<i>width</i>
+     *                x <i>height</i>".  If omitted, options default to:
+     *                <ul>
+     *                  <li>"alt" => <i>humanized filename</i></li>
+     *                  <li>"width" and "height" value computed from
+     *                       value of "size"</li>
+     *                </ul>
+     *  @return string  A image tag for each asset in the argument list
      *  @uses image_path()
      *  @uses tag()
@@ -183 +268 @@
     function image_tag($source, $options = array()) {
         $options['src'] = $this->image_path($source);
-        $options['alt'] = $options['alt'] ? $options['alt'] : Inflector::capitalize(reset($file_array = explode('.', basename($options['src']))));
-        
+        $options['alt'] = array_key_exists('alt',$options)
+            ? $options['alt']
+            : Inflector::capitalize(reset($file_array =
+                             explode('.', basename($options['src']))));
         if(isset($options['size'])) {
             $size = explode('x', $options["size"]);         
@@ -191 +278 @@
             unset($options['size']);
         }
-        
         return $this->tag("img", $options);
     }
     
     /**
-     * Returns a link tag that browsers and news readers can use to auto-detect a RSS or ATOM feed for this page. The $type can
-     * either be <tt>:rss</tt> (default) or <tt>:atom</tt> and the $options follow the url_for() style of declaring a link target.
-     *
-     * Examples:
-     *  auto_discovery_link_tag # =>
-     *   <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.curenthost.com/controller/action" />
-     *  auto_discovery_link_tag(:atom) # =>
-     *   <link rel="alternate" type="application/atom+xml" title="ATOM" href="http://www.curenthost.com/controller/action" />
-     *  auto_discovery_link_tag(:rss, {:action => "feed"}) # =>
-     *   <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.curenthost.com/controller/feed" />
-     *  auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "My RSS"}) # =>
-     *   <link rel="alternate" type="application/rss+xml" title="My RSS" href="http://www.curenthost.com/controller/feed" />
-        *  @uses tag()
-     */
-    function auto_discovery_link_tag($type = 'rss', $options = array(), $tag_options = array()) {
+     *  Returns a link tag that browsers and news readers can use to
+     *  auto-detect a RSS or ATOM feed for this page. The $type can 
+     *  either be <tt>:rss</tt> (default) or <tt>:atom</tt> and the
+     *  $options follow the url_for() style of declaring a link
+     *  target. 
+     *
+     *  Examples:
+     *  auto_discovery_link_tag  =>
+     *   <link rel="alternate" type="application/rss+xml" title="RSS"
+     *  href="http://www.curenthost.com/controller/action" /> 
+     *  auto_discovery_link_tag(:atom) =>
+     *   <link rel="alternate" type="application/atom+xml"
+     *  title="ATOM"
+     *  href="http://www.curenthost.com/controller/action" /> 
+     *  auto_discovery_link_tag(:rss, {:action => "feed"}) =>
+     *   <link rel="alternate" type="application/rss+xml" title="RSS"
+     *  href="http://www.curenthost.com/controller/feed" /> 
+     *  auto_discovery_link_tag(:rss, {:action => "feed"}, {:title =>
+     *  "My RSS"})  => 
+     *   <link rel="alternate" type="application/rss+xml" title="My
+     *  RSS" href="http://www.curenthost.com/controller/feed" /> 
+     *  @uses tag()
+     *  @uses url_for()
+     */
+    function auto_discovery_link_tag($type = 'rss', $options = array(),
+                                     $tag_options = array()) {
         return $this->tag(
           "link", array(
-          "rel" => ($tag_options['rel'] ? $tag_options['rel'] : "alternate"),
-          "type" => ($tag_options['type'] ? $tag_options['type'] : "application/{$type}+xml"),
-          "title" => ($tag_options['title'] ? $tag_options['title'] : strtoupper($type)),
-          "href" => url_for(array_merge($options, array('only_path' => false))))
-        );
+                        "rel" => (array_key_exists('rel',$tag_options)
+                                  ? $tag_options['rel'] : "alternate"),
+                        "type" => (array_key_exists('type',$tag_options)
+                                   ? $tag_options['type']
+                                   : "application/{$type}+xml"),
+                        "title" => (array_key_exists('title',$tag_options)
+                                    ? $tag_options['title']
+                                    : strtoupper($type)),
+                        "href" => url_for(array_merge($options,
+                                         array('only_path' => false))))
+          );
     }    
 }
 
-
-/**
- *  @todo Document this method  
- *  Avialble functions for use in views
- *  auto_discovery_link_tag($type = 'rss', $options = array(), $tag_options = array())
+/**
+ *  Make a new AssetTagHelper object and call its auto_discovery_link_tag() method
  *  @uses AssetTagHelper::auto_discovery_link_tag()
  */
@@ -231 +331 @@
     $asset_helper = new AssetTagHelper();
     $args = func_get_args();
-    return call_user_func_array(array($asset_helper, 'auto_discovery_link_tag'), $args);
-}
-
-/**
- *  @todo Document this method  
- *  image_tag($source, $options = array())
+    return call_user_func_array(array($asset_helper,
+                                      'auto_discovery_link_tag'), $args);
+}
+
+/**
+ *  Make a new AssetTagHelper object and call its image_tag() method
  *  @uses AssetTagHelper::image_tag()
  */
@@ -246 +346 @@
 
 /**
- *  @todo Document this method  
- *  stylesheet_link_tag($sources)
+ *  Make a new AssetTagHelper object and call its stylesheet_link_tag() method
  *  @uses AssetTagHelper::stylesheet_link_tag()
  */
@@ -253 +352 @@
     $asset_helper = new AssetTagHelper();
     $args = func_get_args();
-    return call_user_func_array(array($asset_helper, 'stylesheet_link_tag'), $args);
-}
-
-/**
- *  @todo Document this method
- *  javascript_include_tag($sources)
+    return call_user_func_array(array($asset_helper,
+                                      'stylesheet_link_tag'), $args);
+}
+
+/**
+ *  Make a new AssetTagHelper object and call its javascript_include_tag() method
  *  @uses AssetTagHelper::javascript_include_tag()
  */
@@ -264 +363 @@
     $asset_helper = new AssetTagHelper();
     $args = func_get_args();
-    return call_user_func_array(array($asset_helper, 'javascript_include_tag'), $args);
+    return call_user_func_array(array($asset_helper,
+                                      'javascript_include_tag'), $args);
 }
 

trunk/trax/vendor/trax/action_view/helpers/date_helper.php

@@ -343 +343 @@
      *  @param mixed[]  Output format options:
      *  <ul>
-     *    <li><samp>'field_seperator' => '</samp><i>somestring</i><samp>'</samp><br />
+     *    <li><samp>'field_separator' => '</samp><i>somestring</i><samp>'</samp><br />
      *      String to insert between the month and year selectors.  If
      *      none is specified, default value is <samp>' / '</samp></li>
@@ -372 +372 @@
         $options['start_year'] = date("Y");
         $options['end_year'] = date("Y") + 7;
-        $options['field_seperator'] = " / ";        
+        $options['field_separator'] = " / ";        
 
         //  Find name and initial value of year field,
@@ -396 +396 @@
         //  Output month and year selectors in desired order
         if($options['month_before_year']) {
-            $select_html =  $month_select . $options['field_seperator']
+            $select_html =  $month_select . $options['field_separator']
                 .  $year_select;     
         } else {
-            $select_html =  $year_select . $options['field_seperator']
+            $select_html =  $year_select . $options['field_separator']
                 .  $month_select;
         }
@@ -1143 +1143 @@
      *    <li><samp>'discard_year' => true</samp> Don't show a year
      *      menu.  If absent or false, year menu will be output.</li>
-     *    <li><samp>'field_seperator' => '</samp><i>string</i><samp>'</samp>
+     *    <li><samp>'field_separator' => '</samp><i>string</i><samp>'</samp>
      *      String to insert between the submenus in the output.  If
      *      absent, one blank will be inserted.</li> 
@@ -1171 +1171 @@
 //                  . " attribute='$this->attribute_name'");
 //        error_log("options=".var_export($options,true));
+
+        //  Handle historically misspelled options
+        if (array_key_exists('field_seperator', $options)) {
+            $options['field_separator'] = $options['field_seperator'];
+            unset($options['field_seperator']);
+        }
         $defaults = array('discard_type' => true);
         $options  = array_merge($defaults, $options);
@@ -1241 +1247 @@
         //  (default blank)
         if(count($date_select)) {
-            $seperator = array_key_exists('field_seperator',$options)
-                ? $options['field_seperator'] : " ";
-            $date_select = implode($seperator, $date_select);            
+            $separator = array_key_exists('field_separator',$options)
+                ? $options['field_separator'] : " ";
+            $date_select = implode($separator, $date_select);            
         }
 
@@ -1392 +1398 @@
         $options['start_year'] = date("Y");
         $options['end_year'] = date("Y") + 7;
-        $options['field_seperator'] = " / ";
+        $options['field_separator'] = " / ";
         return $this->to_date_select_tag($options);               
     }  

trunk/trax/vendor/trax/action_view/helpers/url_helper.php

@@ -31 +31 @@
 /**
  *  @todo Document this class
- *  @package PHPonTrax
  */
 class UrlHelper extends Helpers {
 
     /**
-     * Creates a link tag of the given +name+ using an URL created by the set of +options+.
-     * It's also possible to pass a string instead of an options hash to
-     * get a link tag that just points without consideration. If null is passed as a name, the link itself will become the name.
-     * The $html_options have a special feature for creating javascript confirm alerts where if you pass ":confirm" => 'Are you sure?',
-     * the link will be guarded with a JS popup asking that question. If the user accepts, the link is processed, otherwise not.
+     * Creates a link tag of the given +name+ using an URL created by
+     * the set of +options+. 
+     * It's also possible to pass a string instead of an options hash
+     * to get a link tag that just points without consideration. If
+     * null is passed as a name, the link itself will become the
+     * name. 
+     * The $html_options have a special feature for creating
+     * javascript confirm alerts where if you pass ":confirm" => 'Are
+     * you sure?', 
+     * the link will be guarded with a JS popup asking that
+     * question. If the user accepts, the link is processed, otherwise
+     * not. 
      *
      * Example:
-     *   link_to("Delete this page", array(":action" => "delete", ":id" => $page->id), array(":confirm" => "Are you sure?"))
+     *   link_to("Delete this page", array(":action" => "delete",
+     * ":id" => $page->id), array(":confirm" => "Are you sure?")) 
+     *  @return string
+     *  @uses content_tag()
+     *  @uses convert_confirm_option_to_javascript()
+     *  @uses url_for()
      */
     function link_to($name, $options = array(), $html_options = array()) {
-        $html_options = $this->convert_confirm_option_to_javascript($html_options);
+        $html_options =
+            $this->convert_confirm_option_to_javascript($html_options);
         if(is_string($options)) {
             $href = array("href" => $options);
@@ -90 +102 @@
     /**
      *  @todo Document this method
+     *  @param mixed[]
+     *  @param mixed[]
+     *  @return mixed[]
      */
     function convert_boolean_attributes(&$html_options, $bool_attrs) {
@@ -102 +117 @@
     /**
      *  @todo Document this method
+     *  @param string
+     *  @param mixed[]
+     *  @param mixed[]
+     *  @return string
+     *  @uses convert_boolean_attributes()
+     *  @uses convert_confirm_option_to_javascript()
+     *  @uses url_for()
      */
     function button_to($name, $options = array(), $html_options = null) {
@@ -115 +137 @@
         }
 
-        $html_options = array_merge($html_options, array("type" => "submit", "value" => $name));
-        return "<form method=\"post\" action=\"" .  htmlspecialchars($url) . "\" class=\"button-to\"><div>" .
-            $this->tag("input", $html_options) . "</div></form>";
-    }
-
-    /**
-     * This tag is deprecated. Combine the link_to and AssetTagHelper::image_tag yourself instead, like:
-     *   link_to(image_tag("rss", array("size" => "30x45"), array("border" => 0)), "http://www.example.com")
-     */
-    function link_image_to($src, $options = array(), $html_options = array()) {
+        $html_options = array_merge($html_options,
+                              array("type" => "submit", "value" => $name));
+        return "<form method=\"post\" action=\"" .  htmlspecialchars($url)
+            . "\" class=\"button-to\"><div>"
+            . $this->tag("input", $html_options) . "</div></form>";
+    }
+
+    /**
+     * This tag is deprecated. Combine the link_to and
+     * AssetTagHelper::image_tag yourself instead, like: 
+     *   link_to(image_tag("rss", array("size" => "30x45"),
+     * array("border" => 0)), "http://www.example.com") 
+     *  @todo Document this method
+     */
+    function link_image_to($src, $options = array(),
+                           $html_options = array()) { 
         $image_options = array("src" => (ereg("/", $src) ? $src : "/images/$src"));
         if (!ereg(".", $image_options["src"])) $image_options["src"] .= ".png";
@@ -155 +183 @@
 
     /**
-     *  Return the URL for the set of $options provided.
+     *  Generate URL based on current URL and optional arguments
+     *
+     *  Output a URL with controller and optional action and id.
+     *  The output URL has the same method, host and
+     *  <samp>TRAX_URL_PREFIX</samp> as 
+     *  the current URL.  Controller is either the current controller
+     *  or a controller specified in $options.  Action and ID are
+     *  optionally specified in $options, or omitted.  The
+     *  <samp>':id'</samp> option will be ignored if the <samp>':action'</samp>
+     *  option is omitted.
+     *  @param mixed[]
+     *  <ul>
+     *    <li><b>string:</b><br />
+     *      The string value is returned immediately with no
+     *      substitutions.</li>
+     *    <li><b>array:</b>
+     *     <ul>
+     *       <li><samp>':controller'=></samp><i>controller value</i></li>
+     *       <li><samp>':action'=></samp><i>action value</i></li>
+     *       <li><samp>':id'=></samp><i>id value</i></li>
+     *     </ul>
+     *  </ul>
+     *  @return string
+     *  @uses controller_path
      */
     function url_for($options = array()) {
@@ -162 +213 @@
         $extra_params = array();
         if(is_string($options)) {
-            //$url[] = $options;
+
+            //  Argument is a string, just return it
             return $options;
+
         } elseif(is_array($options)) {
+
+            //  Argument is a (possibly empty) array
+            //  Start forming URL with this host
             $url_base = $_SERVER['HTTP_HOST'];
             if(substr($url_base, -1) == "/") {
                 # remove the ending slash
-                $url_base = substr($url_base, 0, -1);                             
+                $url_base = substr($url_base, 0, -1);
             }           
-            
+
+            //  Method is same as was used by the current URL
             if($_SERVER['SERVER_PORT'] == 443) {
                 $url_base = "https://".$url_base;
@@ -176 +233 @@
                 $url_base = "http://".$url_base;
             }
+            //  Insert value of TRAX_URL_PREFIX (must start with /)
             if(!is_null(TRAX_URL_PREFIX)) {
-                $url_base .= "/".TRAX_URL_PREFIX;
+                $url_base .= TRAX_URL_PREFIX;
             }
             
+            //  Get controller from $options or $controller_path
             if(array_key_exists(":controller", $options)) {
                 if($controller = $options[":controller"]) {
@@ -192 +251 @@
                 $url[] = $controller;
             }
-            
+
+            //  If controller found, get action from $options
             if(count($url)) {
                 if(array_key_exists(":action", $options)) {
@@ -200 +260 @@
                 } 
             }
+
+            //  If controller and action found, get id from $actions
             if(count($url) > 1) {
                 if(array_key_exists(":id", $options)) {
@@ -226 +288 @@
             $url_base .= "/";    
         } 
-        return $url_base . implode("/", $url) . (count($extra_params) ? "?".http_build_query($extra_params) : null);
+        return $url_base . implode("/", $url)
+            . (count($extra_params)
+               ? "?".http_build_query($extra_params) : null);
     }    
 
@@ -232 +296 @@
 
 /**
- *  Avialble functions for use in views
- *  @todo Document this function
+ *  Make a new UrlHelper object and call its link_to() method
+ *  @uses UrlHelper::link_to()
  */
 function link_to($name, $options = array(), $html_options = array()) {
@@ -240 +304 @@
 }
 
+/**
+ *  Make a new UrlHelper object and call its link_image_to() method
+ *  @uses UrlHelper::link_image_to()
+ */
 function link_image_to($src, $options = array(), $html_options = array()) {
     $url_helper = new UrlHelper();
@@ -245 +313 @@
 }
 
+/**
+ *  Make a new UrlHelper object and call its button_to() method
+ *  @uses UrlHelper::button_to()
+ */
 function button_to($name, $options = array(), $html_options = null) {
     $url_helper = new UrlHelper();
@@ -250 +322 @@
 }
 
+/**
+ *  Make a new UrlHelper object and call its url_for() method
+ *  @uses UrlHelper::url_for()
+ */
 function url_for($options = array()) {
     $url_helper = new UrlHelper();