The SiteURLManager
can use a transformation rules file to transform production site URLs, which is generally useful for generating staging server URLs and associating them with the correct site IDs. In a multisite environment with many servers, this can save much administrative overhead. For example, you can use transformation rules to generate staging site URLs by appending the string -staging
to all production site URLs, in order to generate staging site URLs. Thus, requests for wishesArePonies.com
and wishesArePonies-staging.com
are mapped to the same site ID and use the same site configuration.
The SiteURLManager's
transformRuleFile
property points to an XML file that contains transformation rules—by default, /atg/multisite/urlTransform.xml
. The SiteURLManager's
Boolean property enableURLTransform
determines whether it executes URL transformations—by default set to true
.
The SiteURLManager's
transformURL()
method processes the transform rule on all site production URLs. Because the urlTransform.xml
file may contain IDN Unicode, all strings are converted to ASCII before the transformation occurs.
Note: It is generally good practice to implement transformation rules only for servers that are used for testing purposes, such as staging and preview servers. Production servers should avoid using transformation rules, and rely on production site URLs as configured through Site Administration.
Constraints
The following constraints apply to URL transformation rules:
Only one rule is allowed per server configuration. All URLs are subject to the same transformation rule.
A multisite application uses generated URLs only for a given site. URL transformations have no effect on repository settings.
Transformation Operations apply only to portions of the domain name. They have no effect on URL path elements.
Transformation Operations
URL management supports three rule operations:
Operation | Syntax |
---|---|
|
|
|
|
|
|
Replace Operations
Replace operations can replace any portion of a domain name. For example, given the following rule:
<rule op="replace"> <new-string>foobar</new-string> <original>example</original> </rule>
hockey.example.com
is transformed as follows:
hockey.foobar.com
Prepend and Append Levels
prepend
and append
transformation rules specify a string to add to the domain name. The <level>
tag provides an integer value that specifies which label of the domain name to modify:
Level | Specifies... |
---|---|
| Top-level domain—for example, |
| Parent domain |
| Subdomain |
For example, given the following rule:
<rule op="append"> <new-string>-staging</new-string> <level>3</level> </append>
accessories.wishesArePonies.com
is transformed as follows:
accessories-staging.wishesArePonies.com