further enhanced TUrlMapping.

1 files changed, 42 insertions, 35 deletions

diff --git a/demos/quickstart/protected/pages/Configurations/UrlMapping.page b/demos/quickstart/protected/pages/Configurations/UrlMapping.page
index 4e06dd09..3197dde3 100644
--- a/demos/quickstart/protected/pages/Configurations/UrlMapping.page
+++ b/demos/quickstart/protected/pages/Configurations/UrlMapping.page
@@ -4,36 +4,29 @@
 

 <com:DocLink ClassPath="System.Web.TUrlMapping" />

 

-<p id="230222" class="block-content">Using the <tt>TUrlMapping</tt> module different URLs can be

-mapped into any existing Prado pages or services. This allows

-the application to use nice looking and friendly URLs.

+<p id="230222" class="block-content">

+The TUrlMapping module allows PRADO to construct and recognize friendly URLs

+based on specific patterns.

 </p>

 

 <p id="230223" class="block-content">

-The <tt>TUrlMapping</tt> module allows aributary URL path to be mapped to a

-particular service and page class. This module must be configured

-before a service is initialized, thus this module should be configured

-globally in the <a href="?page=Configurations.AppConfig">application configuration</a>

-file and before any services.

+TUrlMapping consists of a list of URL patterns which are used to match

+against the currently requested URL. The first matching pattern will then

+be used to decompose the URL into request parameters (accessible via

+<tt>$this->Request['paramname']</tt>). The patterns can also be used to

+construct customized URLs. In this case, the parameters in an applied

+pattern will be replaced with the corresponding GET variable values.

 </p>

 

-<div class="info"><b class="tip">Info:</b>

-The <tt>TUrlMapping</tt> must be configured before the

-<a href="?page=Fundamentals.Modules">Request module</a> resolves the request.

-This usually means delcaring the <tt>TUrlMapping</tt> module before any

-<tt>&lt;services&gt;</tt> tag in the  <a href="?page=Configurations.AppConfig">application configuration</a>.

-Specifying the mappings in the per directory <tt>config.xml</tt> is not supported.

-</div>

-

 <p id="230224" class="block-content">

 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,

 <com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_230098">

 <modules>

     <module id="request" class="THttpRequest" UrlManager="friendly-url" />

     <module id="friendly-url" class="System.Web.TUrlMapping">

-        <url ServiceParameter="Posts.ViewPost" pattern="post/{id}/?" parameters.id="\d+" />

-        <url ServiceParameter="Posts.ListPost" pattern="archive/{time}/?" parameters.time="\d{6}" />

-        <url ServiceParameter="Posts.ListPost" pattern="category/{cat}/?" parameters.cat="\d+" />

+        <url ServiceParameter="Posts.ViewPost" pattern="post/{id}/" parameters.id="\d+" />

+        <url ServiceParameter="Posts.ListPost" pattern="archive/{time}/" parameters.time="\d{6}" />

+        <url ServiceParameter="Posts.ListPost" pattern="category/{cat}/" parameters.cat="\d+" />

     </module>

 </modules>

 </com:TTextHighlighter>

@@ -49,9 +42,18 @@ The above example is part of the application configuration of the <tt>blog</tt>
 </ul>

 

 <p id="230226" class="block-content">

-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.

+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.

 </p>

 

+<div class="info"><b class="tip">Info:</b>

+The <tt>TUrlMapping</tt> must be configured before the

+<a href="?page=Fundamentals.Modules">request module</a> resolves the request.

+This means delcaring the <tt>TUrlMapping</tt> outside of the

+<tt>&lt;services&gt;</tt> element in the <a href="?page=Configurations.AppConfig">application configuration</a>.

+Specifying the mappings in the per directory <tt>config.xml</tt> is not supported.

+</div>

+

 <h2 id="46023">Specifying URL Patterns</h2>

 <p id="230227" class="block-content">

 <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.

@@ -63,7 +65,7 @@ values are regular expression patterns that
 determine the mapping criteria. The <tt>Pattern</tt> property takes

 a regular expression with parameter names enclosed between a left brace '<tt>{</tt>'

 and a right brace '<tt>}</tt>'. The pattens for each parameter can be set

-using <tt>Parameters</tt>attribute collection.

