Iain Urquhart

Taxonomy

Home → Software → Taxonomy Module → Module Tags → taxonomy:nav

taxonomy:nav

Build navigation on your ExpressionEngine site

{exp:taxonomy:nav tree_id="1" entry_id="{entry_id}" ul_css_id="my-id"}
    <a href="{node_url}">{node_title}</a>
{/exp:taxonomy:nav}

Navigation Tag Parameters

tree_id=

tree_id="1"

The id of the tree you want to fetch. This is a required parameter.

depth=

depth="10"

Set a limit on how many levels the generated list will go down.

Note: If you're using the root_node_entry_id parameter to output a tree which starts x levels down, you'll need to offset the depth parameter.
Example: if you wanted to start on a 5th level node, and display nodes at 2 levels below that, your depth parameter would be depth="7"

entry_id=

entry_id="{entry_id}"

By default the tag will look at the current uri, and match it against the node tree to find a match. If it finds a match, it will apply the css class 'active' to the active <li>. If your uri has any extra segments it will break this rule, so you can use this parameter to ensure the 'active' css class is applied, and enjoy the benefits of having the class 'active_parent' to ancestor <li> elements too.

It is assumed if you are passing an "{entry_id}", you are placing the nav tag between an exp:channel:entries tag.

display_root=

display_root="no"

Don't output the root node, default is 'yes'

Note: As of version 2.0.4 the scope of this parameter has changed:

Previous to 2.0.4:
display_root is strictly applicable to the first node of the entire tree

From 2.0.4 onwards:
display_root is applicable to the first parent of the requested tree (sub tree or entire tree).

root_node_lft=

root_node_lft="1"

Begins the navigation from the lft value of a given node. The root always has a lft value of 1.

Note: the 'lft' value will change if nodes are moved/added/deleted. I've left this in but should not be used unless you're doing something dynamic through nav iterations. Use the root_node_entry_id or root_node_id parameter below for a more 'fixed' approach to setting the root.

root_node_entry_id=

root_node_entry_id="45"

Start the tree from the node which contains the entry_id specified

root_node_id=

root_node_id="45"

Start the tree from the node with the node_id specified

ul_css_id=

ul_css_id="my-id"

Choose a css id to be placed on the outermost ul

ul_css_class=

ul_css_class="my-class"

Choose a css class or classes to be placed on the outermost ul

hide_dt_group

hide_dt_group="yes"

Hide/remove default template group from urls generated by Taxonomy.

url_title=

url_title="{segment_2}"

Start the tree from the node which contains the url_title specified

auto_expand=

auto_expand="yes"

To use this feature, the nav tag *must* implicitly know which node is active via the entry_id parameter or the node_id parameter (or alternatively via the set_node tag)

Makes the menu follow an active branch only, and only shows one level deeper than the current node. Only siblings of parents displayed.

For example, this is the regular Taxonomy nav output when visiting the Community node

Home
 |- about
 |- -- team
 |- -- -- jimmy
 |- -- -- sue
 |- -- *community*
 |- -- -- programs
 |- -- -- sponsorships
 |- -- -- -- helicopter rescue
 |- -- -- -- bird recovery
 |- contact
 |- -- some subpage

And you visited the same node, with auto_expand="yes" parameter added to the nav tag

Home
 |- about
 |- -- team
 |- -- *community*
 |- -- -- programs
 |- -- -- sponsorships
 |- contact

node_active_class=

node_active_class="active_parent"

Changes the default class name for the active node from 'active' to whatever you specify. Useful if you are injecting categories into your nav tag for example.

entry_status=

entry_status="open|special"

By default, Taxonomy will only display nodes with "open" statuses. Any nodes with statuses other than "open" will be skipped, and Taxonomy will skip all children too.

The parameter is optional, and you can pipe statuses to include as many statuses as you wish.

If you'd like the functionality of pre 1.2 where Taxonomy displayed all nodes regardless of status, use entry_status="ALL" to return nodes regardless of status.

style=

style="linear"

Gives you a raw output of your nodes with all variables below available to you. Useful if you are not requiring <ul> and <li> wrappers round your nav and you want to build your own custom output. You might find this blog post useful if you're looking to create a custom output with this tag.

active_branch_start_level=

active_branch_start_level="1"

Gives you a dynamic navigation which shows siblings/children of the active branch. Easiest to demonstrate, so here's an example tree structure:

