Custom NavEE

Demo

Customize Your NavEE

Would you prefer to roll your own NavEE? We understand that, with navigation, one size does not always fit all. Using the navee:custom tag you can easily build your own navigation structure using any HTML elements you like. To build a navigation similar to what the default NavEE tags would output, you would do something like this:

{exp:navee:custom nav_title="main-nav" wrap_type="ul"}
  <li class="{class}"><a href="{link}">{text}</a>{kids}</li>
{/exp:navee:custom}

Parameters

All parameters are optional unless otherwise mentioned.

class

The class parameter will add a class to the outermost list container (ul or ol). This is useful for styling your navigation using CSS.

class=“main-nav”

branch_of_selected

The branch_of_selected parameter will display the entire branch of the selected node.

branch_of_selected="true"

disable_title

When we initially developed NavEE we did not prefix all of our variables, which is bad practice. This caused an issue when your NavEE tags are within standard EE tags and you want to use the channel entry title within your NavEE tags. Essentially, the NavEE {title} overrides the EE {title} field. By setting disable_title to true, it will fix this problem. You will then be able to access the NavEE title field information using the navee_title tag.

disable_title="true"

display_all_children_of_selected

This works similarly to only_display_children_of_selected, however, it continues building the navigation down infinitely until the end of the branch.

display_all_children_of_selected="true"

display_entire_branch

Expands the full branch of your navigation which contains the selected node.

display_entire_branch="true"

first_class

This parameter appends a special class onto the first item of each list.

first_class="first"

get_info_about_selected

This parameter is required if you want the depth_of_selected variable to be available.

get_info_about_selected="true"

id

The id parameter will add an ID to the outermost list container (ul or ol). This is useful for styling your navigation using CSS.

id="sub-nav"

ignore_include_in_nav

You’ll notice in the control panel that one of the options for each navigation node is Include In Navigation. This is useful if you want to build navigation items for use in your sitemap, but not show them in actual navigation.

ignore_include_in_nav="true"

ignore_regex

This parameter will force NavEE to ignore any regular expressions in your NavEE nodes.

ignore_regex="true"

include_single_parent

If you are using a dynamically generated navigation which starts below the root of your navigation tree, you can pass this parameter to include a single parent item above where your tree begins.

include_single_parent="true"

last_class

This parameter appends a special class onto the last item of each list.

last_class="last"

max_depth

The max_depth parameter allows you to set the maximum depth that your navigation will build to. If you only want a two-level navigation, you would set this parameter to:

max_depth="2"

The only parameter required by NavEE is nav_title. When you create your navigation in the control panel, your very first step will be to set a nav_title. Just enter that here, and you’ll be on your way.

nav_title="main-nav"

no_children

NavEE will generate your entire navigation in nested lists by default. If you would rather just have the top-level items and not dig into the subsequent levels of your navigation, set this to true. no_children only accepts true or false as values.

no_children="true"

no_selected

Override NavEE’s default action of marking matching pages as selected. This parameter only accepts true or false as values.

no_selected="true"

only_display_children_of_selected

Used in building a very specific kind of dynamic subnavigation, this parameter will only build children nodes on the path to the selected item in your navigation (and then one level below that). This is great if you have a large side-navigation and don’t want to use the method of hiding non-selected items with CSS.

only_display_children_of_selected="true"

parent_selected_class

By default, if you use the selected_class_on_parents paremeter, NavEE appends a class of selected onto any parents of the page that you are on. If you would like to add a different class, for example something like parent-selected, specify it here.

parent_selected_class="parent-selected"

reverse

The reverse parameter reverses the order of all items in your navigation.

reverse="true"

selected_class

By default NavEE appends a class of selected onto any item in your navigation that matches the page you are on. If you would like to add a different class, for example something like on, specify it here.

selected_class="on"

selected_class_on_parents

NavEE checks to see if the page you are on is the same as any item in your navigation. If so, it appends a class of selected to that item. Sometimes, however, you might want every parent item of the selected node to have a selected class as well. This is nice for showing your users the full path to your item, and also great for revealing hidden tertiary navigation sections. This parameter only accepts true or false as values.

selected_class_on_parents="true"

site_id

If you are using the EllisLab MultiSite Manager (MSM), by default NavEE identifies the site the user is currently in and only outputs navigations for that site. For example, if you had two navigations with the same nav_title for multiple sites, NavEE will use the appropriate navigation for the site you are in.

The site_id parameter allows you to override this functionality. This way, if you want to build a single navigation in site #1 and distribute it across your other MSM sites, you can pass this parameter with the site_id of the appropriate site and NavEE will only output that one.

site_id="2"

skip_closed_entries

If passed, this parameter will skip all nodes created with the Guided or Pages methods that have entries with a status currently set to closed.

skip_closed_entries="true"

start_nav_from_parent

This parameter is used to build dynamic subnavigation. If you set this parameter to true, NavEE will search to find the page you are on in the navigation and then build your navigation starting with the children of the top-most parent of that item. Watch the video tutorial. By default, this will start with the top-most parent, but that can be overridden with the start_nav_from_parent_depth parameter.

