Slugs & URL Maps: SEO Friendly URLs

The URL Map feature on dotCMS Content Types is an easy way to automatically create friendly URL's for Search Engine Optimization (SEO) as the content is contributed. When you create a URL Map for a Content Type, each individual content item can be viewed from the front-end of your site as if it had it's own separate page, without you having to create a separate page for each content item.

To create a URL Map for a Content Type, you create a URL Map Pattern on the Content Type which redirects all front end requests matching the pattern to a detail page (configured on the Content Type). The detail page understands how to display a single item of your Content Type, and displays the individual content as if it had its own separate page.

Constructing the URL Map Pattern

The URL Map Pattern field may contain any combination of text and Content Type Variables, organized in a folder hierarchy (separated by forward slashes (/)). Each Content Type Variable must match the Variable value of a Field of the Content Type, and must be enclosed in braces (curly brackets).

Note: It is recommended that you end all URLMap values with a trailing slash (/), as this makes the URL more robust to being accessed in different ways, and differences in user environments.

For example, consider a Content Type named “Documentation” with the following text fields:

Label	Variable
Title	title
UTL Title	urlTitle
Subject	subject

To create a URL Map which includes the Subject in the URL, the URL Map Pattern could be set as follows:

/help/{subject}/{urlTitle}/

This would include “/help”, the value of the Subject field, and the value urlTitle field in the URL for each piece of content, ensuring that both the word “help” and the subject of each piece of content are incorporated in your SEO strategy. For example, using the above URL Map Pattern, a document detailing user password rules with the Subject set to “Security” might end up mapped to the following URL:

/help/security/user-password-restrictions/

The Detail Page

The detail page is a Page that is specifically built to display a single content item of your URL Mapped Content Type. The detail page uses Velocity code to retrieve an individual content item accessed via the URL Map, and formats and displays that individual item.

Note that the detail page is not intended to be accessed directly (via it's own URL) from your front-end site. For example, if your detail page is located in “/somefolder/detail”, it is not intended for users to access the detail page via a URL of the form “http://site.yourdomain.com/somefolder/detail”.

Instead, when dotCMS recognizes that a user has entered a URL which matches the URL Map Pattern, dotCMS automatically displays the detail page for your Content Type, and passes the appropriate content item (the content item whose field values match the URL entered) into the detail page.

For more information on how to access a URL Mapped content item from within your detail page, please see the Velocity Code to Access URLMap Info section, below.
For more information on how to build your detail page, please see the Creating a Detail Page documentation.

Configuring a Detail Page for Multiple Sites

The detail page specification can accommodate feeding content to multiple sites.

First, ensure that the Content Type and all relevant content live on the System Host, rather than a particular Site.
Next, when defining the Content Type's detail page, include a Site in the path. For example:
```
//dotcms.com/documentation/index
```
For each additional site, in line with the example above, ensure that a detail page exists in the relative path /documentation/index.

Example: dotCMS Documentation

This documentation site, for example, utilizes the URL map attribute on a Content Type named the Documentation so that all content can be reached using an SEO friendly URL Path:

/docs/latest/{urlTitle}

There is actually only one HTML page serving up ALL of the dotCMS documentation you are currently reading. The Documentation Content Type has a required field named urlTitle. As content is contributed, this field builds the URL path and passes the matching piece of content to the detail page. This occurs automatically through the use of the URL Map field on the Content Type as seen in the example image below:

dotCMS Documentation URL Map Configuration

For example, this document you are now reading is a piece of content that has the following field:

urlTitle = slugs-and-url-maps-seo-friendly-urls

The combination of the URL Map Pattern (/docs/latest/{urlTitle}) and the value of the urlTitle field (slugs-and-url-maps-seo-friendly-urls) produce the URL you see at the top of your browser (/docs/latest/slugs-and-url-maps-seo-friendly-urls). Note that this URL allows you to access this document as a separate page, even though the “docs” and “latest” directories do not actually exist within dotCMS.

There is only one HTML page serving up all of the documentation and all of the content in the repository is building its own virtual URL path in your browser on the detail page (configured to the documentation index page)!

Handling Non-Matching URLs

By default, if the URL entered via a URL map does not match any existing content, dotCMS will generate an HTTP 404 (page not found error). However URL Mapping can be configured to “fall through,” displaying the URL Map page even if there is no matching content.

To affect this property, configure the DOT_URLMAP_FALLTHROUGH environment variable accordingly:

true (default): Check for matching content and then fall through.
- A check is first made to find a piece of content with a matching URL Map, then if there is no match the path “falls through” to check if there is a matching dotCMS object whose path matches the URL path (most likely the base HTML page used to display all the URL map content).
false: Always redirects to the detail page as set on the Content Type.
- Forces dotCMS to always display the detail page for the content type, regardless of whether or not any content matches the URL.
  - This means the detail page acts like a custom 404 page for the structure for requests that match the URL Map pattern.
- The detail page should be set up to handle page visits that do not match the URL Map pattern to any piece of content.
  - The following psuedocode demonstrates one possible way to handle this in the detail page:
```
#set($myCats  = $request.getRequestURI().split("/"))
#foreach($cat in $myCats)
    #set($myCat = $cat)
#end 
Here is the last cat: $cat 
#set($subject = $subjects.getCategoryByKey(${cat}))
##Now use ${subject} to pull content in normal $dotcontent pulls
```

Velocity Code to Access URLMap Info

You can use Velocity code to access all of the following from your detail page:

Entered URL

Since the detail page is not intended to be accessed directly by its own URL, it will instead be accessed by a URL which matches the URL Map Pattern. To find the URL which was used to access the URL Mapped content (and which was used to match the URL Map pattern and display the detail page) use the following within your Velocity code:

$request.getAttribute("javax.servlet.forward.request_uri")

Individual Content Items

When your URL Map Pattern is matched, dotCMS will automatically find the individual content item which matches the pattern, and pass that content item to your detail page. To access the individual content item from within your detail page, use the following built-in content object:

$URLMapContent

Content Item Fields

The $URLMapContent is an object representing a single content item of your Content Type. You can access any field within the $URLMapContent object just as if you were accessing an object of your Content Type returned from any other Velocity method or viewtool (such as $dotcontent.pull()). For example, the following Velocity code can be used to access the “Title” field of the dotCMS Documentation content item displayed on this page:

$URLMapContent.title

Search Engine Optimization Impacts

To any user or search engine that accessed the front-end of your site, each individual content item of your URL Mapped Content Type appears to be a separate individual page on your site. This has the following benefits for Search Engine Optimization (SEO):

Your site has a larger number of pages (and thus is perceived as having more valuable content).
Each individual content item has a URL which may, itself match specific search terms (in addition to the content and content title).
Each individual content item has a URL which matches the content itself.
Links you create within your individual content items to other individual content items provide increased linkage and search term matching.
The user-friendly URLs for pages makes it easier for users to share and link to individual pages on your site.

All of these factors increase the relevance of both your site and your individual pages (in this case, individual content items) in search rankings.

Multilingual URLs

For information on how to create URL Maps that handle multiple languages, please consult the URL Maps (Multilingual) documentation.