Home
    Alpha
        Alpha one
    Bravo
        Bravo One
            Bravo One One
        Bravo Two
            Bravo Two One

Here is the taxonomy nav tag with the new active_branch_start_level parameter:

{exp:taxonomy:nav 
    tree_id="1" 
    entry_id="{entry_id}" 
    active_branch_start_level="1" 
    auto_expand="yes"
}
    <a href="{node_url}">{node_title}</a>
{/exp:taxonomy:nav}

And the resulting output whilst visiting Bravo:

Bravo
    Bravo One
    Bravo Two

And whilst visiting Bravo One:

Bravo
    Bravo One
        Bravo One One
    Bravo Two

require_valid_entry_id=

require_valid_entry_id="yes"

Default setting is 'no' and the nav tag will output the navigation regardless of having a valid entry_id or not. Setting this parameter to 'yes' will make the nav tag return null if the entry_id does not exist within the tree.

html_before="

html_before="<div class='foo'>"

Prefix your navigation output with additional markup. If the nav does not have anything to display, the markup entered in this parameter will not display either.

Note: if your parameter is using double quotes, make sure the html you're passing through does not also contain double quotes as it will end the parameter prematurely. See the example above for how I'm using single quotes inside the double quoted parameter.

html_after="

html_after="</div>"

Similar to the html_before parameter, this simply appends the navigation output with additional markup if required.

node_id="

node_id="2"

Similar to the entry_id parameter, this tells Taxonomy which node is currently active.

exclude_node_id="

exclude_node_id="2|3|4"

Ignore nodes with the node_ids specified. Multiple ids can be passed using the | character as a separator

exclude_entry_id="

exclude_entry_id="29|364"

Ignore nodes that contain the entry_ids specified. Multiple ids can be passed using the | character as a separator

show_future_entries="

show_future_entries="yes"

Show nodes with entries associated that are future dated

show_expired="

show_expired="yes"

Show nodes with entries associated that have expired

li_has_children_class="

li_has_children="has_kiddie_winkies"

Override the default class name of "has_children" with your own value

ul_css_class:level_x="

ul_css_class:level_1="dropdown"

Apply a custom class to <ul> elements at x depth.

For example, ul_css_class:level_1="drop_down" would add the class 'drop_down' to the level_1 <ul>

Navigation Tag Variables

These varables are available between the tag pair

Variable Example Output / Notes
{node_id} 22
The ID for this node
{node_title} About Us
The Label for this node as entered in the Taxonomy Module or Fieldtype
{node_url} http://example.com/about_us
The url of the node which can be comprised of template_group/template/url_title, page_uri, or URL Override
{node_active} active
Returns 'active' if this is the active/current node
{node_active_parent} active_parent
Returns 'active_parent' if this node is a parent the active/current node
Please note that the entry_id or node_id parameter must be used for this variable to function
{node_lft} 15
The 'lft' value of the node
{node_rgt} 16
The 'rgt' value of the node
{node_entry_id} 75
The entry_id of the entry associated with this node
{node_custom_url} /foo
The value entered in the "URL Override" field
{node_entry_title} About Us
The Title of the entry associated with this node
{node_entry_url_title} about_us
The url_title of the entry associated with this node
{node_entry_status} closed
The status of the entry associated with this node
{node_entry_entry_date} 1310087884
The entry_date timestamp of the entry associated with this node
{node_entry_template_name} default_page
The selected template associated with this node
{node_entry_template_group_name} pages
The selected template group associated with this node
{node_has_children} yes
Returns 'yes' if the node has children
{node_next_child} 3
Returns the current node's 'lft' value, +1
{node_level} 2
Depth/level of the node
{node_level_count} 5
Incremental count value as tag pair parses current level
{node_level_total_count} 5
Number of nodes at this level (total)
{node_count} 5
Incremental count value as tag pair parses entire tree
{node_previous_level} 3
The level of the previous node
{node_previous_level_diff} -1
The level difference of the previous node and this node
{node_indent} (whitespace)
Produces whitespace indenting on the tag pair, if you're anal about source markup.

If you require any additional user defined variables, take a look at node custom fields.

Want to say 'thank you'?

If you find any of my work useful, feel free to make a donation amount of your choosing via PayPal — or if you like, purchase a copy of Introvert from Devot-EE and you'll get something in return :)

↑ Back to top