Show
Ignore:
Timestamp:
03/02/06 17:20:34 (6 years ago)
Author:
haas
Message:

Finish Router class doc, regression test

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/trax/tutorials/PHPonTrax/Router.cls

    r155 r161  
    22 <refnamediv> 
    33  <refname>Router</refname> 
    4   <refpurpose>@todo Router tutorial</refpurpose> 
     4  <refpurpose>Convert a URL to an action</refpurpose> 
    55 </refnamediv> 
    66 <refsynopsisdiv> 
    … …  
    1515 <refsect1 id="{@id intro}"> 
    1616  <title>Introduction</title> 
     17 
     18  <para>The {@link Router Router class} owns the information and 
     19   algorithms that convert URLs to actions.  An object of this class 
     20   holds a {@link Router::$routes route table} containing routes to be 
     21   matched to URLs.</para> 
     22 
     23  <para>In normal operation, a Router object is created by  
     24   {@link ActionController::load_router()} which reads routes from the 
     25   configuration file {@link routes.php config/routes.php}.</para> 
     26 
    1727 </refsect1> 
     28 <refsect1 id="{@id table}"> 
     29  <title>Structure of the Route Table</title> 
     30 
     31  <para>The route table is an ordered list of routes.  A route consists 
     32   of a path and a (possibly null) parameter array. The structure of 
     33   the table is:</para> 
     34 
     35  <example> 
     36$routes[0]['path']    First route path 
     37          ['params']  First route parameters 
     38       [1]['path']    Second route path 
     39          ['params']  Second route parameters 
     40... 
     41  </example> 
     42 
     43  <para>A route path consists of character strings separated by 
     44   forward slash ('/') characters.  The route path must not begin 
     45   or end with '/', and the character strings in the path must 
     46   not contain '/'.  There are two kinds of character strings in 
     47   route paths:</para> 
     48 
     49  <unorderedlist> 
     50   <listitem>Placeholder strings start with a colon (':') followed by 
     51    one or more alphameric characters chosen from "a..z0..9_-".  A 
     52    placeholder string matches any alphameric string in the same 
     53    position of a URL.  The actual contents of the placeholder string 
     54    following ':' are irrelevant.</listitem>  
     55   <listitem>Pattern strings start with any character except ':' or 
     56    '/' followed by any character except '/'.  The contents of 
     57    the pattern string are a 
     58    {@link http://www.php.net/manual/en/ref.pcre.php Perl regular expression}. 
     59   </listitem> 
     60  </unorderedlist> 
     61 
     62  <para>The order of routes in the table is significant.  When a URL 
     63   is to be matched, the route table is searched in order from first 
     64   entry to last.  The first route entry that matches is 
     65   returned.</para> 
     66 
     67  <para>{@link Router::find_route()} guarantees that there will always be 
     68   at least one route in the table by inserting 
     69   {@link Router::$default_route_path} if the table is empty when 
     70   find_route() is called.</para> 
     71 </refsect1> 
     72 
     73 <refsect1 id="{@id build}"> 
     74  <title>Constructing the Route Table</title> 
     75 
     76  <para>To construct a route table, first create a new Router object, 
     77   then  make multiple calls to {@link Router::connect()} to add route 
     78   entries to the object's table.  The second argument to connect(), if 
     79   specified, must be an array, but the array can hold anything (or 
     80   nothing).</para> 
     81 
     82  <para>There is no way to change or delete an existing route table 
     83   entry.</para> 
     84  <para>Either assure that any path you search for will return some 
     85  route, or prepare to deal with a null return from 
     86  {@link Router::find_route()} </para> 
     87 
     88  <para><important>CAUTION:</important> Do not call 
     89   {@link Router::find_route()} before calling 
     90   {@link Router::connect()}, unless you want the default route to be 
     91   the first entry in the route table.</para> 
     92 
     93 </refsect1> 
     94 <refsect1 id="{@id search}"> 
     95  <title>Searching the Route Table</title> 
     96 
     97  <para>To look up a URL in the route table, call 
     98   {@link Router::find_route()} with the URL as argument.  A copy of 
     99   the first matching route table entry, if any, will be returned.  If 
     100   none matches, null will be returned.</para> 
     101 
     102  <para>A URL consisting of a null string '' matches a route 
     103   whose path is a null string.</para> 
     104 
     105  <para>A copy of the last route table entry returned by find_route() 
     106   is saved in {@link Router::$selected_route}.  It can be fetched by 
     107   a call to {@link Router::get_selected_route()}.  The next call to 
     108   find_route() overwrites the previous value in 
     109   $selected_route.</para> 
     110 
     111 </refsect1> 
     112<!-- 
     113Local variables: 
     114mode: xml 
     115c-basic-offset: 1 
     116indent-tabs-mode: nil 
     117End: 
     118--> 
    18119</refentry>