Navigation Concepts

The goal of the Riena navigation concept is to make navigation as easy and comfortable as possible for the enterprise user.

Subapplications

The Riena application ist made up from possibly multiple subapplications identifyable by the handles in the top area of the application window.

This example shows a Riena client application with 2 subapplications called 'Navigation' and 'Playground'. The 'Navigation' subapplication is currently selected.

Module Groups, Modules and Submodules

Each subapplication may contain multiple module groups, each module group may contain multiple modules and each module may contain multiple submodules. Submodules may be organized in a hierarchical way, ie a submodul may have zero (probably the most common case), one or more submodules as children.

The picture to the left shows 3 module groups, the first one containing two modules (named 'Module 1' and 'M2 (not closable)'). The second and third module group each contain one module only (named 'Module 1.2.1' and 'Navigate', resp). The modules named 'M2 (not closable)' Module 1.2.1' cannot be closed by the user indicated by the absence of the 'X' button in the right corner of the module widget.

Note that only the first module within the first module group is expanded, ie its submodules are visible within the navigation tree. This is because that module is currently selected.
We can also see that the first submodule (named 'SubModule 1.1') is the parent of another submodule (named 'SubModule 1.1.1') and has a sibling (named 'SubModule 1.2') within the same module.
Selecting a subapplication, module group or module automatically activates the first submodule within that context. This implies the there is no work area associated with modules, module groups or subapplications - only submodules can have an associated work area (ie view and optionally a controller)

The Riena navigation therefore can be thought of as a tree where the root is the application node and the leafs are the submodule nodes.

Navigation Node Common Properties

There are some properties that can be defined for all navigation nodes:

id - The id is made up from two parts, a type and an instance part. This is explained later on this page.

children - The type of children depends on the parent, a module node eg can only have submodule nodes as children.

Navigation nodes except module group nodes may also have a label and/or an icon.

Programmatic Creation

All navigation structures may easily be created programmatically. If the application class configured in extension org.eclipse.core.runtime.applications extends org.eclipse.riena.navigation.ui.application.AbstractApplication the method createModel() would be sent within the start(IApplicationContext context) method.
The default implementation just returns an application node without any children:

All navigation node interfaces extend a common super interface, org.eclipse.riena.navigation.INavigationNode. The implementation classes form a corresponding hierarchy where all non abstract navigation node classes inherit from org.eclipse.riena.navigation.model.NavigationNode:

Using Custom createModel() method

Let's now try to create the 'Navigation' subapplication and the first module group from the screenshot above. We start our implementation of the createModel() method with a call to the super implemetantion to receive an IApplicationNode and configure label and application icon:

Creating a Subapplication

To be able to create a subapplication we need one more thing:
As subapplications in Riena correspond to RCP perspectives we need to contribute the corresponding extension. The view class representing the subapplication perspective in Riena is org.eclipse.riena.navigation.ui.swt.views.SubApplicationView, so we will configure our subapplication as follows (of course the id is not required to be 'subapplication.1'):

This would bring up the Riena application with one subapplication called 'Navigation' that does not contain any content (please ignore menu and toolbar for now - those are there because I lazily abused the Riena example client and did not remove them):

Creating a Module Group

Creating a module group is rather easy in as there is no label, icon or work area that could require configuration. As we also do not need a node id here we can simply write:

// create a module group and add it to subapplication
IModuleGroupNode moduleGroup =new ModuleGroupNode(null);
subApplication.addChild(moduleGroup);

This does not change anything in the visualization of our example client as we do not yet have any modules within or module group and empty groups are not displayed. Therefore let's proceed creating our first module...

That's all for the programmatic creation of the navigation tree basics. Now let's have a look how this could be achieved using the declarative way.

Using Extension Points

All navigation structures may also be created in a declarative way using extension points. Just like if using the programmatic approach the application class configured in extension org.eclipse.core.runtime.applications is required to extend org.eclipse.riena.navigation.ui.application.AbstractApplication so the method createModel() will be sent within the start(IApplicationContext context) method.
The application class is (except for your view and controller implementations, of course) the only java code that is required to create exactly the same navigation structure as we did before the programmatic way.

Using Custom createModel() method

The implementation of the createModel() method is really only required to set label and icon of the application, we will not add any more code to this method:

This would bring up the same Riena application with one subapplication called 'Navigation' not containing any content like in the first step of the programmatic example:

Creating a Module Group

Creating a module group just requires adding the modulegroup element to our subapplication element. There are no attributes required but we will assign a name so we can easily identify it within the PDE:

<subapplicationlabel="Navigation"typeId="org.eclipse.riena.example.navigation.subapplication"view="subapplication.1"><!-- create module group and add it subapplication --><modulegroupname="group"></modulegroup></subapplication>

This does not change anything in the visualization of our example client as we do not yet have any modules within or module group and empty groups are not displayed. Therefore let's again proceed creating our module...

Creating a Module

As you may have already guessed there is also a module element that can be added as a child to the modulegroup element:

Tis concludes the extension point section of the navigation tree basics.

Navigation Node Assemblers

Assembler Basics

As you have seen in the previous section the extension point contains assembly elements. These elements decribe how a certain part of the Riena navigation tree is going to be 'assembled'.
Basically there are two options

Custom Assemblers provide the user with the option to create parts of the navigation tree structure in a programmatic way without using any additional xml. A custom assembler would create navigation nodes just the way we did within the createModel() method of the programmatic example. A custom assembler MUST implement the interface org.eclipse.riena.navigation.INavigationAssembler

Generic Assemblers are prepared to use the element structure provided within the assembly element. Generic Assemblers MUST implement the org.eclipse.riena.navigation.IGenericNavigationAssembler interface. There is a default implementation of a generic assembler, org.eclipse.riena.navigation.model.GenericNavigationAssembler, that will be used if no assembler is specified.

Generic Assembler Reference

assembly

attributes

name

id

assembler

parentTypeId

autostartsequence

ref

subelements

subapplication or modulegroup or module or submodule

subapplication

attributes

name

typeId

instanceId

label

icon

view

subelements

any combination of an arbitrary number of modulegroup and/or assembly elements

modulegroup

attributes

name

typeId

instanceId

subelements

any combination of an arbitrary number of module and/or assembly elements

module

attributes

name

typeId

instanceId

label

icon

unclosable

subelements

any combination of an arbitrary number of submodule and/or assembly elements

submodule

attributes

name

typeId

instanceId

label

icon

view

controller

shared

subelements

any combination of an arbitrary number of submodule, foreach and/or assembly elements