Renderer::List

mjtko edited this page Mar 24, 2012 · 8 revisions

When using this renderer your navigation will be displayed as Html list, e.g.

<ul>
  <li id="books"><a href="/books">Books</a></li>
  <li id="music" class="selected"><a href="/musics" class="selected">Music</a></li>
  <li id="dvds"><a href="/dvds">Dvds</a></li>
</ul>

An Html list is very easy to style with css (see Styling) and will be the right renderer for you in almost all cases. To render your navigation as Html list you don’t have to specify a renderer since it is the default case.

You can pass the following options to render_navigation when using the Html list renderer:

  • :level – this option determines which parts of your navigation are rendered with this render_navigation call. Use :level => :all to render all your levels at once. Use :level => 1 to render just the first level of your navigation. Use :level => 1..2 to render the first two levels of your navigation. Defaults to :all. See the code examples below for details.
  • :expand_all – Set :expand_all => true to render your navigation as a fully expanded tree. This is useful for javascript style menus like Superfish. Defaults to false.
  • :skip_if_empty – Set this option to true if you are rendering a specific level and you don’t want the renderer to output an empty ul tag if there are no navigation items for that level.
  • :context – specifies the context for which you would render the navigation. Defaults to :default which loads the default navigation.rb (i.e. config/navigation.rb). If you specify a context then the plugin tries to load the configuration file for that context, e.g. if you call render_navigation(:context => :admin) the file config/admin_navigation.rb will be loaded and used for rendering the navigation. This is very useful for allowing multiple completely separate menus within a single application.
  • :ordered – if true specifies that the list should be rendered with a <ol> element rather than the usual <ul> element. Defaults to false. (from 3.8.0+)

The following examples show how to use render_navigation to render your navigation as Html list.

Nested Navigation (like a Tree)

Call

render_navigation

without any parameter to render all defined levels of navigation nested into each other (like a tree). By default, only the sub navigations of active parent items are rendered (see the section about how to set the active item above). If you want to render all the sub navigations at once (i.e. a fully expanded navigation tree – useful for javascript menus) you have to pass the option :expand_all => true.

Separately render specific levels

If you have to render your sub navigation independently from the navigation containing it (e.g. you render your primary navigation horizontally on the top of the page and the sub navigation vertically on the left of the page in a sidebar), then you specify the level when calling render_navigation

render_navigation(:level => 1)

This renders your primary navigation (‘Books’, ‘Music’, ‘Dvds’). To render the sub navigation, call

render_navigation(:level => 2)

This renders the current sub navigation (i.e. ‘Fiction’, ‘History’, ‘Sports’ if the ‘Books’ primary navigation item is active).

If you have more than two levels, you can also specify ranges. For example, let’s consider the following setup:

You have a navigation with three levels. The first two levels should be rendered as a navbar-style javascript menu using superfish. The third level should be rendered separately in a sidebar. To achieve this you would have the following code in your view (using HAML):

#top_navigation= render_navigation(:level => 1..2, :expand_all => true)
#sidebar= render_navigation(:level => 3)

:javascript
  $(document).ready(function(){ 
    $("#top_navigation ul").superfish(); 
  });