[Sommaire] [Imprimer]

   1  <com:TContent ID="body" >
   2  
   3  <h1 id="2101">URL Mapping (Friendly URLs)</h1>
   4  
   5  <com:DocLink ClassPath="System.Web.TUrlMapping" />
   6  
   7  <p>Using the <tt>TUrlMapping</tt> module different URLs can be
   8  mapped into any existing Prado pages or services. This allows
   9  the application to use nice looking and friendly URLs.
  10  </p>
  11  
  12  <p>
  13  The <tt>TUrlMapping</tt> module allows aributary URL path to be mapped to a
  14  particular service and page class. This module must be configured
  15  before a service is initialized, thus this module should be configured
  16  globally in the <a href="?page=Configurations.AppConfig">application configuration</a>
  17  file and before any services.
  18  </p>
  19  
  20  <div class="info"><b class="tip">Info:</b>
  21  The <tt>TUrlMapping</tt> must be configured before the
  22  <a href="?page=Fundamentals.Modules">Request module</a> resolves the request.
  23  This usually means delcaring the <tt>TUrlMapping</tt> module before any
  24  <tt>&lt;services&gt;</tt> tag in the  <a href="?page=Configurations.AppConfig">application configuration</a>.
  25  Specifying the mappings in the per directory <tt>config.xml</tt> is not supported.
  26  </div>
  27  
  28  <p>
  29  To use <tt>TUrlMapping</tt>, one must set the <tt>UrlManager</tt> property of the <tt>THttpRequest</tt> module as the <tt>TUrlMapping</tt> module ID. See following for an example,
  30  <com:TTextHighlighter Language="xml" CssClass="source">
  31  <modules>
  32      <module id="request" class="THttpRequest" UrlManager="friendly-url" />
  33      <module id="friendly-url" class="System.Web.TUrlMapping">
  34          <url ServiceParameter="Posts.ViewPost" pattern="post/{id}/?" parameters.id="\d+" />
  35          <url ServiceParameter="Posts.ListPost" pattern="archive/{time}/?" parameters.time="\d{6}" />
  36          <url ServiceParameter="Posts.ListPost" pattern="category/{cat}/?" parameters.cat="\d+" />
  37      </module>
  38  </modules>
  39  </com:TTextHighlighter>
  40  </p>
  41  
  42  <p>
  43  The above example is part of the application configuration of the <tt>blog</tt> demo in the PRADO release. It enables recognition of the following URL formats:
  44  </p>
  45  <ul>
  46    <li><tt>/index.php/post/123</tt> is recognized as <tt>/index.php?page=Posts.ViewPost&id=123</tt></li>
  47    <li><tt>/index.php/archive/200605</tt> is recognized as <tt>/index.php?page=Posts.ListPost&time=200605</tt></li>
  48    <li><tt>/index.php/category/2</tt> is recognized as <tt>/index.php?page=Posts.ListPost&cat=2</tt></li>
  49  </ul>
  50  
  51  <p>
  52  The <tt>ServiceParameter</tt> and <tt>ServiceID</tt> (the default ID is 'page') set the service parameter and service ID, respectively, of the <a href="?page=Fundamentals.Modules">Request module</a>. The service parameter for the <tt>TPageService</tt> service is the Page class name, e.g., for an URL "index.php?page=Home", "page" is the service ID and the service parameter is "Home". Other services may use the service parameter and ID differently. See <a href="?page=Fundamentals.Services">Services</a> for further details.
  53  </p>
  54  
  55  <h2 id="21001">Specifying URL Patterns</h2>
  56  <p>
  57  <tt>TUrlMapping</tt> enables recognition of customized URL formats based on a list prespecified of URL patterns. Each pattern is specified in a <tt>&lt;url&gt;</tt> tag.
  58  </p>
  59  
  60  <p>
  61  The <tt>Pattern</tt> and <tt>Parameters</tt> attribute
  62  values are regular expression patterns that
  63  determine the mapping criteria. The <tt>Pattern</tt> property takes
  64  a regular expression with parameter names enclosed between a left brace '<tt>{</tt>'
  65  and a right brace '<tt>}</tt>'. The pattens for each parameter can be set
  66  using <tt>Parameters</tt>attribute collection.
  67  For example,
  68  <com:TTextHighlighter Language="xml" CssClass="source">
  69  <url ServiceParameter="ArticleView" pattern="articles/{year}/{month}/{day}"
  70       parameters.year="\d{4}" parameters.month="\d{2}" parameters.day="\d+" />
  71  </com:TTextHighlighter>
  72  </p>
  73  The example is equivalent to the following regular expression (it uses the "named group" feature in regular expressions available in PHP):
  74  <com:TTextHighlighter Language="xml" CssClass="source">
  75  <url ServiceParmaeter="ArticleView">
  76  <![CDATA[
  77      /articles\/(?P<year>\d{4})\/(?P<month>\d{2})\/(?P<day>\d+)/u
  78  ]]>
  79  </url>
  80  </com:TTextHighlighter>
  81  <p>
  82  In the above example, the pattern contains 3 parameters named "<tt>year</tt>",
  83  "<tt>month</tt>" and "<tt>day</tt>". The pattern for these parameters are,
  84  respectively, "<tt>\d{4}</tt>" (4 digits), "<tt>\d{2}</tt>" (2 digits)
  85  and "<tt>\d+</tt>" (1 or more digits).
  86  Essentially, the <tt>Parameters</tt> attribute name and values are used
  87   as substrings in replacing the placeholders in the <tt>Pattern</tt> string
  88  to form a complete regular expression string.
  89  </p>
  90  
  91  <div class="note"><b class="tip">Note:</b> If you intended to use the <tt>RegularExpression</tt>
  92  property you need to escape the slash in regular expressions.
  93  </div>
  94  
  95  <p>Following from the above pattern example,
  96  an URL "<tt>http://example.com/index.php/articles/2006/07/21</tt>" will be matched
  97  and valid.  However, "<tt>http://example.com/index.php/articles/2006/07/hello</tt>" is not
  98   valid since the "<tt>day</tt>" parameter pattern is not satisfied.
  99   In the default <tt>TUrlMappingPattern</tt> class, the pattern is matched against the
 100  <b>path</b> property of the URL only. For example, only the
 101  "<tt>/index.php/articles/2006/07/21</tt>" portion of the URL is considered.
 102   </p>
 103  
 104  <p>
 105  The mapped request URL is equivalent to <tt>index.php?page=ArticleView&amp;year=2006&amp;month=07&amp;day=21</tt>.
 106  The request parameter values are available through the standard <tt>Request</tt>
 107  object. For example, <tt>$this->Request['year']</tt>.
 108  </p>
 109  
 110  <p>The URL mapping are evaluated in order they are place and only the first mapping that matches
 111   the URL will be used. Cascaded mapping can be achieved by placing the URL mappings
 112   in particular order. For example, placing the most specific mappings first.
 113  </p>
 114  
 115  <h2 id="21002">Constructing Customized URLs</h2>
 116  <p>
 117  Since version 3.0.6, <tt>TUrlMapping</tt> starts to support constructing customized URL formats. This is achieved by allowing users to extend <tt>TUrlMapping</tt> class and override the <tt>constructUrl</tt> method. In the applications, users can still use <tt>THttpRequest.constructUrl()</tt> or <tt>TPageService.constructUrl()</tt> to generate PRADO-recognizable URLS. The actual URL construction work is ultimately delegated to the <tt>TUrlMapping.constructUrl()</tt>, provided it is implemented.
 118  </p>
 119  
 120  </com:TContent>