Retired Documentation:  You are using the documentation for version 1.7.3 which was retired in 2013. Go here for the latest version documentation or check here for your available upgrades to the latest version.

Weblog Categories Tag

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 you'll do this:

{exp:weblog:categories}

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

{/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 (do not include trailing spaces in your count). A <br /> tag has 6 characters, so you would do this:

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

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

category_group=

category_group="2"

Category Groups are specified by ID number (the ID number of each category group is displayed in the Control Panel). The reason we use the ID is because category groups can be called anything (with spaces, quotes, etc.), and also renamed. It would be much more difficult to have to update the tag parameters every time you updated a category name.

And as with many other parameters, you can stack category groups:

category_group="1|2|4"

Or use "not" to exclude categories

category_group="not 2"

class=

class="my_custom_class"

When using the "nested" style of display (see the style= parameter), this lets you specify the value of the "class" attribute in the opening <ul> tag. The default value is "nav_categories".

For instance, if you set the parameter as class="my_custom_class", then the beginning of the nested category output would be:

<ul class="my_custom_class">

disable=

disable="category_fields"

The disable= parameter allows you to turn off aspects of the tag that you might not be using in order to improve performance. Valid options are:

id=

id="my_custom_id"

When using the "nested" style of display (see the style= parameter), this lets you specify the value of the "id" attribute in the opening <ul> tag. The default value is "nav_categories".

For instance, if you set the parameter as id="my_custom_id", then the beginning of the nested category output would be:

<ul id="my_custom_id">

parent_only=

parent_only="yes"

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

show=

show="4|7"

With this parameter, you can specify which categories will be included in the list. For instance, if you wanted to keep a particular category from being listed you could specify only those you wanted displayed to be included. Category IDs are separated by the pipe character to specify more than one category.

You may alternatively specify which categories to not show:

show="not 3|6|8"

Note: If you specify that a parent category is not shown, then any children of that parent category are then unable to be shown by the tag. The parent category is required for any and all children categories.

show_empty=

show_empty="no" show_empty="yes"

This parameter determines whether or not categories that contain no entries are displayed. If you set the parameter to "no" then categories which do not contain any entries will not be included in the list.

By default, categories with no entries will be included.

status=

status="open"

You may restrict to categories with entries with a particular status . The two statuses "open" and "closed" are default statuses that are always available, so you can always specify those if needed. You can choose multiple statuses using a pipe:

status="draft|reviewed|published"

Or exclude statuses using "not"

status="not submitted|processing|closed"

By default, the Categories tag will display categories that contain any entries with a status other than closed.

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 id="nav_categories">
  <li>News
    <ul>
      <li>Regional</li>
      <li>World</li>
    </ul>
    </li>
  <li>Sports
    <ul>
      <li>National
        <ul>
          <li>Football</li>
          <li>Basketball
            <ul>
              <li>Lakers</li>
              <li>Knicks</li>
            </ul>
            </li>
        </ul>
        </li>
    </ul>
    </li>
</ul>

A "linear" category is one that shows a pure list with no HTML inserted:

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.

When using the "nested" style of display, the opening <ul> tag of the list will have an id of "nav_categories" applied to it. This can be used as a "hook" for javascript or CSS in providing DHTML or other functionality. You may change this by using the id= parameter.

weblog=

weblog="weblog_name"

The name (short name) of the weblog that the categories are assigned to. This variable is required unless you only have a single weblog.

You must specify this parameter if you use the category name in URL feature.

Variables

category_description

{category_description}

This variable simply displays the content from the "category description" field. The variable may also be wrapped in a conditional statement so that it only displays if there is content in the field:

{if category_description}{category_description}{/if}

category_id

{category_id}

The category ID associated with the category.

parent_id

{parent_id}

The category ID associated with the category's parent (or 0 in the case of a top level category).

category_image

{category_image}

The image link (or other information) you can optionally store with each category within the Control Panel.

category_name

{category_name}

This variable simply displays the name of the category.

category_url_title

{category_url_title}

This variable displays the URL title of the category

count

{count}

The "count" out of the current categories being displayed. If five categories are being displayed, then for the fourth category the {count} variable would have a value of "4".

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>

total_results

{total_results}

The total number of categories being displayed.

Custom Category Fields

All custom fields assigned to a category can be accessed using the "short name" of the field:

{class}
{extended_description}
{category_name_fr}
etc..

These are totally dynamic in that any field you create for your category will automatically be available by its "short name" as a variable.

Category Dropdown Menu

You can also display categories in a dropdown menu using the code below:

<form name="catmenu" action="">
<select name="selcat" onchange="location=document.catmenu.selcat.options[document.catmenu.selcat.selectedIndex].value;">
<option value="">--Select Category--</option>
{exp:weblog:categories weblog="yourweblog" style="linear"}
<option value="{path='weblog'}">{category_name}</option>
{/exp:weblog:categories}
</select>
</form>

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.

Top of Page