GWcode Categories Documentation

The tag in its most simple form:

{exp:gwcode_categories}{/exp:gwcode_categories}

..will show a nested list of all category groups (wrapped in h2 tags) and its categories.
Click the thumbnail below to see the output:

GWcode Categories Default Ouput

Parameters

If you're using the ExpressionEngine 1 version of this plugin, be sure to replace "channel" with "weblog".

As explained in the "How it works" section of the overview page, in most cases you'll pick a starting point first by using one of these parameters:

Parameter Possible Value(s) Example Description
channel Channel short name(s), separated by pipe characters channel="my_channel|another_channel" Returns the categories for these channels.
group_id Category group ID('s), separated by pipe characters group_id="1|2" Returns the categories for these category groups.
cat_id Category ID cat_id="30" Returns the child categories for this category by default, or the parent categories for this category if you use it in combination with the "show_trail" parameter.
cat_url_title Category URL title cat_url_title="{segment_3}" Returns the child categories for this category by default, or the parent categories for this category if you use it in combination with the "show_trail" parameter.
entry_id Entry ID('s), separated by pipe characters entry_id="23" Returns the categories the entry has been added to.

Then, if needed, you can narrow down the resulting list of categories with these parameters:

Parameter Possible Value(s) Example Description
last_only yes, no (default) last_only="yes" If set to "yes", only last child categories will be returned.
depth number(s), separated by pipe characters depth="1|2" Returns categories with a certain depth (level) only. Depth 1 categories are root categories. Depth 2 categories are their children, etc.
min_depth number min_depth="2" Only return categories with a minimum depth.
max_depth number max_depth="3" Only return categories with a maximum depth.
show_empty yes (default), no show_empty="no" Returns categories with 1 or more entries only.
excl_group_id Category group ID(s), separated by pipe characters excl_group_id="2|3" Can only be used in combination with the "channel" parameter currently to remove 1 or more category groups from the results. If you need this parameter in any other case, let me know :)
excl_cat_id Category ID('s), separated by pipe characters excl_cat_id="2|3" Removes these categories from the results.
excl_cat_id_children yes, no (default) excl_cat_id_children="yes" Can be used in combination with the "excl_cat_id" parameter. If set to "yes", this will also remove all children categories for the categories supplied with the "excl_cat_id" parameter.
show Category ID('s), separated by pipe characters show="2|4" Can be used to only show categories with a certain category ID (this parameter will act as a filter).
limit number limit="5" Limit the number of categories being returned.
output_depth numer(s), separated by pipe characters output_depth="1|2" Allows you to only show categories with a certain "output depth". If you have a category in a category group with a depth of 3 for example and you want to show its child categories in a nested list, but only its direct children, you can use this parameter. (example will follow soon)
offset one positive number and/or one negative number, separated by a pipe character offset="2|-3" Remove a number of categories from the beginning or end of the final output. Use a negative number to remove categories from the beginning and a positive number to remove categories from the end.

If you want to show the number of entries in each category that's being returned (by using the {entry_count} variable), you can use any or a combination of the following parameters:

Parameter Possible Value(s) Example Description
entry_count yes, no (default) entry_count="yes" This is the fastest possible way to show the entry count. It will count all entries of any status and also includes entries which are expired or which entry date is in the future.
status entry status status="open|approved" This will display the number of entries with a certain status.
count_future_entries yes (default), no count_future_entries="no" If you don't want to count entries with an entry date in the future, use count_future_entries="no".
count_expired_entries yes (default), no count_expired_entries="no" If you don't want to count expired entries, use count_expired_entries="no".

Additionally, these parameters are available as well:

Parameter Possible Value(s) Example Description
site_id Site ID('s), separated by pipe characters site_id="1|2" In case you use Multi Site Manager.
style nested (default), simple, linear style="linear" Return a nested (possibly multi-level) ul or ol list, a simple nested (one level) ul or ol list, or a linear list.
list_type ul (default), ol list_type="ol" See "style" parameter above. If nested or simple, should it be an unordered (ul) or ordered (ol) list?
backspace number backspace="3" Removes characters from the last iteration of the loop. Can only be used when the "style" parameter has been set to "linear".
id CSS id id="ul-id" Adds an ID to the ul / ol for CSS or JavaScript.
class CSS class class="ul-class" Adds a class to the ul / ol for CSS or JavaScript.
custom_fields yes, no (default) custom_fields="yes" Enables you to output category custom fields if set to "yes".
show_trail yes, no (default) show_trail="yes" Can only be used in combination with the "cat_id" or "cat_url_title" parameter. When set to "yes", this will display a list of the category's parent categories.
incl_self yes (default), no incl_self="no" Can only be used in combination with the "cat_id" or "cat_url_title" parameter. When set to "no", the category provided with the "cat_id" or "cat_url_title" parameter will not be included in the results.
show_full_trail yes, no (default) show_full_trail="yes" Can only be used in combination with the "entry_id" parameter. When set to "yes", it will show a full trail from the root category to the category an entry has been posted in, even if the entry hasn't been added to a category's parent categories.
orderby entry_count, cat_id, cat_name, random. These values can also be separated by pipe characters, except when using "random". orderby="cat_name" By default, GWcode Categories will output your categories in the same order as defined in the EE Control Panel. You can use this parameter in combination with the "sort" parameter to override the default order. For example, to generate a list of "most popular" categories where the categories with the most entries are listed on top, you can use orderby="entry_count" sort="desc". If you use "random" as the value for this parameter, it will only work if you set style="linear" or style="simple".
sort asc (default), desc. These values can also be separated by pipe characters. sort="asc" Can be used in combination with the "orderby" parameter and determines the sort method.
variable_prefix anything variable_prefix="gw:" Allows you to add a prefix to all variables used by GWcode Categories, to prevent conflicts with another add-on or native ExpressionEngine variables when you nest tags. For example, {parent_id} will become {gw:parent_id}.
switch anything. Use a pipe character to separate values. switch="class1|class2" Can be used to rotate through any number of values as the categories are displayed.

If you use a combination of the depth paramaters, like so for example:

{exp:gwcode_categories channel="example" depth="1" min_depth="3"}
	{cat_name}
{/exp:gwcode_categories}

..the plugin will return all categories for channel "example" that have a depth of 1 or depth 3 or higher.

Variables

The following variables can be used between the {exp:gwcode_categories} and {/exp:gwcode_categories} tags. They allow you to control what the output should look like:

Variable Description
{site_id} The site ID a category group / category belongs to.
{cat_count} Incrementing number for each category in the output.
{cat_count_in_group} Incrementing number for each category in the output. Resets for each category group in the list.
{group_heading}..{/group_heading} A variable pair which will be parsed before a new category group starts when you use style="nested" or style="simple" (it will not be available when you use style="linear"). Allows you to add a heading to your category groups like this: {group_heading}<h2>{cat_group_name}</h2>{/group_heading}
{cat_group_id} The category group's ID number.
{cat_group_name} The category group's name.
{cat_id} The category's ID number.
{cat_name} The category's name.
{cat_url_title} The category's URL title.
{cat_description} The category's description
{cat_image} The category's image.
{cat_order} The category's order number (unlikely to be useful).
{parent_id} The category's parent category ID.
{parent_url_title} The category's parent URL title.
{parent_name} The category's parent category name.
{depth} The category's depth. Root categories have a depth of 1. Their child categories have depth 2 etc.
{results} The number of categories being displayed, which can be limited because of the "limit" parameter.
{results_total} The total number of categories, without taking the "limit" parameter into account.
{group_start} This variable is "true" when a new category group starts. Can be useful for conditionals. For example: {if group_start}..show something..{/if}
{group_end} Like {group_start}, but is set to "true" when a category group ends.
{has_children} Can be useful for conditionals to find out if a category has child categories. For example: {if has_children}..this category has child categories..{/if}
{has_children_in_output} Like {has_children}, but this variable will only be "true" if the child categories are actually shown in the output.
{entry_count} The number of entries in a category. This variable will only be available if you use the entry_count, status or show_empty parameter.
{li_depth} The depth for a category's list item (li tag) in the final output. This value will always be 1 for simple lists (style="simple") and 0 for linear lists (style="linear").
{complete_path} The complete path for a category, starting with its root category. Can be used to create hyperlinks.
{output_path} The path for a category as shown in the output. Can be used to create hyperlinks.
{no_results} You can use the "no_results" variable in conditionals to show a message if there are no results: {if no_results}Nothing to show here!{/if}
{depthX_start} Swap the X with a valid depth number in the output. Can be used in conditionals to show something when the output for a certain depth starts. For example: {if depth1_start}Start!{/if}
{depthX_end} Same as {depthX_start}, but for when the output for a certain depth ends. Example: {if depth1_end}End!{/if}
{depthX_start_count} Increasing number starting with 1 for when the output of categories with a certain depth starts. Example: {if depth2_start_count == 3}This is the start of my third group of child categories{/if}
{depthX_end_count} Same as {depthX_start_count}, but for when the output of categories with a certain depth ends. Example: {if depth2_end_count == 3}This is the end of my third group of child categories{/if}
{switch} Outputs the value given with the "switch" parameter.
custom category fields All custom fields assigned to a category can be accessed using the "short name" of the field. Example: {my_custom_field}. Please note, in order to get this to work, you need to add the parameter custom_fields="yes" to the plugin tag.

With all these parameters and variables, we should be able to do some cool things. Let's head over to the examples page!