Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml


Classes:
Keyword

Class TUrlMappingPattern

TComponent
   |
   --TUrlMappingPattern

TUrlMappingPattern class.

TUrlMappingPattern represents a pattern used to parse and construct URLs. If the currently requested URL matches the pattern, it will alter the THttpRequest parameters. If a constructUrl() call matches the pattern parameters, the pattern will generate a valid URL. In both case, only the PATH_INFO part of a URL is parsed/constructed using the pattern.

To specify the pattern, set the Pattern property. Pattern takes a string expression with parameter names enclosed between a left brace '{' and a right brace '}'. The patterns for each parameter can be set using Parameters attribute collection. For example

  1. <url ... pattern="articles/{year}/{month}/{day}"
  2. parameters.year="\d{4}" parameters.month="\d{2}" parameters.day="\d+" />

In the above example, the pattern contains 3 parameters named "year", "month" and "day". The pattern for these parameters are, respectively, "\d{4}" (4 digits), "\d{2}" (2 digits) and "\d+" (1 or more digits). Essentially, the <tt>Parameters</tt> attribute name and values are used as substrings in replacing the placeholders in the <tt>Pattern</tt> string to form a complete regular expression string.

For more complicated patterns, one may specify the pattern using a regular expression by RegularExpression. For example, the above pattern is equivalent to the following regular expression-based pattern:

  1. /^articles/(?P<year>d{4})/(?P<month>d{2})/(?P<day>d+)$/u
The above regular expression used the "named group" feature available in PHP. Notice that you need to escape the slash in regular expressions.

Thus, only an url that matches the pattern will be valid. For example, a URL <tt>http://example.com/index.php/articles/2006/07/21</tt> will match the above pattern, while <tt>http://example.com/index.php/articles/2006/07/hello</tt> will not since the "day" parameter pattern is not satisfied.

The parameter values are available through the <tt>THttpRequest</tt> instance (e.g. <tt>$this->Request['year']</tt>).

The ServiceParameter and ServiceID (the default ID is 'page') set the service parameter and service id respectively.

Since 3.1.4 you can also use simplyfied wildcard patterns to match multiple ServiceParameters with a single rule. The pattern must contain the placeholder {*} for the ServiceParameter. For example

<url ServiceParameter="adminpages.*" pattern="admin/{*}" />

This rule will match an URL like <tt>http://example.com/index.php/admin/edituser</tt> and resolve it to the page Application.pages.admin.edituser. The wildcard matching is non-recursive. That means you have to add a rule for every subdirectory you want to access pages in:

<url ServiceParameter="adminpages.users.*" pattern="useradmin/{*}" />

It is still possible to define an explicit rule for a page in the wildcard path. This rule has to preceed the wildcard rule.

You can also use parameters with wildcard patterns. The parameters are then available with every matching page:

<url ServiceParameter="adminpages.*" pattern="admin/{*}/{id}" parameters.id="\d+" />

To enable automatic parameter encoding in a path format fro wildcard patterns you can set {@setUrlFormat UrlFormat} to 'Path':

<url ServiceParameter="adminpages.*" pattern="admin/{*}" UrlFormat="Path" />

This will create and parse URLs of the form <tt>.../index.php/admin/listuser/param1/value1/param2/value2</tt>.

Use {@setUrlParamSeparator} to define another separator character between parameter name and value. Parameter/value pairs are always separated by a '/'.

<url ServiceParameter="adminpages.*" pattern="admin/{*}" UrlFormat="Path" UrlParamSeparator="-" />

<tt>.../index.php/admin/listuser/param1-value1/param2-value2</tt>.

Since: 3.0.5
Author: Wei Zhuo <weizhuo[at]gmail[dot]com>

Constructor Summary
public
__construct Array
Constructor.

Method Summary
string
constructUrl ( array $getItems, boolean $encodeAmpersand, boolean $encodeGetItems)
Constructs a URL using this pattern.
boolean
boolean
Returns a value indicating whether to use this pattern to construct URL.
boolean
TUrlManager
protected  string
Substitute the parameter key value pairs as named groupings in the regular expression matching pattern.
TAttributeCollection
string
array
Uses URL pattern (or full regular expression if available) to match the given url path.
string
string
string
THttpRequestUrlFormat
string
void
init ( TXmlElement $config)
Initializes the pattern.
void
setCaseSensitive ( boolean $value)
void
setEnableCustomUrl ( boolean $value)
Sets a value indicating whether to enable custom constructUrl using this pattern
void
void
setPattern ( string $value)
void
setRegularExpression ( string $value)
void
setServiceID ( string $value)
void
setServiceParameter ( string $value)
void
setUrlFormat ( THttpRequestUrlFormat $value, since 1)
Sets the format of URLs constructed and interpreted by this pattern.
void
setUrlParamSeparator ( string $value)
boolean
supportCustomUrl ( array $getItems)
Methods Inherited From TComponent
TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()