+using <tt>Parameters</tt> attribute collection.

 For example,

 <com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_230099">

 <url ServiceParameter="ArticleView" pattern="articles/{year}/{month}/{day}"

@@ -72,11 +74,8 @@ For example,
 </p>

 The example is equivalent to the following regular expression (it uses the "named group" feature in regular expressions available in PHP):

 <com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_230100">

-<url ServiceParmaeter="ArticleView">

-<![CDATA[

-	/articles\/(?P<year>\d{4})\/(?P<month>\d{2})\/(?P<day>\d+)/u

-]]>

-</url>

+<url ServiceParameter="ArticleView"

+     RegularExpression="/articles\/(?P<year>\d{4})\/(?P<month>\d{2})\/(?P<day>\d+)/u" />

 </com:TTextHighlighter>

 <p id="230229" class="block-content">

 In the above example, the pattern contains 3 parameters named "<tt>year</tt>",

@@ -93,13 +92,13 @@ property you need to escape the slash in regular expressions.
 </div>

 

 <p id="230230" class="block-content">Following from the above pattern example,

-an URL "<tt>http://example.com/index.php/articles/2006/07/21</tt>" will be matched

-and valid.  However, "<tt>http://example.com/index.php/articles/2006/07/hello</tt>" is not

- valid since the "<tt>day</tt>" parameter pattern is not satisfied.

- In the default <tt>TUrlMappingPattern</tt> class, the pattern is matched against the

-<b>path</b> property of the URL only. For example, only the

-"<tt>/index.php/articles/2006/07/21</tt>" portion of the URL is considered.

- </p>

+an URL <tt>http://example.com/index.php/articles/2006/07/21</tt> will be matched

+and valid.  However, <tt>http://example.com/index.php/articles/2006/07/hello</tt> is not

+valid since the <tt>day</tt> parameter pattern is not satisfied.

+In the default <tt>TUrlMappingPattern</tt> class, the pattern is matched against the

+<b>PATH_INFO</b> part of the URL only. For example, only the <tt>/articles/2006/07/21</tt>

+portion of the URL is considered.

+</p>

 

 <p id="230231" class="block-content">

 The mapped request URL is equivalent to <tt>index.php?page=ArticleView&amp;year=2006&amp;month=07&amp;day=21</tt>.

@@ -107,14 +106,22 @@ The request parameter values are available through the standard <tt>Request</tt>
 object. For example, <tt>$this->Request['year']</tt>.

 </p>

 

-<p id="230232" class="block-content">The URL mapping are evaluated in order they are place and only the first mapping that matches

+<p id="230232" class="block-content">The URL mapping are evaluated in order they are placed and only the first pattern that matches

  the URL will be used. Cascaded mapping can be achieved by placing the URL mappings

  in particular order. For example, placing the most specific mappings first.

 </p>

 

 <h2 id="46024">Constructing Customized URLs</h2>

 <p id="230233" class="block-content">

-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.

+Since version 3.1.1, <tt>TUrlMapping</tt> starts to support constructing customized URLs based on the provided patterns. To enable this feature, set <tt>TUrlMapping.EnableCustomUrl</tt> to true. When <tt>THttpRequest.constrcutUrl()</tt> is invoked, the actual URL construction work will be delegated to a matching <tt>TUrlMappingPattern</tt> instance. It replaces the parameters in the pattern with the corresponding GET variables passed to <tt>constructUrl()</tt>.

+</p>

+

+<p id="230234" class="block-content">

+A matching pattern is one whose <tt>ServiceID</tt> and <tt>ServiceParameter</tt> properties are the same as those passed to <tt>constructUrl()</tt> and whose named parameters are found in the GET variables. For example, <tt>constructUrl('Posts.ListPost',array('cat'=>2))</tt> will use the third pattern in the above example.

+<p>

+

+<p id="230235" class="block-content">

+By default, <tt>TUrlMapping</tt> will construct URLs prefixed with the currently requesting PHP script path, such as <tt><b>/path/to/index.php</b>/article/3</tt>. Users may change this behavior by explicitly specifying the URL prefix through its <tt>UrlPrefix</tt> property. For example, if the Web server configuration treats <tt>index.php</tt> as the default script, we can set <tt>UrlPrefix</tt> as <tt>/path/to</tt> and the constructed URL will look like <tt>/path/to/article/3</tt>.

 </p>

 

 <div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file