GWcode CatMenu Documentation

Throughout the documentation, we'll use the words "open", "active" and "current" often, to describe the state a category is in. A category is "open" when it's showing its child categories in the menu.

Categories are "active" when they are in an active menu path. For example, when we are viewing the ExpressionEngine category page and the menu path is 3 levels deep: Services → CMS → ExpressionEngine, the ExpressionEngine category is considered to be active, and so are its parent categories up until the root category (CMS and Services).

And finally, categories are "current" when they are being provided with the cat_id or cat_url_title parameter, or when the entry_id or entry_url_title has been provided and the entry has been added to that category.

Parameters

Here's a list of available parameters for the {exp:gwcode_catmenu} tag. In most cases, you would probably use:

  • the entry_id or url_title parameter on single entry pages, so the menu will open the categories an entry has been added to;
  • the cat_id or cat_url_title parameter on your category pages, so the menu will open the category currently being viewed;
  • the channel or channel_id parameter, or the group_id parameter on any other pages where you want to show a menu.

Feel free to use any combination of parameters.

Parameter Example Description
site_id site_id="1|2" For Multi Site Manager. Multiple values allowed.
channel_id channel_id="1" Channel ID number. Creates a menu for that channel. Multiple values allowed.
channel channel="example" Like "channel_id", but use the channel short name instead.
group_id group_id="1" Category group ID number. Creates a menu for that category group. Multiple values allowed. This parameter can also be used to determine the order. E.g. group_id="1|2|3" creates a menu in a different order compared to group_id="3|2|1".
cat_id cat_id="3" Category ID number. Creates a menu with that categories as "open" and "active", which means the category shows possible child categories. Multiple values allowed.
cat_url_title cat_url_title="cat1" Like "cat_id", but use the Category URL Title instead.
entry_id entry_id="1" Entry ID number. Creates a menu, where the categories the entry has been added to are marked as "open", "active" and "current".
url_title url_title="my_entry" Like "entry_id", but use the Entry URL Title instead.
depth_open depth_open="1|2|3" Opens up categories in the menu with this depth. Root categories are depth 1, its child categories have depth 2 etc. Multiple values allowed.
active_depth_open active_depth_open="1|2|3" Opens up categories in the menu with this depth, but only for root categories which are marked as "active". Root categories are depth 1, its child categories have depth 2 etc. Multiple values allowed.
entry_count entry_count="yes" Enables the {entry_count} variable to display the number of entries (with status "Open") in a category. Default value: "no".
status status="open|pending" Like "entry_count", but with the option to choose the status. Multiple values allowed.
style style="simple" Return a nested (possibly multi-level) menu, a simple nested (one level) menu, or a linear menu. Possible values: "nested" (default), "simple", "linear".
backspace backspace="3" Removes characters from the last iteration of the loop. Can only be used in combination with style="linear".
show_empty show_empty="no" Show or don't show empty categories in the menu. If a parent category has 0 entries, but one or more of its child categories has 1 or more entries, it will still be included in the menu. Default value: "yes".
excl_cat_id excl_cat_id="2|35" Exclude categories (and their possible child categories) from the menu. Multiple values allowed.
excl_group_id excl_group_id="1|2" Exclude category groups from the results. Multiple values allowed.
min_depth min_depth="2" Only return categories with a minimum depth.
max_depth max_depth="3" Only return categories with a maximum depth.
active_branch_only active_branch_only="yes" When set to "yes", the menu will only show category tree branches which are active from the root. Default value: "no".
list_type list_type="ol" Use an unordered (ul) or ordered (ol) list. Possible values: "ul" (default), "ol".
id id="main_nav" Adds an ID to the outermost ul / ol for CSS or JavaScript.
class class="catmenu" Adds a class to the outermost ul / ol for CSS or JavaScript.
class_open class_open="expanded" Change the name of the class that's being added to li tags for "open" categories. Use class_open="-" to prevent this class from being added. Default value: "open".
class_active class_active="active_path" Change the name of the class that's being added to li tags for "active" categories. Use class_active="-" to prevent this class from being added. Default value: "active".
class_depth class_depth="level" Change the name of the class that's being added to li tags with the category's depth. Use class_depth="-" to prevent this class from being added. Default value: "depth".
id_group_heading id_group_heading="catgroup" Change the name of the id that's being added to the li tag for the {group_heading}..{/group_heading} variable pair. Use id_group_heading="-" to prevent this id from being added. Default value: "group".
class_group_heading class_group_heading="catgroup" Change the name of the class that's being added to the li tag for the {group_heading}..{/group_heading} variable pair. Use class_group_heading="-" to prevent this class from being added. Default value: "group-heading".
class_entry_count class_entry_count="count" Adds a css class to the list item tags with the number of entries appended so that you can "grey out" empty categories for example.
class_current class_current="current_category" If you use the "cat_id", "cat_url_title", "entry_id" or "url_title" parameter, a CSS class "current" will be added to the li tag for those categories or the categories the entry has been added to. You can change the name of that class with this parameter. Use class_current="-" to prevent this class from being added. Default value: "current".
add_class_url_title add_class_url_title="yes" When set to "yes", a unique class based on the category's url title will be added to the li tag for that category, which can be useful if you need to style a certain category. Default value: "no".
custom_fields custom_fields="yes" Allows you to output category custom fields if set to "yes". Default value: "no".
variable_prefix variable_prefix="gw:" Allows you to add a prefix to all variables used by GWcode CatMenu, to prevent conflicts with another add-on or native ExpressionEngine variables when you nest tags. For example, {parent_id} will become {gw:parent_id}.

Variables

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

Variable Description
{site_id} The site ID a category belongs to.
{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 URL to a 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.
{count} Incrementing number for each category in the menu.
{entry_count} The number of entries in a category. This variable will only be available if you use the entry_count or status parameters.
{total_entry_count} This variable will contain the total number of entries in a category, including the entries for any of its child categories, or their child categories etc.
{total_results} The total number of categories in the menu.
{active} Can be used for conditionals, to add a CSS class to active category links for example: {if active} class="active"{/if}
{open} Can be usefed for conditionals, to add a CSS class to open categories for example: {if open} class="open"{/if}
{current} Can be used for conditionals and will be true for categories which are current. Example: {if current} class="current"{/if}
{has_children} Can be used for conditionals to find out if a category has child categories. For example: {if has_children}..link this category to a different template..{/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.
{complete_path} The complete path for a category, starting with its root category. Can be used to create hyperlinks.
{output_path} The output path for a category, starting with the root category in the menu. Can be used to create hyperlinks and differs from {complete_path} when you use min_depth="2" for example.
{group_id} The category group's ID number.
{group_name} The category group's name.
{group_heading}..{/group_heading} A variable pair which will be parsed before a new category group starts. Allows you to add a heading to your category groups like this: {group_heading}<h2>{group_name}</h2>{/group_heading}
{new_group} Can be used for conditionals. Example: {if new_group}..a new category group has started..{/if}
{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}

With all these parameters and variables, we should be able to create the category based menu you're looking for. Let's head over to the examples page!