Displaying Related Content

The need often arises to display a list of database items that are related to the item being displayed. For example:

• In an information portal, when displaying an article you may want to list other articles on the same topic.
• In a product catalog, when displaying a product you may want to list other products in the same category.

Webvanta provides a variety of mechanisms for accomplishing this.

There are two fundamentally different ways to determine which are the related items:

1. By explicitly defining related items for each database item.
2. By showing items in the same category as the current item.

The first approach is most useful when the relations are idiosyncratic and not determined by categories. It provides the content editor with complete control over related items on an item-by-item basis. The cost, of course, is that each related item must be explicitly specified. See Working With Related Items for details on this technique.

Using the Categories Assigned to the Item

In many cases, you can use the category (or categories) to which an item is assigned to find related items without having to explicitly specify the connections. The following examples assume you are on an item page (that is, a page whose type is set to "Item"), which sets the item context.

The basic approach is as follows:

<w:kb:item>
  <w:kb:category:each relative="item">
    <ul>
      <w:kb:item:each category='current' filter='current_item'>
        <li><a href="<w:path url='/item' />"><w:name /></a></li>
      </w:kb:item:each>
    </ul>
  </w:kb:category:each>
</w:kb:item>

The code <w:kb:category:each relative="item"> sets up an iterator that repeats the code that follows it for each category to which the current item is assigned. Inside this loop, we can access the selected category as "current", so the code <w:kb:item:each category='current' filter='current_item'> iterates through each of the items in that category. Note the parameter filter='current_item'; this excludes the page's primary item from the list, since you wouldn't want to show that in a list of related items.

The following example takes this approach a little further, adding a heading for each category, but displaying the heading only if there are related items in that category:

<w:kb:item>
  <w:kb:category:each relative="item">
    <w:if_items category='current' filter='current_item'>
    <p>More items in category <w:name /></p>
    <ul>
    <w:kb:item:each category='current' filter='current_item'>
      <li><a href="<w:path url='/item' />"><w:name /></a></li>
    </w:kb:item:each>
    </ul>
    </w:if_items>
  </w:kb:category:each>
</w:kb:item>

Note the use of filter='current_item' in the w:if_items statement.

Using the Category Passed to the Page

In the examples above, all of the categories to which an item has been assigned are used to find related items. Often, however, you have additional context information based on how a particular item was reached.

Suppose, for example, you have a category page that lists all the articles in a particular category. In its simplest form, the category page might have code like this:

<w:kb:category>
  <ul>
    <w:kb:item:each type='articles'>
      <li><a href="<w:path url='/article' category='current' />"><w:name /></a></li>
    </w:kb:item:each>
  </ul>
</w:kb:category>

When this category page is accessed, it would have a category specified in the URL. This category is available as "current", and it is included in the URL generated for the article by the code <w:path url='/article' category='current' />.

Then, on the article page, you can access this category again as "current", to display other articles in the same category.

This example shows how you can create the list of related articles on the article page:

<w:kb:item>
    <ul>
      <w:kb:item:each category='current' filter='current_item'>
        <li><a href="<w:path url='/article' />"><w:name /></a></li>
      </w:kb:item:each>
    </ul>
</w:kb:item>

Note that unlike the approach described previously, if the article is assigned to multiple categories, the related articles displayed by the code above will include only the single category through which the article was accessed. Thus, the related articles shown will be different for the same article, depending on how the article was accessed.

For example, suppose there is an article about pets, and it is assigned to both the "cats" and "dogs" categories. If the article is accessed via a link on the cats category page, the related articles shown will be about cats, whereas if the same article is accessed via a link on the dogs category page, the related articles shown will be about dogs.

The following is a more complex example, taken from the item page code for our standard knowledgebase pages, that shows both articles and other resources (external links), and shows the appropriate headings only when there are items of that type:

<w:kb:item>
  <w:if_items category='current' filter='current_item'>
    <div class="kb">
      <h3>Additional Resources</h3>
          <w:if_items type='articles' category='current' filter='current_item'>
            <h4>Our Articles</h4>
            <ul>
              <w:each type='articles' category='current' filter='current_item'>
                <li><a href="<w:path url='/item' />"><w:name /></a></li>
              </w:each>
            </ul>
          </w:if_items>
          <w:if_items type='-articles' category='current' filter='current_item'>
            <h4>More Resources</h4>
            <ul>
              <w:each type='-articles' category='current' filter='current_item'>
                <li><a href="<w:path url='/item' />"><w:name /></a></li>
              </w:each>
            </ul>
          </w:if_items>
    </div>
  </w:if_items>
</w:kb:item>