Sesat > Docs + Support > Development using the SFC > Navigation documentation

Contents

Concepts

The navigation model is built around the object NavigationItem. A NavigationItem, extends a ResultList and, has basically four aspects viewed from the view generation side.

The core aspects of a navigators:

  • Selected: Is this navigator selected? This is a indication if this navigator has been chosen by the user. In some cases a navigator can be chosen by default. This is controlled by configuration.
  • HitCount: In many cases a navigator is a representation of a search. The hitcount indicates the expected number of hits you will get when you do this search. (At the time of writing this functionality only works for fast navigators). [inherited from ResultList]
  • Url: The url to this navigation. To "select" this navigator, go to this url. [inherited from ResultItem]
  • Title: The title of this navigator. This should be used in the display text of the navigator. [inherited from ResultItem]

Optimally all navigation on a page should be represented as NavigationItems. If you do, you will be able to write more generic velocity code, and you don't need to worry about url generation in the view layer.

These NavigationItems are just plain old java objects intended only for data transfer. There are constructed by the configured NavigationController inside the NavigationRunHandler. This NavigationRunHandler is hardcoded into the RunningQuery and automatically detects the following navigation configuration.

Configuration

Navigation is configured in xml. The configuration describes how searcResults are used to generate the hitCounters, and how the URL's should be built to navigate in and out of the page.

The navigation configuration concept was written in answer to all the view code made to solve navigation in a page.

If you want to add a navigation to a mode you need to add the navigation element to that mode. An navigation may contain one or more navigation elements. And that navigation in turn must contain a nav element, to define the navigator.

A nav element can be linked to a searchResult (by commandName), contain predefined options or even a combination.

Nav predefined options

If you want to add a pure predefined navigation, you just supply those option in the <nav> element. For a pure predefined navigator, hitCount is not set.

Example under shows how you can add a sort navigation.

<navigation>
   <navigation>
      <nav id="sort">
         <option value="descending" display-name="nyest først"/>
         <option value="ascending" display-name="eldst først"/>
      </nav>
   </navigation>
</navigation>

This configuration will present two navigators, on the key "sort". In velocity to access the defined navigators:

#set ($sort = $datamodel.navigation.getNavigation('sort'))
#foreach($sortType in $sort)
   <a href="/search/?$sortType.url" >$sortType.title</a>
#end

Will result in the following html:

<a href="/search/?c=m&sort=descending"  >nyest først</a>
<a href="/search/?c=m&sort=ascending"  >eldst først</a>

The default behavior is that the "c" parameter will stick to the one active for the page you are using. You can override this by setting tab="something" in the nav and/or option.

...
      <nav id="sort" tab="b">
         <option value="descending" display-name="nyest først" default-select="true"/>
         <!-- Tab on a option "overrides" the one in nav -->
         <option value="ascending" tab="a" display-name="eldst først"/>
      </nav>
...

The above velocity code will then result in the following html:

<a href="/search/?c=b&sort=descending" >nyest først</a>
<a href="/search/?c=a&sort=ascending" >eldst først</a>

Now we want to show that the default sorting is descending. So we need to set a default-select. This requires that the searchCommand actually uses descending sort if none was supplied.

...
   <navigation>
      <nav id="sort">
         <option value="descending" display-name="nyest først" default-select="true"/>
         <option value="ascending" display-name="eldst først"/>
      </nav>
   </navigation>
...

We change the velocity code to not make a link if a navigation is selected.

#set ($sort = $datamodel.navigation.getNavigation('sort'))
#foreach($sortType in $sort)
   #if($sortType.selected)
      <!-- Displaying the selected sort -->
      $sortType.title
   #else
      <a href="/search/?$sortType.url" >$sortType.title</a>
   #end
#end

Results in the following html:

<!-- Displaying the selected sort -->
   nyest først
   <a href="/search/?c=m&sort=ascending" >eldst først</a>

Linking navigation to a searchCommand

In many cases you want navigation to be dynamic, depending on the search that was run. At the time of writing, only fast navigators are supported from the searchCommands.

You need to define the navigators in the search command to make the navigators able to access them.

For a typical news search you, may want to display navigators per year. A typical configuration for this could be:

<mode>
   <navigation>
      <navigation command-name="newsSearch">
         <nav id="year"/>
      </navigation>
   </navigation>

   <clustering-esp-fast-command id="newsSearch">
      <navigators>
         <navigator id="year" field="year" name="yearnavigator" display-name="År" sort="YEAR"/>
      </navigators>
   </clustering-esp-fast-command>
</mode>

You need to "link" the navigation element to a command by supplying the command-name in the navigation element. When generating navigators, the navigation system will use the results from this search. It will look for a navigator in the searchResult, with id equal to the id of the navigation element.

Velocity code for displaying the navigator:

#set ($years = $datamodel.navigation.getNavigation('year'))
#foreach($year in $years)
   #if($year.selected)
      <!-- Displaying the selected year -->
      <p>$year.title</p>
   #else
      <p><a href="/search/?$year.url" >$year.title</a> $year.hitCount</p>
   #end
#end

Depends on the search, but an example result could be:

<p><a href="/search/?c=m&year=2007&nav_year=yearnavigator"  >2007</a> 583</p>
<p><a href="/search/?c=m&year=2006&nav_year=yearnavigator"  >2006</a> 1786</p>
 <!-- Displaying the selected year -->
<p>2005</p>

As you see here, when you link navigation to a fast navigator you get two parameters. The year= and the nav_year=. If the navigators are for some reason available from the search command, and you want to suppress the nav_year=, you can set the parameter real-navigator=false on the nav element.

...
   <navigation command-name="newsSearch">
      <nav id="year" real-navigator="false"/>
   </navigation>
...

Linking navigation with predefined options

In some cases it will make sense to only display chosen navigator elements with counters. This can be done if you link navigation to a Search, but supply the options that you want to display.

...
<navigation id="newscategory">
   <nav tab="m" id="medium" command-name="newsSearchNavigator" real-navigator="false" out="true">
      <option value="webnewsarticle" display-name="Norske nyheter"/>
      <option value="printnewsarticle" display-name="Norske papiraviser"/>
   </nav>
</navigation>
...

Combining navigation and the <reset-nav> element

So, if you want to combine both a navigation on year, and want the results be be sortable you just combine the configuration from the above examples:

<mode>
   <navigation>
      <navigation>
         <nav id="sort">
            <option value="descending" display-name="nyest først" default-select="true"/>
            <option value="ascending" display-name="eldst først"/>
         </nav>
      </navigation>
      <navigation command-name="newsSearch">
         <nav id="year"/>
      </navigation>
   </navigation>

   <clustering-esp-fast-command id="newsSearch">
      <navigators>
         <navigator id="year" field="year" name="yearnavigator" display-name="År" sort="YEAR"/>
      </navigators>
   </clustering-esp-fast-command>
</mode>

If you use this, navigation will "stick" on all urls. That mean that if you click on sort, that sort whill stick on all year urls generated for the page.

In some cases you don't want all navigation to stick on certain clicks. To support this behavior you need to use the <reset-nav> element.

In the example over we want the sort, to always be descending when you display a new result. So we want sort to reset when you click year. This can be done by adding a <reset-nav> to the year navigation.

...
      <navigation command-name="newsSearch">
         <nav id="year"/>
         <reset-nav id="sort"/>
      </navigation>
...
 © 2007-2009 Schibsted ASA
Contact us