start_nav_from_parent="true"

start_nav_from_parent_depth

This parameter is used in conjunction with start_nav_from_parent and allows you to override the default functionality of starting the navigation from the top-most parent. If you want your navigation to start from two levels deep, you would use the following code:

start_nav_from_parent_depth="2"

start_nav_on_level_of_selected

This parameter is used in building dynamic subnavigation. If set to true, this parameter will force NavEE to identify the selected node and build your navigation from the same depth as your selected item. Meaning, any siblings of your selected item will be on the top level of the navigation generated when this parameter is used.

start_nav_on_level_of_selected="true"

start_nav_with_kids_of_selected

Similar to start_nav_on_level_of_selected, but it sets the id of your selected item as the start_node and begins your navigation with the descendants of that item.

start_nav_with_kids_of_selected="true"

start_node

By default, NavEE will begin at the very top of your navigation. If you’d prefer to see only a subsection of your navigation, just pass this parameter. You can easily find the appropriate code by clicking the EE Code button on the node you’d like to start with in your control panel.

Additionally, you can pass a string to the start_node parameter. If the string you pass matches any link field in your control panel, it will start the navigation below that node.

start_node="42"

Or

start_node="/some/string/that/matches/your/link/field"

start_x_levels_above_selected

This parameter is used in building dynamic subnavigation. If you use, for example, the number 2 in this parameter, it will identify the selected item in your tree, move up two nodes, and start the navigation from that point.

start_x_levels_above_selected="2"

var_prefix

If you’re worried about variable name conflicts, you can set a variable prefix. The prefix you choose here needs to precede the variables you’re using. For example, var_prefix="nav" means variable {title} becomes {nav:title}.

var_prefix="nav"

wrap_type

By default, NavEE uses nested unordered lists. You can override this functionality, which will make NavEE wrap any grouping of navigation items in an opening/closing pair of whatever you pass here. wrap_type will also accept a parameter of none which will output no wrapping tags.

wrap_type="table"

Variables for {exp:navee:custom}

accesskey

The accesskey variable outputs any access key you have associated with a NavEE item.

class

The class variable outputs any specific class you have associated with a NavEE item. Additionally, this variable will contain the selected class, and any first/last item classes you may have defined (when applicable).

count

The count variable outputs a running count of the items in your navigation. This is useful for writing conditions based on the nth navigation item in a child group.

custom

The custom variable outputs what you have entered in the Include additional html in li section for each NavEE item.

custom_kids

The custom_kids variable outputs what you have entered in the Include additional html in ul of children section for each NavEE item.

depth_of_selected

The depth_of_selected variable returns the depth of your selected item. In order for this variable to be available, you must pass the get_info_about_selected parameter.

id

The id variable outputs the id associated with each NavEE item.

has_kids

Boolean which returns true if the current element has child elements.

include_in_nav

This will return true or false depending on what you have configured in the “Include In Navigation”:/navee/control-panel/#includeInNavigation section.

is_first_item_on_level

Boolean which returns true for the first item on each level of your navigation.

is_last_item_on_level

Boolean which returns true for the last item on each level of your navigation.

is_previous_item_selected

Boolean which returns true if the item preceding the current item was assigned the class of selected.

is_selected

Boolean which returns true if the current element is the selected node.

kid_count

The kid_count variable outputs the number of child elements the current node has.

kids

If your navigation is more than one level deep, congratulations, you are a parent. Well, not really, but each navigation item that has child nodes beneath it will have the kids tag available to it. By adding this variable, you navigation will become recursive.

level

The level variable outputs which level of navigation you are on. If your navigation is three levels deep, all your top nodes will have a level of 1, the secondary items a level of 2, and so on.

level_count

The level_count variable returns a count of the total number of items on the current level you are on.

The link variable outputs the link associated with each NavEE item.

The link_type variable outputs whether the current link was created using the Manual, Guided or Pages options.

name

The name variable outputs the name attribute associated with each NavEE item (for use in an anchor tag).

An alias for the count variable.

Each NavEE item has a unique identifier, and the navee_id variable outputs it.

navee_entry_id

If your NavEE element was built using either the Guided or the Pages method, the Channel Entry ID associated with that item is available through the navee_entry_id variable. This can be used to pull content from your channel entry into your navigation as necessary.

An alias for the link variable.

An alias for the title variable.

Each NavEE navigation group has a unique identifier, and the navigation_id variable outputs it.

rel

The rel variable outputs the rel attribute associated with each NavEE item (for use in an anchor tag).

selected_has_kids

Boolean which returns true if your selected item has child nodes. In order for this variable to be available, you must pass the get_info_about_selected parameter.

target

The target variable outputs the target attribute associated with each NavEE item (for use in an anchor tag).

title

It is recommended that you use the navee_title tag instead of this one to avoid conflicts with EE’s title tag

The title variable outputs the title attribute associated with each NavEE item (for use in an anchor tag).

text

The text variable outputs the text associated with each NavEE item.