org.zkoss.zuti.zul

Class NavigationModel<T>

java.lang.Object

org.zkoss.zuti.zul.NavigationModel<T>

Type Parameters:

T - The data type

All Implemented Interfaces:

Serializable

public class NavigationModel<T>
extends Object
implements Serializable

A model that accepts arbitrary levels and arbitrary items for navigation. Use with Apply component. A typical usage is that you can get each NavigationLevel by NavigationLevel.getChild() recursively.

Usage

Create a new NavigationModel. Add some data by calling put method. The data is associated with a path. Data is stored like a tree hierarchy.

     NavigationModel<String> navModel = new NavigationModel<String>();
     navModel.put("Step 1", "step1.zul");
     navModel.put("Step 1/Step 1-1", "step1-1.zul");
     navModel.put("Step 2", "step2.zul");
     navModel.put("Step 2/Step 2-1", "step2-1.zul");
     navModel.put("Step 2/Step 2-2", "step2-2.zul");
     navModel.put("Step 2/Step 2-2/Step 2-2-1", "step2-2-1.zul");
     navModel.put("Step 2/Step 2-2/Step 2-2-2", "step2-2-2.zul");
     navModel.put("Step 3", "step3.zul");
 

By using <apply> tags, we can include and navigate this zul files in a single page. Calling navigateTo can navigate to the path. The context is a Map to put something useful.

     <apply level1="@load(vm.navModel.root)"
            templateURI="@load(level1.current)"
            context="@load(level1.context)"/>
 

By using the same approach, get child level navigation recursively in these included zul files.

     <apply level2="@load(level1.child)"
            templateURI="@load(level2.current)"
            context="@load(level2.context)"/>
 

Add a link or button to navigate what you want in the same level. For instance, level1 can be used to navigate through Step 1 to Step 3.

     <a label="Step 2"
           onClick='level1.setContext(Collections.singletonMap("hello", "world")).navigateTo("Step 2")' />
 

Path

A path represents the location of an item. For example, Section B/Sub Section C/My Item. By default it is separated by / symbol and recognized as keys in each level. Sometimes we may want to use / in the key name. Using a path string could get the unexpected result. There are another methods that accept String[] instead of path string to avoid this issue.

Events

If the data in the model is changed or the current navigation is changed, the listeners registered by addEventListener(EventListener) will be invoked. The event object is NavigationEvent.

Since:

8.6.0

Author:

rudyhuang

See Also:

Apply, Serialized Form

Constructor Summary

Constructors

Constructor and Description
NavigationModel()

Method Summary

Modifier and Type	Method and Description
void	addEventListener(org.zkoss.zk.ui.event.EventListener<NavigationEvent<T>> listener) Adds a listener to the list that's notified each time a change to the model occurs.
void	append(String[] levels, String key, T data) Appends the data after the specific path.
void	append(String path, String key, T data) Appends the data after the specific path.
protected void	fireEvent(NavigationLevel<T> level, NavigationEvent.Type type, org.zkoss.zuti.zul.NavigationNode<T> node)
NavigationLevel<T>	getRoot() Gets the first navigation level.
void	insertBefore(String[] levels, String key, T data) Inserts the data before the item of specific levels.
void	insertBefore(String path, String key, T data) Inserts the data before the specific path.
void	navigateTo(String key) A shortcut of getRoot().navigateTo(String).
void	navigateToByPath(String path) Navigates to the specified path.
void	navigateToByPath(String[] levels) Navigates to the specified levels.
T	put(String[] levels, T data) Puts the data to the path.
T	put(String path, T data) Puts the data to the path.
T	remove(String path) Removes the data associated with the specific path.
T	remove(String[] levels) Removes the data associated with the specific levels.
void	removeEventListener(org.zkoss.zk.ui.event.EventListener<NavigationEvent<T>> listener) Removes a listener from the list that's notified each time a change to the model occurs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NavigationModel

public NavigationModel()

Method Detail

put

public T put(String path,
             T data)

Puts the data to the path. It will replace the data of the path if the previous data associated with path exists. If any / symbol is included in the path string, it is suggested to call put(String[], Object) instead.

