Class 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