| Sesat > Docs + Support > Development using the SFC > Navigation documentation |
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:
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.
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.
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>
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>
...
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>
...
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>
...