Iain Urquhart

Taxonomy 3

taxonomy:nav

Build navigation on your ExpressionEngine site

The taxonomy:nav tag outputs your tree structure in any format you require, primarily for generating menus/navigations.

The tag can operate as a tag pair:

Note: If you're updating from 2.x to 3.x, the taxonomy:nav tag pair does *not* automatically add the <li> elements any more, and includes a new {children} vairable

Or a single tag:

{exp:taxonomy:nav tree_id="1"}

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.


entry_id=

entry_id="{entry_id}"

Use this parameter to implicitly set which node is the current/active node. It is recommended you set this parameter where possible, especially if using any of the auto_expand or active_branch features.

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


node_id="

node_id="2"

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


display_root=

display_root="no"

Don't output the root node of the requested tree, or the requested subset of the tree. Default is 'yes'


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 is associated with the entry_id specified


root_node_id=

root_node_id="45"

Start the tree from the node with the node_id specified


root_node_url_title=

root_node_url_title="{last_segment}"

Start the tree from the node which is associated with an entry that contains the url_title 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.


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

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 tree data with no <ul> elements applied. Here's an example of generating a Taxonomy list manually:


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.


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


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_class} active
Returns 'active', 'active_parent' or null depending on the node's status in the active node selection.
{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
{my_custom_taxonomy_field} Bonjour
Output any custom taxonomy field by calling it's short name

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