Working with Categories

Categories are one of the most powerful features of the Webvanta database system. Using the built-in category support, you can organize your information in all kinds of ways.

Note: We have now generalized the category system into a more powerful taxonomy system. Categories are simply one of an infinite number of possible hierarachical taxonomies. See Working With Taxonomies for details. The syntax described in this article is still supported, though deprecated. All of the concepts still apply.

First, it's important to be clear about the difference between categories and item types. Each item type can have a different set of fields that defines the item's information. There are standard item types for such things as articles, blog posts, and links to various kinds of external items, and you can create custom item types with whatever fields you want. Example custom item types are products, companies, press releases, and FAQ items.

Categories, on the other hand, divide items of the same type (or across multiple types) into groups, typically by their topic or subtype. For example:

In a product catalog, you might have a single item type "product", and categories to specify the type of product (chairs, tables, accessories, etc.).

In an information portal site, you would typically use the categories to define the topics being covered, and then assign every article, blog post, book, or link to the appropriate category. The category (topic) page then shows all the items related to that topic, regardless of type.

Selecting a Category Directly

To work with a category you must, of course, specify the category in some way.

The simplest approach is to specify it directly:

<w:kb:category name='Cats'>
   (category context is set to 'Cats' for code placed here)
</w:kb:category>

You can also use a category ID, instead of the name, which makes for less readable but more robust code; it has the advantage of continuing to work even if the name of the category is changed.

Once you've set the category context, you can access the category's name and description easily:

<w:kb:category name='Cats'>
   <h2><w:name /></h2>
   <p><w:description /></p>
</w:kb:category>

Iterating Through Categories

While there are times when selecting a category manually in this way is desirable, more often you'll want to specify the category automatically in one way or another.

For example, this code displays a list of all of the top-level categories:

<ul>
  <w:kb:category:each>
    <li><w:name /></li>
  </w:kb:category:each>
</ul>

Accessing Subcategories

You can nest categories to any depth, though usually it is counterproductive to have more than two or three levels.

This code shows a list of categories and their subcategories.

<ul>
  <w:kb:category:each>
    <li><w:name />
    <ul>
      <w:each relative='children'>
        <li><w:name /></li>
      </w:each>
    </ul>
    </li>
  </w:kb:category:each>
</ul>

The w:kb:category:each iterator repeats the entire block of code following it once for each top level category. Inside of that code, we have another loop; the w:each relative='children' iterator repeats the code in the block that it creates for each subcategory of the current category.

Displaying the Items in a Category

You can use a category setting on the w:kb:item:each iterator to display all the items in a category. For example:

<ul>
  <w:kb:item:each category='Cats'>
    <li><w:name /></li>
  </w:kb:item:each>
</ul>

in this w:kb:item:each statement, you could provide a comma-separated list of category names (e.g., Cats, Dogs, Birds) and it will display all items in any of those categories.

In an iterator loop, or in a page context that sets the category, you can access the current category as "current". For example, this code lists all of the items in each top-level category:

<w:kb:category:each>
  <h2>Category: <w:name /></h2>
  <ul>
    <w:kb:item:each category='current'>
      <li><w:name /></li>
    </w:kb:item:each>
  </ul>
</w:kb:category:each>

Using Categories in Navigation

If you include a category page in the main menu, it has a magic behavior: it expands into one menu item for each top-level category. So if you put a category page into the menu and just create categories, each category will have its own menu item.

For an information portal site, in which the top-level categories are the primary navigation, put the category page as a top-level menu item. Each category will have its own menu item, with a drop-down menu for its subcategories.

On a business site, often you want to condense all the categories under one main menu item, using a drop-dowm menu to list the categories. To do this, create a menu item "Resources" (or whatever), and then drag the category page under it as a submenu item. This will magically expand to make a submenu entry for each top-level category.

Sometimes you may have categories that you don't want to include in the automatic menu creation. For any such categories, mark them as "Special" in the category editor and they will be excluded.

Using the "Current" Category

We gave an example above of using category="current" to set the category inside of a loop that is repeating for each category.

Threre's another common situation in which "current' is an important way to set the category. If you are on one of the special knowledgebase page types -- category, list, or item -- then the category may be passed to the page via the URL, and then made available as "current".

For example, here's a simple category page:

<w:kb:category>
  <h1>Category: <w:name /></h1>
  <w:kb:item:each category='current'>
     <p>Item: <w:name /></p>
  </w:kb:item:each>
</w:kb:category>

Here, it is w:kb:category that does the magic of capturing the category from the URL and making it available as "current".

Manually Creating Paths to Category Pages

If you want to create the URL for a specific category page, you can construct it by adding the category name as follows:

/category/category-name-here

Assuming that the slug for your category page is "category". Note that this simplified URL, including only the name of the category and not its ID, will not work if there are multiple categories with the same name, or there is a page with a slug that matches the category name. Also, the category name must be transformed into a "url-friendly" format, changing spaces to hyphens, for example.

It is more reliable to include the category ID in URL. You can find the category ID by going to Database > Categories, and then hover over the edit button for the category and note the ID in the URL. You can use the ID number alone, or append the title to it for SEO value.

Automatically Creating Paths to Category Pages

If you're using an iterator, or if the category has been set by the page context, you can use w:path to generate a path to the category page.

For example, the code below modifies our earlier example, which generates a list of categories, linking the category name to the category page.

<ul>
  <w:kb:category:each>
    <li><a href="<w:path url='/category' />"><w:name /></a></li>
  </w:kb:category:each>
</ul>

The url attribute in the path statement sets the particular category page to use, so you can use different category pages in different parts of your site.

The path statement will create a URL like:

/category/12345-category-name