[ Index ]
 

Code source de PHPonTrax 2.6.6-svn

Accédez au Source d'autres logiciels libresSoutenez Angelica Josefina !

title

Body

[fermer]

/doc/tutorials/PHPonTrax/ -> Router.cls (source)

   1  <refentry id="{@id}" revision="$Id: Router.cls 192 2006-03-27 22:02:53Z haas $">
   2   <refnamediv>
   3    <refname>Router</refname>
   4    <refpurpose>Convert a URL to an action</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  
  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  
  27   </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>Keyword strings start with a colon (':') followed by
  51      a keyword consisting of
  52      one or more alphameric characters chosen from "a..z0..9_-".  A
  53      keyword string matches any alphameric string in the same
  54      position of a URL.  The value of the keyword following ':' is
  55      irrelevant to Router, but certain keywords are meaninful to
  56      {@tutorial PHPonTrax/ActionController.cls}.</listitem>  
  57     <listitem>Pattern strings start with any character except ':' or
  58      '/' followed by any character except '/'.  The contents of
  59      the pattern string are a
  60      {@link http://www.php.net/manual/en/ref.pcre.php Perl regular expression}.
  61     </listitem>
  62    </unorderedlist>
  63  
  64    <para>The order of routes in the table is significant.  When a URL
  65     is to be matched, the route table is searched in order from first
  66     entry to last.  The first route entry that matches is
  67     returned.</para>
  68  
  69    <para>{@link Router::find_route()} guarantees that there will always be
  70     at least one route in the table by inserting
  71     {@link Router::$default_route_path} if the table is empty when
  72     find_route() is called.</para>
  73   </refsect1>
  74  
  75   <refsect1 id="{@id build}">
  76    <title>Constructing the Route Table</title>
  77  
  78    <para>To construct a route table, first create a new Router object,
  79     then  make multiple calls to {@link Router::connect()} to add route
  80     entries to the object's table.  The second argument to connect(), if
  81     specified, must be an array, but the array can hold anything (or
  82     nothing).</para>
  83  
  84    <para>There is no way to change or delete an existing route table
  85     entry.</para>
  86    <para>Either assure that any path you search for will return some
  87    route, or prepare to deal with a null return from
  88    {@link Router::find_route()} </para>
  89  
  90    <para><important>CAUTION:</important> Do not call
  91     {@link Router::find_route()} before calling
  92     {@link Router::connect()}, unless you want the default route to be
  93     the first entry in the route table.</para>
  94  
  95   </refsect1>
  96   <refsect1 id="{@id search}">
  97    <title>Searching the Route Table</title>
  98  
  99    <para>To look up a URL in the route table, call
 100     {@link Router::find_route()} with the URL as argument.  A copy of
 101     the first matching route table entry, if any, will be returned.  If
 102     none matches, null will be returned.</para>
 103  
 104    <para>A URL consisting of a null string '' matches a route
 105     whose path is a null string.</para>
 106  
 107    <para>A copy of the last route table entry returned by find_route()
 108     is saved in {@link Router::$selected_route}.  It can be fetched by
 109     a call to {@link Router::get_selected_route()}.  The next call to
 110     find_route() overwrites the previous value in
 111     $selected_route.</para>
 112  
 113   </refsect1>
 114  <!--
 115  Local variables:
 116  mode: xml
 117  c-basic-offset: 1
 118  indent-tabs-mode: nil
 119  End:
 120  -->
 121  </refentry>


Généré le : Sun Feb 25 20:04:38 2007 par Balluche grâce à PHPXref 0.7