Categories documentation

This module adds an extra tag called {exp:categories} that, unlike {exp:channel:categories} can get category information without being tied to a channel. This way you can let a client edit categories (lists basically) which you use in form dropdown lists, etc.

Install

To install simply unzip and drop the "categories" folder into /system/expressionengine/third_party/ - then navigate to Addons -> Modules in the Control Panel and hit "Install" on the "Categories" module.

Parameters

  • category_group_id (optional, use either this or channel) the group id of the category to get
  • channel (optional, use either this or category_group_id) the name of the channel whose categories to fetch
  • category_id (optional, use if you just want to retrieve a specific category by id) the database id of the category to fetch
  • url_title (optional) if specified the tag will only get information about a specific category (with that url_title)
  • style (optional) nested/linear – will default to “nested”
  • children (optional) y/n (defaults to y) specify children=‘n’ if you do not want children (only root categories)
  • fetch_entry_counts (optional) y/n (defaults to no) – if you enable this the database work will be a bit heavier
  • only_count_status (optional) - used in conjunction with fetch_entry_counts if you only want to coint entries with a certain status (e.g. open, closed, featured, etc.) You can use the | separator here (e.g. only_fetch_counts=‘open|featured’)
  • show_empty (optional, defaults to "yes") - if set to "no" only categories with entries will be fetched

Variables

  • {category_id}
  • {category_name}
  • {category_url_title}
  • {category_image}
  • {category_description}
  • {category_entry_count} (remember to set fetch_entry_counts parameter to ‘y’ to get this)

Usage examples

Here's code to output a ul/li based menu:

<ul>

{exp:categories category_group_id=’1’}
<li><a title="{category_name}" href="{path=blog/category}/{category_url_title}" >{category_name}<span class="nav-description">{category_description}</span></a>

{if has_children}
<ul>
{children}
<li><a title="{child_category_name}" href="{path=blog/category}/{child_category_url_title}">{child_category_name}</a></li>

{/children}
</ul>
{/if}

</li>
{/exp:categories}
</ul>

Get all categories w/entry count:

{exp:categories category_group_id="1" style="linear" fetch_entry_counts="yes"}
<li><a href="{path=blog/{category_url_title}}">{category_name}</a> ({category_entry_count})</li>

{/exp:categories}

Only display categories that contain entries:

<ul>
{exp:categories category_group_id="1" style="linear" show_empty="no"}
<li><a href="{path=blog/{category_url_title}}">{category_name}</a> ({category_entry_count})</li>
{/exp:categories}
</ul>

This example will populate a dropdown list using the categories in group_id 4:

{exp:categories category_group_id="4" style="linear"}
<option value="{category_url_title}">{category_name}</option>
{/exp:categories}

Create a navigation menu for a channel from its associated categories (while counting the entries w/status open OR featured for each category):

<ul class="faq-categories">
{exp:categories channel='faq' fetch_entry_counts='y' only_count_status='open|featured'}
<li><a href="#">{category_name} <span>({category_entry_count})</span></a></li>
{/exp:categories}
</ul>

This will populate a form with some hidden values pointing to category images:

{exp:categories category_group_id="4" style="linear"}
<input type='hidden' name='{category_url_title}_logo' value='{category_image}'/>
{/exp:categories}