What are Search Engine Safe (SES) routes? Take a typical Mach-II URL, e.g. /index.cfm?event=world&country=canada&province=british%20columbia&city=vancouver. Even using Mach-II’s own Search Engine Safe (SES), the URL remains somewhat ugly: /index.cfm/event/world/country/canada/province/british%20columbia/city/vancouver/.
Suppose the format of the URL is always consistent. In our example above it can safely be assumed that the event name is world which is followed by country, province, and city.
Search Engine Safe URLs with Mach-II
Using SES Routes to Clean a URL
Since the format and order of the example above is consistent, wouldn’t it make sense that we could omit the parameter identifiers? Why include country, province, and city for the event called world when we always know that this event is followed by the same parameters?
As of version 1.8, the Mach-II framework provides SES Routes you can do just that! With Mach-II configured correctly, the above example could just as easily be re-written as /index.cfm/world/canada/british%20columbia/vancouver/. So much shorter and easier to read, isn’t it?
Mach-II SES Routes Configuration
In order to utilize Mach-II SES Routes, they must be configured in the Mach-II configuration file. Each new route can be configured by adding another parameter. Below continues the example where the URL Route is defined by the name world and has all of country, province, and city as required parameters:
<property name="routes" type="MachII.properties.UrlRoutesProperty"> <parameters> <parameter name="world"> <struct> <key name="event" value="world" /> <key name="requiredParameters" value="country,province,city" /> </struct> </parameter> </parameters> </property>
Alternatively, below is a configuration where province and city are both optional (i.e. a user may want to be able to travel to /input.cfm/world/canada/ to view a page where it lists some common information on all provinces, for example):
<property name="routes" type="MachII.properties.UrlRoutesProperty"> <parameters> <parameter name="world"> <struct> <key name="event" value="world" /> <key name="requiredParameters" value="country" /> <key name="optionalParameters" value="province:all,city:all" /> </struct> </parameter> </parameters> </property>
Below is a more detailed breakdown of the UrlRoutesProperty. For more information on how to use some of the other parameters, make sure you check out the Mach-II wiki.
| module | String | Defines the module name in which the event exists for this route. |
| event | String | Defines the event name in which this route maps to. |
| urlAlias | String | Defines an alias to be used when building the route, otherwise the route name is used. |
| requiredParameters | List or Array | Required arguments that must be passed when building the route. The order of the required arguments defines the position of the argument in the route and can also define the default value to be used if it’s not passed into BuildRouteUrl(). |
| optionalParameters | List or Array | Optional arguments that can be passed when building the route. The order of the optional arguments defines the position of the argument in the route. Optional arguments must define a default value (using the “:” syntax) so if the argument is not passed into BuildRouteUrl() there is an optional value to use. |
Building URLs
As with the regular SES URLs, Mach-II provides a special method to construct SES Route URLs. This BuildRouteUrl function is the easiest way to leverage the configuration data and construct proper URLs dynamically rather than hardcoding them.
| BuildRouteUrl(routeName, [urlParameters], [queryStringParameters], [urlBase]) | ||
|---|---|---|
| routeName | String | Name of the route to build. |
| urlParameters | Pipe-delimited String or Struct | Name/value pairs (urlArg1=value1|urlArg2=value2) to build the URL with or a struct of required and option parameters. |
| queryStringParameters | Pipe-delimited String or Struct | Name/value pairs (urlArg1=value1|urlArg2=value2) to build the url with or a struct of query string parameters to append to end of the route. |
| urlBase | String | Used to change the base of the URL independent of the global setting. |
Continuing the example from above, a route URL could be created using the BuildRouteUrl function as follows:
<a href="#BuildRouteUrl('world', 'country=canada|province=british columbia|city=vancouver')#">Vancouver</a>
Which would translate to the following HTML:
<a href="/index.cfm/world/canada/british%20columbia/vancouver/">Vancouver</a>
Conclusion
As you can see, using Mach-II’s UrlRoutesProperty can really help generate some effective and good-looking URLs with very minimal effort. These URLs are not only easy to read, but also are effective when it comes to SEO applications.
Tags: BuildRouteUrl, ColdFusion, intermediate, Mach-II, routes, Search Engine Safe, SEO, SES, UrlRoutesProperty