Package 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:
    `java.io.Serializable`

      public class NavigationModel<T>
      extends java.lang.Object
      implements java.io.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 | Description
    --- | ---
    `NavigationModel()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addEventListener​(EventListener<NavigationEvent<T>> listener)` | Adds a listener to the list that's notified each time a change to the model occurs.
    `void` | `append​(java.lang.String[] levels, java.lang.String key, T data)` | Appends the data after the specific path.
    `void` | `append​(java.lang.String path, java.lang.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​(java.lang.String[] levels, java.lang.String key, T data)` | Inserts the data before the item of specific levels.
    `void` | `insertBefore​(java.lang.String path, java.lang.String key, T data)` | Inserts the data before the specific path.
    `void` | `navigateTo​(java.lang.String key)` | A shortcut of `getRoot()`.`navigateTo(String)`.
    `void` | `navigateToByPath​(java.lang.String path)` | Navigates to the specified path.
    `void` | `navigateToByPath​(java.lang.String[] levels)` | Navigates to the specified levels.
    `T` | `put​(java.lang.String[] levels, T data)` | Puts the data to the path.
    `T` | `put​(java.lang.String path, T data)` | Puts the data to the path.
    `T` | `remove​(java.lang.String path)` | Removes the data associated with the specific path.
    `T` | `remove​(java.lang.String[] levels)` | Removes the data associated with the specific levels.
    `void` | `removeEventListener​(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​(java.lang.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​(java.lang.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​(java.lang.String path,
                             java.lang.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:
        `java.lang.IllegalArgumentException` - if the path is invalid, the key is invalid or duplicated in the same level

    - #### append

          public void append​(java.lang.String[] levels,
                             java.lang.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:
        `java.lang.IllegalArgumentException` - if the path is invalid, the key is invalid or duplicated in the same level

    - #### insertBefore

          public void insertBefore​(java.lang.String path,
                                   java.lang.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:
        `java.lang.IllegalArgumentException` - if the path is invalid, the key is invalid or duplicated in the same level

    - #### insertBefore

          public void insertBefore​(java.lang.String[] levels,
                                   java.lang.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:
        `java.lang.IllegalArgumentException` - if the path is invalid, the key is invalid or duplicated in the same level

    - #### remove

          public T remove​(java.lang.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:
        `java.lang.IllegalArgumentException` - the path is invalid

    - #### remove

          public T remove​(java.lang.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:
        `java.lang.IllegalArgumentException` - the path is invalid

    - #### navigateTo

          public void navigateTo​(java.lang.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​(java.lang.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:
        `java.lang.IllegalArgumentException` - if the path is invalid

    - #### navigateToByPath

          public void navigateToByPath​(java.lang.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:
        `java.lang.IllegalArgumentException` - if the path is invalid

    - #### addEventListener

          public void addEventListener​(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​(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)