Parameters:

path - a path string. Will be separated into levels by / symbols. Like A/B/C

data - a data

Returns:

the previous data associated with path, or null if there was no mapping.

put

public T put(String[] levels,
             T data)

Puts the data to the path. It will replace the data of the path if the previous data associated with levels exists.

Parameters:

levels - an array that contains each level keys as a path

data - a data

Returns:

the previous data associated with levels, or null if there was no mapping.

append

public void append(String path,
                   String key,
                   T data)

Appends the data after the specific path. If the path is invalid, the appending will be failed. If the key is duplicated in the same level, the appending will be failed, too.

Parameters:

path - a path string. Will be separated into levels by / symbols. Like A/B/C

key - an item key. Must be unique in the same level

data - a data

Throws:

IllegalArgumentException - if the path is invalid, the key is invalid or duplicated in the same level

append

public void append(String[] levels,
                   String key,
                   T data)

Appends the data after the specific path. If the path is invalid, the appending will be failed. If the key is duplicated in the same level, the appending will be failed, too.

Parameters:

levels - an array that contains each level keys as a path

key - an item key. Must be unique in the same level

data - a data

Throws:

IllegalArgumentException - if the path is invalid, the key is invalid or duplicated in the same level

insertBefore

public void insertBefore(String path,
                         String key,
                         T data)

Inserts the data before the specific path. If the path is invalid, the insertion will be failed. If the key is duplicated in the same level, the insertion will be failed, too.

Parameters:

path - a path string. Will be separated into levels by / symbols. Like A/B/C

key - an item key. Must be unique in the same level

data - a data

Throws:

IllegalArgumentException - if the path is invalid, the key is invalid or duplicated in the same level

insertBefore

public void insertBefore(String[] levels,
                         String key,
                         T data)

Inserts the data before the item of specific levels. If the path is invalid, the insertion will be failed. If the key is duplicated in the same level, the insertion will be failed, too.

Parameters:

levels - an array that contains each level keys as a path

key - an item key. Must be unique in the same level

data - a data

Throws:

IllegalArgumentException - if the path is invalid, the key is invalid or duplicated in the same level

remove

public T remove(String path)

Removes the data associated with the specific path. If the path is navigated currently, the navigation of that level will be changed to the sibling (right or left).

Parameters:

path - a path string. Will be separated into levels by / symbols. Like A/B/C

Returns:

the previous data.

Throws:

IllegalArgumentException - the path is invalid

remove

public T remove(String[] levels)

Removes the data associated with the specific levels. If the path is navigated currently, the navigation of that level will be changed to the sibling (right or left).

Parameters:

levels - an array that contains each level keys as a path

Returns:

the previous data.

Throws:

IllegalArgumentException - the path is invalid

navigateTo

public void navigateTo(String key)

A shortcut of getRoot().navigateTo(String).

Parameters:

key - the item key

getRoot

public NavigationLevel<T> getRoot()

Gets the first navigation level.

Returns:

the first navigation level

navigateToByPath

public void navigateToByPath(String path)

Navigates to the specified path. If the key could not be found in the specific level, the action will not be performed.

Parameters:

path - a path string. Will be separated into levels by / symbols. Like A/B/C

Throws:

IllegalArgumentException - if the path is invalid

navigateToByPath

public void navigateToByPath(String[] levels)

Navigates to the specified levels. If the key could not be found in the specific level, the action will not be performed.

Parameters:

levels - an array that contains each level keys as a path

Throws:

IllegalArgumentException - if the path is invalid

addEventListener

public void addEventListener(org.zkoss.zk.ui.event.EventListener<NavigationEvent<T>> listener)

Adds a listener to the list that's notified each time a change to the model occurs.

Parameters:

listener - Listener object

removeEventListener

public void removeEventListener(org.zkoss.zk.ui.event.EventListener<NavigationEvent<T>> listener)

Removes a listener from the list that's notified each time a change to the model occurs.

Parameters:

listener - Listener object

fireEvent

protected void fireEvent(NavigationLevel<T> level,
                         NavigationEvent.Type type,
                         org.zkoss.zuti.zul.NavigationNode<T> node)