In this Article

Understanding contextual URLs

Several widgets in Telligent Community rely on a specific context or contextual data in order to display their contents properly. For example, the Blog -  Post List widget allows you to select a blog or group and can be used out of context, while the Blog Post widget needs to be in the context of a blog post.

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 for 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 this context, the widget does not know which 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's 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.

Contextual data currently supported In Telligent Connect For Sitecore

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

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).

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 a 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.

Mappings, tokens and routes

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

Tokens (master: /sitecore/system/modules/TelligentEvolution/Urls/Tokens)

Tokens represent placeholders. They are used to replace the wildcard characters behind the scenes with an identifiable value. For example, a wildcard path like this - /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, such as a group ID or application key.  You should never have to alter the values of tokens.

Position mappings (master: /sitecore/system/modules/TelligentEvolution/Urls/Position Mappings)

Position mappings define which wildcards in an item path will be replaced by which 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.For example, consider our previous URL of /item/item2/*/*.  You could create a mapping for this URL having two positions - one for each wildcard and a token assigned to each position. The number of positions defined in the mapping is the minimum number of wildcards required in the path. The example below shows the default mapping for a blog post. This mapping has three  positions - GroupID, BlogKey, and PostKey. So when we define a path for a blog post, we expect it to contain at least three wildcards (one wildcard for each position). We also then replace the position with the defined token so that we can easily extract the value at that position later.

Routes (master: /sitecore/system/modules/TelligentEvolution/Urls/Routes)

Routes tie tokens and mappings together. Routes, unlike tokens and often mappings, do require some configuration.

A route determines which mapping to use based on the contextual item. It 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 followed by a rule, provided that every item can satisfy the same mapping. The rule consists of a condition, which is usually checking that the item path has wildcards, and an action to execute if the rule is true. This action to execute 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. It has 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 that the mapping defined.

Defining a route

Now, let's focus on using the information to create a route. In the following example, we will create a route for a blog post. This route will utilize the the default route that is already defined and its mappings; we are simply going to add our item path. The goal is a resulting URL that you can display the blog post widget on.

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 items are the minimum pieces of data needed to reliably retrieve a blog post when not using any of the post's ID.  Because we have three positions, our target item for our URL needs to have a minimum of three wildcards in its path. For this example mapping, the first wildcard will be the group ID; the second, the blog's application key, and the third, the post's slug or key.

Step 2: Create the Item Path

From this information, we can set up our item path.

We are going to create the following path:

( /sitecore/content/home/community/*/b/*/* )

which has our three wildcards. The resulting URL should be: http://mysite.com/en/community/{groupid}/b/{blogKey}/{postSlug}.aspx, given the mapping we discussed earlier.

The following screen capture has the same tree, but the display names in it are changed a bit to show you how the mapping will extract values:

You should be able to navigate to the URL you are trying to create and adding ?sc_mode=edit in order for the page editor to open. 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 can't see contextual data because the wildcards are not present.

Thus, in our case, we are going to http://hostname/en/community/3/b/sample_weblog/expanding-your-community.aspx?sc_mode=edit. You can see that we've replaced our wildcards with valid data:

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 the Debug widget doesn't 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 Evolution 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 the items and select the target item, which in this case is the last wildcard in our item path.

  8. Click OK.

  9. Save the route.

After saving, return to  http://hostname/en/community/3/b/sample_weblog/expanding-your-community.aspx?sc_mode=edit and refresh the page. The post should now appear.

If you examine the Debug widget, a group, blog and post are now in context. You also see the tokens extracted from the URL.

Blog post is now displayed




Debug widget now shows route is resolved