Working with contextual URLs in Sitecore

Understanding contextual URLs

Several widgets in Telligent Community rely on a specific context or contextual data to display their contents properly. A widget used out of context either does not render at all or can result in errors. Telligent Community uses several techniques to determine context, but if you follow all of the paths to get contextual data, the root source of information is usually in the URL.

Types of contextual data

Contextual data is simply an object on which the content of the widget is based. For example, if you read a blog post, the contextual object is a specific blog post. Without it, the widget does not know what post in which blog you want to display. Some widgets function using contextual data but can also be set to a specific item. For example, the Blog - Post List widget is smart enough to determine whether it is in the context of a blog or a group, and will list blog posts depending on which is available. However, via widget configuration you can also set the blog or group specifically, bypassing the contextual data.

These items can all be determined from a URL, or determined based on a child item that is currently in context (such as a blog from a contextual blog post).

• Group
• Blog
• Blog
• User
• Forum
• Forum Thread
• Forum Reply
• Media Gallery
• Media File

How context is retrieved in Sitecore

Telligent Connect for Sitecore uses the concept of wildcard items to define dynamic pieces of data in a URL. When rendering pages, the tree path usually determines your URL, matching the names of items specifically in the tree hierarchy. If you add a wildcard instead of a proper name for an item (which is done by giving the item the name "*" instead of a proper name), it will use this item to match any value at that place in the hierarchy that isn't already specifically defined. For example, a path of /item1/subitem1/* will match /item1/subitem1/something.aspx or /item1/subitem1/12345.aspx.

The first part of understanding how to use wildcards with Telligent Connect for Sitecore is to understand some of the components. Most of the information explained here is set up for you. If you are starting a new community, you can leave the defaults in place.

Tokens

Tokens (master: /sitecore/system/modules/TelligentEvolution/Urls/Tokens) represent placeholders. They are used to replace the wildcard characters behind the scenes with an identifiable value.  For example, a wildcard path of /item/item2/*/* has no way of deciphering the first wildcard from the second. These values will be replaced by token values so that they can be easily identified as the data they represent, like a group ID or application key.  You should never have to alter the values of tokens.

Position Mappings

Position mappings (master: /sitecore/system/modules/TelligentEvolution/Urls/Position Mappings) define which wildcards in an item path will be replaced by what token value so they can later be extracted. A mapping is a collection of positions that define the wildcard's numeric position, or occurrence, in the path, and the token to use to replace it. Consider our previous URL of /item/item2/*/*.  A mapping you could create for this would have two positions: one for each wildcard and a token assigned to each position. The number of positions defined in the mapping are the minimum number of wildcards required in the path. The example below shows the default mapping for a blog post. It has three  positions: GroupID, BlogKey, and Post Key. This means when we define a path for a blog post, we expect it to contain at least three wildcards (i.e., one for each position). We also then replace the position with the defined token so it is easier to extract the value in that position later.

Routes

Routes (master: /sitecore/system/modules/TelligentEvolution/Urls/Routes) are what ties tokens and mappings together. They are the one piece that requires some configuration. Routes determine which mapping to use based on the contextual item. A route combines a collection of items with a specific rule and action to extract data from the wildcards in the URL. A route can have multiple items and then a rule. The rule consists of a condition, which is usually checking that the item path has wildcards, and action to execute if true, which is the process of extracting the data based on the defined mapping you specify in the action. The example below defines a blog post route example with one target item, so when that item URL is accessed, the condition checks for the presence of wildcards and extracts the values from those positions defined in the mapping. A route can have multiple items provided that every item can satisy the same mapping.

Defining a route

Now let's focus on using the information to create a route.  For an example, these steps walk you through creating a route for a blog post using the default route and its mappings. You just need to add the item path. The goal is a resulting URL on which you can display the blog post widget.

Step 1: Review the mapping

By default there is a BlogPostMapping already defined that utilizes the group ID, the blog application key, and the post slug or key. These are the minimum pieces of data needed to reliably retrieve a blog post when not using any of the post's IDs. Because we have three positions, our target item we will use for our URL needs to have a minimum of three wildcards in its path. With this mapping, the first wildcard will be the group ID, the second the blog's application key, and the last the post's slug or key.

Step 2: Create your Item Path

From this we can set up our item path. with three wildcards: /sitecore/content/home/community/*/b/*/*. The resulting URL will be: http://mysite.com/en/community/{groupid}/b/{blogKey}/{postSlug}.aspx, given the mapping we discussed earlier.

We can clean this image up a bit by changing the display names to show you how the mapping is going to extract values:

You should be able to navigate to the URL you are trying to create and add ?sc_mode=edit to open the page editor. We do it this way rather than through the content manager to ensure all of the data in our wildcards exists. The content editor opens the item by ID, which means we cannot see contextual data because the wildcards are not present. In our case, we are going to navigate to http://hostname/en/community/3/b/sample_weblog/expanding-your-community.aspx?sc_mode=edit. You can see we replaced our wildcards with valid data:

• Group ID: 3
• Blog application key: sample_weblog
• Post slug/key: expanding-your-community

On the page, add the Sitecore Debug Widget via the Telligent Community widget rendering, which is designed to show you contextual data for troubleshooting and verification:

Once added to the page, you will see it does not recognize a contextual blog post and blog, and the contextual group is Site Root, which is the default. In our case, group ID 3 is a sample group. So we can tell there is no route set up.

Furthermore, if you add another Telligent Community Component to the page and make it show the Blog Post widget, it will not render:

Step 3: Set up your route

To bring a blog post into context, we have to configure the route. The blog post route is already defined.

1. Edit the  BlogPostRoute and select Edit rule on the right to bring up the rule editor.
2. For the condition, under Telligent select target item has wildcards.
3. For the action, select the replace wildcards as defined in specific position mappings item.
   
   
4. Click specific position mappings item.
5. Select BlogPostMapping.
6. Click OK.
   
   
7. Click Edit above items and select the target item, which in this case is the last wildcard in our item path. Click OK.
   
   
8. Save the route.