Weblog Categories

The "weblog categories tag" enables you to show your categories in a list. Here is the basic syntax:

{exp:weblog:categories}

{category_name}

{/exp:weblog:categories}

Everything contained between the opening and closing tag will be repeated for each category, so if you want to wrap each category with some markup, like a div tag, you'll do this:

{exp:weblog:categories}

<a href="{path=weblog/index}">{category_name}</a>

{/exp:weblog:categories}

Parameters

backspace=

backspace="6"

Backspacing removes characters from the last iteration of the loop. For example, if you put a <br /> tag between each category you'll have this layout:

Local News<br />
Health News<br />
Science News<br />

You might, however, not want the <br /> tag after the final item. By adding backspacing you can remove it. Simply count the number of characters and spaces in the item you want to remove and add it to the tag. A <br /> tag has 6 characters, so you would do this:

{exp:weblog:categories backspace="6"}

{category_name}<br />

{/exp:weblog:categories}

That will produce code like this:

Local News<br />
Health News<br />
Science News

The "backspace" parameter is only allowed if you are using the "linear" style. It is not applicable if you use the "nested" style for the display of the list.

parent_only=

parent_only="yes"

This parameter allows you to limit the category display to only "parent" categories; no sub-categories will be displayed.

style=

style="nested"

There are two list "styles" for your categories: "nested" and "linear".

A "nested" category is one that shows the parent/child hierarchy. It will display the categories as nested "unordered lists" and will automatically enclose the contents in <li> tags and nest them correctly to show the hierarchy:

<ul>
  <li>News</li>
    <ul>
      <li>Regional</li>
      <li>World</li>
    </ul>
  <li>Sports</li>
    <ul>
      <li>National</li>
        <ul>
          <li>Football</li>
          <li>Basketball</li>
            <ul>
              <li>Lakers</li>
              <li>Knicks</li>
            </ul>
        </ul>
    </ul>
</ul>

A "linear" category is one that shows a pure list:

News
Regional
World
Sports
National
Football
Basketball
Lakers
Knicks

By default, if you do not specify the "style" parameter then you will get a "nested" list.

If you do use the nested list, there are two additional parameters:

weblog=

weblog="weblog_name"

The name (short name) of the weblog to which the categories are assigned. Note: You can only list one weblog name, since each weblog can only have one category list. This variable is required unless you only have a single weblog.

Variables

category_name

{category_name}

This variable simply displays the name of the category.

path=

{path=template_group/template}

The path (template_group/template) where you want to show the categories. This is typically used within a standard HTML link tag:

<a href="{path=weblog/index}">{category_name}</a>

You can also use SITE_INDEX in your path to point to your main site index page. If you show your blog on your home page, using SITE_INDEX is preferable since it will make the URL cleaner.

<a href="{path=SITE_INDEX}">{category_name}</a>

Examples

Here are a few examples of the categories tag in use:

{exp:weblog:categories weblog="news" backspace="6"}

<a href="{path=news/entry"}>{category_name}</a><br />

{/exp:weblog:categories}

This code would create a list of the categories in the "news" weblog and link to the "news/entry" Template. It would also remove the <br /> from the last entry.

{exp:weblog:categories weblog="politics" style="nested"}

<a href="{path=SITE_INDEX"}>{category_name}</a>

{/exp:weblog:categories}

This code would create a nested, unordered list of the categories from the "politics" weblog as links to the main weblog page.