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

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

User Contributed Notes

Posted by: AJP on 8 October 2008 3:10pm
AJP's avatar

It should be noted that when using a category group in multiple weblogs, the weblog parameter and the show_empty=“no” parameter, do not limit only to entries in that weblog (and hide the empty ones for that weblog). Rather, if an entry in another weblog has an entry is a given category, it *will* show the category name, that is “empty” in your specified weblog.
Posted by: Pie Man on 12 March 2008 9:54am
Pie Man's avatar

The Solspace Primary Category extension solves the problem of needing to have a “primary” category for an entry when it’s assigned to many categories… or even just 2.
No longer do you need to fiddle with sloppy workarounds… just drag and drop, and your done. The template variables are easy, clean, and flexible!

The Primary Category extension allows you to assign a primary category to an entry in ExpressionEngine using AJAX drag and drop. When you view a front-end page and have a weblog entries loop you can pull the primary category variables like all native EE category variables. Additionally, using the exp:primary_category loop, you can pull the same variables, so you have more flexibility.

http://www.solspace.com/software/detail/primary_category/
Posted by: supersusie on 9 August 2007 5:15am
supersusie's avatar

The order of the returned categories is controlled by the ordering settings of that category group in the control panel, and can’t be overridden.

This also means that subcategories will always appear directly below their parent categories, even when the list is styled as “linear” not “nested.”
Posted by: Arun Shanbhag on 9 July 2007 8:06pm
Arun Shanbhag's avatar

Example: Including the category_group parameter to use two category groups in a Weblog.
Admin ›  Weblog Administration ›  Category Groups
In the Catergory Groups section, the two category groups, (a) Categories, and (b) Issues, were defined.  The following code separated the two category groups in the sidebar.

<h2 class="sidetitle">Categories</h2>
<p>
{exp:weblog:categories weblog="{my_weblog}" style="nested" category_group="1"}
<a href="http://expressionengine.com/{my_template_group//index}">{category_name}</a>
{/exp:weblog:categories}
</p>

<h2 class="sidetitle">Issues</h2>
<p>
{exp:weblog:categories weblog="{my_weblog}" style="nested" category_group="2"}
<a href="http://expressionengine.com/{my_template_group//index}">{category_name}</a>
{/exp:weblog:categories}
</p>

Posted by: Daniel Walton on 6 July 2007 10:12am
Daniel Walton's avatar

Please note that Category Custom Fields are parsed later than default category fields.  This means the following code would NOT work, as an example.

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

You must have an ExpressionEngine license and have attained a forum rank of "Lab Assistant" (100 posts) to contribute notes to the User Guide