Constructor Details

__construct

public __construct Array

Constructor.


Method Details

constructUrl

public string constructUrl (array $getItems , boolean $encodeAmpersand , boolean $encodeGetItems )

Constructs a URL using this pattern.

Input
array$getItemslist of GET variables
boolean$encodeAmpersandwhether the ampersand should be encoded in the constructed URL
boolean$encodeGetItemswhether the GET variables should be encoded in the constructed URL
Output
string the constructed URL
Exception

getCaseSensitive

public boolean getCaseSensitive ()

Output
boolean whether the Pattern should be treated as case sensititve. Defaults to true.
Exception

getEnableCustomUrl

public boolean getEnableCustomUrl ()

Returns a value indicating whether to use this pattern to construct URL.

Output
boolean whether to enable custom constructUrl. Defaults to true.
Exception

getIsWildCardPattern

public boolean getIsWildCardPattern ()

Output
boolean whether this pattern is a wildcard pattern
Exception

getManager

public TUrlManager getManager ()

Output
TUrlManager the URL manager instance
Exception

getParameterizedPattern

protected string getParameterizedPattern ()

Substitute the parameter key value pairs as named groupings in the regular expression matching pattern.

Output
string regular expression pattern with parameter subsitution
Exception

getParameters

public TAttributeCollection getParameters ()

Output
TAttributeCollection parameter key value pairs.
Exception

getPattern

public string getPattern ()

Output
string url pattern to match. Defaults to ''.
Exception

getPatternMatches

public array getPatternMatches (THttpRequest $request )

Uses URL pattern (or full regular expression if available) to match the given url path.

Input
THttpRequest$requestthe request module
Output
array matched parameters, empty if no matches.
Exception

getRegularExpression

public string getRegularExpression ()

Output
string full regular expression mapping pattern
Exception

getServiceID

public string getServiceID ()

Output
string service id.
Exception

getServiceParameter

public string getServiceParameter ()

Output
string service parameter, such as page class name.
Exception

getUrlFormat

public THttpRequestUrlFormat getUrlFormat ()

Output
THttpRequestUrlFormat the format of URLs. Defaults to THttpRequestUrlFormat::Get.
Exception

getUrlParamSeparator

public string getUrlParamSeparator ()

Output
string separator used to separate GET variable name and value when URL format is Path. Defaults to slash '/'.
Exception

init

public void init (TXmlElement $config )

Initializes the pattern.

Input
TXmlElement$configconfiguration for this module.
Output
Exception
throwsTConfigurationException if service parameter is not specified

setCaseSensitive

public void setCaseSensitive (boolean $value )

Input
boolean$valuewhether the Pattern should be treated as case sensititve.
Output
Exception

setEnableCustomUrl

public void setEnableCustomUrl (boolean $value )

Sets a value indicating whether to enable custom constructUrl using this pattern

Input
boolean$valuewhether to enable custom constructUrl.
Output
Exception

setParameters

public void setParameters (TAttributeCollection $value )

Input
TAttributeCollection$valuenew parameter key value pairs.
Output
Exception

setPattern

public void setPattern (string $value )

Input
string$valueurl pattern to match.
Output
Exception

setRegularExpression

public void setRegularExpression (string $value )

Input
string$valuefull regular expression mapping pattern.
Output
Exception

setServiceID

public void setServiceID (string $value )

Input
string$valueservice id to handle.
Output
Exception

setServiceParameter

public void setServiceParameter (string $value )

Input
string$valueservice parameter, such as page class name.
Output
Exception

setUrlFormat

public void setUrlFormat (THttpRequestUrlFormat $value , since 1 )

Sets the format of URLs constructed and interpreted by this pattern.

A Get URL format is like index.php?name1=value1&name2=value2 while a Path URL format is like index.php/name1/value1/name2/value. The separating character between name and value can be configured with setUrlParamSeparator and defaults to '/'. Changing the UrlFormat will affect constructUrl and how GET variables are parsed.

Input
THttpRequestUrlFormat$valuethe format of URLs.
since13.1.4
Output
Exception

setUrlParamSeparator

public void setUrlParamSeparator (string $value )

Input
string$valueseparator used to separate GET variable name and value when URL format is Path.
Output
Exception
throwsTInvalidDataValueException if the separator is not a single character

supportCustomUrl

public boolean supportCustomUrl (array $getItems )

Input
array$getItemslist of GET items to be put in the constructed URL
Output
boolean whether this pattern IS the one for constructing the URL with the specified GET items.
Exception