URL mapping in Composite

This article describes how Composite maps incoming HTTP requests to specific pages, which developer-related features this yields and how to change the default URL pattern “composite-NNN.htm” to a custom pattern, like “page-NNN.htm”.

Mapping incoming requests

Composite uses two kinds of mechanisms when mapping an incoming HTTP request to a specific page:

• A Friendly URL lookup
  Example: contact.htm
• A URL pattern containing the ID of the page requested
  Example: composite-17.htm

The Friendly URL mechanism

When editing a page you can assign it a Friendly URL on the Access fan. The Friendly URL consists of a hostname field and a path field.

You typically specify a hostname when the page should be the entry page for a sub site, triggered by the host name. For instance, if you specify www.contoso.com as a hostname, and DNS / IIS mappings are in place, a request for http://www.contoso.com/will map to this page.

The hostname mapping mechanism uses a “best match, right to left” strategy – so specifying “contoso.com” will match both http://www.contoso.com/and http://contoto.com/ - unless, of course, the more specific www.contoso.com is assigned to another page.

You use the path field to provide an alternative URL to the page, besides from the auto numbered “composite-NNN.htm” styled URL. When communicating through speech or printed media it is convenient to have a context related path, like http://contoso.com/products.

The navigation related modules that ship with the current version of Composite will use the friendly URL, if specified, when creating menus, sitemaps, navigation bars etc. So specifying a friendly URL on a page will automatically change its URL in those dynamic elements.

The path mapping strategy uses a “best match, left to right” strategy. Developers can use this behavior to create custom output based on the path. A page with “products” as a Friendly URL will be triggered by any request where the path starts with “products”, like “products-binoculars-infrared”. Embedding an ASP.NET Control on the page, that examines the path and acts in accordance, can be seen as an alternative to the more classical GET and POST parameter approach.

The URL pattern mechanism

The URL pattern mechanism depends on a URL Transformation, executed by an IIS ISAPI filter called UrlTransformer. This ISAPI is installed automatically on Composite sites and uses information located in the registry to figure out which URL patterns to transform, and what the transformation should yield.

The UrlTransformer configuration is located in the following registry branch:

• HKLM\Software\CompositeNetsystems\UrlTransformer\Rules

The rule name part have the following pattern:

• <NN - Precedence number >;<Regular Expression – what to match>

The rule data part define the regular expression transformation rule.

Example:

• "01;/composite-(\d+)\.htm(.*)" = "/composite-($1)\.chtm($2)"

This rule has the precedence number “01” (precedence numbers are evaluated as the double ASCII value, 01 comes before 02 etc.). It will match any URL starts with “/composite-”, then has a number, and then has “.htm” and the any string. It will transform the URL into a nearly identical string, except “.htm” will become “.chtm” (which triggers the Composite page handler).

A number of rules exist; mapping std. “composite-NNN.htm” requests in preview and non-preview situations, media file requests and “show.asp” requests, the latter for backwards capability reasons.

Do not change the default mappings created by Composite. If you need to change the default URL pattern “composite-NNN.htm” to something else, you should add new rules as described below.

Please note that the system changes described below require you to be a proficient Composite XSL developer with DBO access to the sites SQL Server database and the IIS server registry, working within a test environment.

If you plan to deploy your site on a shared hosting environment, you should contact the ISP regarding their policy on changes to core Composite configuration like UrlTransformer.

Changing the “composite-NNN.htm” URL pattern

Changing the URL pattern for Composite pages on a default installation requires changing the sites .config file, adding UrlTransformer rules to the registry and changing the XSL templates for navigational elements.

Changing the pattern in the sites .config file

The sites configuration file is located in the folder <Composite Root>\Configuration and is named <Site name>.config. The XML file contains an element named “documenturlpattern” which is used be the Content WYSIWYG editor when the user creates links manually, using the “Link to” function on the left hand sitemap.

By default the <documenturlpattern /> element value is “composite-$$DOCUMENTID;.htm”. The token “$$DOCUMENTID;” is replaced with the page ID the users links to.

To change the URL pattern from “composite-NNN.htm” to “page-NNN.htm”, simply edit the <documenturlpattern /> element and change the word “composite” to “page”.

Adding UrlTransformer rules

When changing the default URL pattern you should add new UrlTransformer rules rather than change existing rules.

To add new rules for a pattern like “page-NNN.htm”, add the following name/data pairs as string values to the existing list, located under the following registry key: HKLM\Software\CompositeNetsystems\UrlTransformer\Rules

• “50;/page-(\d+)\.htm(.*)” = “/composite-($1)\.chtm($2)”
• “51;(.*)/preview(.*)/page-(\d+)\.htm(.*)” = “/preview/composite-($3).chtm?($4)”

(The quotes should be omitted – they are shown above for readability).

Regardless of the pattern you want, the transformation must have the pattern “composite-NNN.chtm”.

Changing XSL templates for navigational elements

The XSL templates that generate the menus, sitemaps, navigation bars etc. contains the “composite-NNN.htm” mapping by default, and each template needs to be updated.

You can do this manually, by locating all XSL templates that generate page URLs and change occurrences of “composite-“ to “page-“.

Provided you are situated in a non-production environment, have a backup of the Composite database and do thorough testing when done, you can execute the following SQL statement on the Composite database to get the job done faster:

UPDATE LLCDataQueryXsl_Source
SET xsltext = Replace( Cast( xsltext as nvarchar(4000) ), 'composite-', 'page-' )
WHERE Len( Cast( xsltext as nvarchar(4000) ) ) < 3900
AND CharIndex( 'composite-', Cast( xsltext as nvarchar(4000) ) ) > 0

This will replace the pattern “composite-“ with “page-“ in all XSL templates with a length less that 3.900 characters. If you have XSL templates larger than 3.900 characters you should handle them manually, using the Composite XSL editor.

To locate the Identifiers of XSL templates with a length larger than 3.900 characters, execute the following SQL statement on the Composite database:

SELECT DISTINCT Xsl.Identifier
FROM LLCDataQueryXsl_Source XslSrc
INNER JOIN
LLCDataQueryXsl Xsl
ON Xsl.id = XslSrc.DataQueryXsl_id
WHERE Len( Cast( xsltext as nvarchar(4000) ) ) >= 3900

The Identifiers returned by this query need to be edited manually.

Deployment

When deploying a site with a different Composite page URL pattern you should document the changes to the UrlTransformer configuration and the sites configuration file.