1 Reply Latest reply on Jun 13, 2013 6:06 PM by ranmadxs

    Public API - Quick glance at Navigation


      Since it's been some time since we've last discussed the Public API, I wanted to at least give a quick look at the recent work that has been done with the API and more specifically Navigation. As always you can view the code on github at https://github.com/gatein/gatein-api-java and javadoc here http://gatein.github.com/gatein-api-java/.



      The PortalRequest object contains data relative to the current request of the portal. It can be retrieved by the following:

      PortalRequest portalRequest = PortalRequest.getInstance();



      The Portal object is the main interface of the public API which is used to obtain specific information of the portal. It can be obtained from the PortalRequest object


      Portal portal = portalRequest.getPortal();



      The navigation object is scoped to a specific site and can be used to retreive, delete, and save navigation nodes. It can be obtained either by the current request or specifically from the Portal object.

      Navigation navigation = portalRequest.getNavigation(); // navigation of the current request
      Navigation adminNav = portal.getNavigation(new SiteId(new Group("platform", "administrators")); // navigation of the /platform/administrators group



      The node is a detached object representing the state of the node and the relationship of it's parent and children at the time of retrieval.


      Node homeNode = navigation.getNode("home");
      Node appRegNode = adminNav.getNode("administration", "registry");



      The number of nodes that are loaded are controlled entirely by the user through the NodeVisitor object. For the most part, the NodeVisitor's that are available via the Nodes class are typically enough.


      Node rootNode = navigation.loadNodes(Nodes.visitChildren()); // Returns the root node with it's children loaded
      Node rootNode = navigation.loadNodes(Nodes.visitNodes(2)); // Returns the root node with it's children and children's children loaded.
      Node adminNode = adminNav.getNode(NodePath.path("administration"), Nodes.visitChildren()); // Returns the administration node with it's children loaded



      If any child operation is performed and the node does not have it's children loaded, an IllegalStateException will be thrown. It's very important to call isChildrenLoaded prior to accessing the children of a node.

      if (!adminNode.isChildrenLoaded())
      Node appRegNode = adminNode.getChild("registry");


      DisplayName & Localization

      The node object has a displayName which can be used to display the node in a navigation menu. The displayName can be localized in order to display different text depending on the locale.


      LocalizedString displayName = homeNode.getDisplayName();
      boolean localized = displayName.isLocalized();
      String en = displayName.getValue(Locale.ENGLISH);
      String fr = displayName.getValue(Locale.FRENCH);


      To automatically resolve the proper display name depending on the current request's locale, if it's localized (extended), or even for resource values such as #{my.nav.name} you can just do

      String resolved = homeNode.resolveDisplayName();



      These are just some quick examples of the navigation part of the public API. Look for more information around the public API in the future as we continue to develop this feature for GateIn.