URL parameters

In Smartsite iXperion 1.3, the Friendly Names system has been extended to support MVC-style URLs. This way of styling URLs avoids the use of querystring parameters for applications.

Lets say you have an application that displays a list of projects, allowing the user to page through a list, select a project and view the project details, you would normally get the following url syntax:

http://domain/projects?page=3&project=2669

Now, with URL parameters, you can specify that parameters should be written into the URL path, instead of the querystring:

http://domain/projects/3/2669

To enable URL parameters, set the 'Use URL Parameters' flags in the 'Friendly Name' tab of your application item:

Note that Friendly Urls must be enabled in the Channel.

Also note that in iXperion 1.4+, the URL parameters feature, is only available if the release setting 'immutableLocators' is set.

Reading and writing URL parameters is very straightforward, since it can be done using the querystring parameters methods, once you have mapped the position of an URL parameter to a name (see Vipers).

Rules

Since parameter values are written to the path component of the URL, different escaping rules apply than for querystring parameters. Besides the normal querystring escaping that will take place, the following extra rules apply:

• Empty values shown in between non-empty values are represented as dashes ('-'): /friendlyname/first/-/third.
• If an URL parameter's value is a single '-' (dash), i is escaped to '%2D'.
• Finally, the '%' sign is written as '$', to prevent automatic unescaping when re-read into System.Uri objects (%2F is converted into '/' just by reading it into a Uri). 

Vipers

The most important viper for URL parameters is url.mapparams(). Calling this viper allows you to then address any parameter (querystring or url parameter) using the existing syntax:

Smartsite SXML	Copy Code
{url.mapparams(request.location(), 'page', 'project')} {buffer.set(proj, request.query(project))}

This makes adapting existing applications to URL parameters extremely easy.

When calling into URL parameter applications, you can use the same technique:

Smartsite SXML	Copy Code
{buffer.set(url, url.create(MY_URLPARAMS_ENABLED_APP))} {url.mapparams($url, 'action', 'term', 'page')} {url.setparameter($url, action, 'search')} {url.setparameter($url, term, 'goo goo dolls')}

You can also use the new overloads on url.addparameter() and url.setparameter():

Smartsite SXML	Copy Code
{url.addparameter(MY_URLPARAMS_ENABLED_APP, 'action', 'search', 1)}

Setting the extra 'position' argument to 1 maps the 'action' parameter name to the first URL parameter index.

The url.addparameters() and url.setparameters() methods also have new overloads. Using these overloads, you can pass a 'mapUrlParams' boolean parameter to make automatic URL mappings for each querystring parameter:

Smartsite SXML	Copy Code
{url.setparameters(MY_URLPARAMS_ENABLED_APP, true, 'action=search', 'term=goo goo dolls')}

Mapping URL Parameters to the current request

To get Querystring parameters from the current request, you will typically use request.query() instead of url.getparameter(request.location()). Request.location() though, will get you a copy of the current request's location, so you will have to get request.location() into a buffer, use url.mapparams() on that buffer, then use url.getparameter($buffername). Of course, this is a bit awkward, so we have introduced a better way:

Smartsite SXML	Copy Code
{request.mapparams('name1', 'name2', [...])}

After this, you can simply use request.query(name1) and get your parameter.

URL Parameters on folders (1.4+)

Since 1.4, URL parameters can be used in folders, as well as in items. This requires URLs using URL parameters to be differentiated from normal URL's however, since there would otherwise be an ambiguity between children within folders with URL parameters enabled, and application URL's to the folder (using MVC-style patrameters).

For example, consider this url:

http://domain.com/pub/news/archive/2010/

If the news folder has URL parameters enabled, the URL could point to

1. the news item itself, with the parameters 'archive' and '2010'
2. an item named '2010' in the folder 'archive' under 'news'

To remove this ambiguity, we have introduced the UrlParameterEndpointExtension parameter in the friendlynames section of the smartsite.config.

The UrlParameterEndpointExtension parameter sets the suffix to use on items with URL Parameters, so the system can determine what to do, just by looking at the URL.

XML	Copy Code
<friendlynames> <mapper id="DefaultFriendlyNameMapper" type="Smartsite.Core.DefaultFriendlyNameMapper, Smartsite.Runtime">       <parameters>         <parameter name="UseVirtualRoot">true</parameter>        <parameter name="UrlParameterEndpointExtension">mvc</parameter>      </parameters>    </mapper> </friendlynames>

By default, this parameter is set to 'mvc' (max 3 characters).

http://domain.com/pub/news.mvc/archive/2010/ points to the news item and sets the parameters 'archive' and '2010'

http://domain.com/pub/news/corporate/ points to a folder below news.

Note: if you don't want your MVC-style urls to be suffixed with an extension, you can set the UrlParameterEndpointExtension value to an empty string. This way,you will still be able to use MVC-style urls on items, but not on folders (pre-1.4 behavior).