Using Complex UI Components

Creating a Menu Model

Use the oracle.adf.view.faces.model.MenuModel, oracle.adf.view.faces.model.ChildPropertyTreeModel, and oracle.adf.view.faces.model.ViewIdPropertyMenuModel classes to create a menu model that dynamically generates a menu hierarchy.

To create a menu model:

1. Create a class that can get and set the properties for each item in the menu hierarchy or tree.

   For example, each item in the tree needs to have a label, a viewId, and an outcome property. If items have children (for example, a menu tab item can have children menu bar items), you need to define a property to represent the list of children (for example, children property). To determine whether items are shown or not shown on a page depending on security roles, define a boolean property (for example, shown property). Example: MenuItem.java for All Menu Items shows the MenuItem class used in the SRDemo application.

   MenuItem.java for All Menu Items

   package oracle.srdemo.view.menu;
   import java.util.List;
   import oracle.adf.view.faces.component.core.nav.CoreCommandMenuItem;
   public class MenuItem {
       private String _label          = null;
       private String _outcome        = null;
       private String _viewId         = null;
       private String _destination    = null;
       private String _icon           = null;
       private String _type           = CoreCommandMenuItem.TYPE_DEFAULT;
       private List   _children       = null;
       //extended security attributes
       private boolean _readOnly = false;
       private boolean _shown = true; 
       public void setLabel(String label) {
           this._label = label;
       }
       public String getLabel() {
           return _label;
       }
    // getter and setter methods for remaining attributes omitted
   }
   
   

   
   

   Note: The type property defines a menu item as global or nonglobal. Global items can be accessed from any page in the application. For example, a Help button on a page is a global item.

   
   

2. Configure a managed bean for each menu item or page in the hierarchy, with values for the properties that require setting at instantiation.

   Each bean should be an instance of the menu item class you create in step 1. Example: Managed Beans for Menu Items in the faces-config.xml File shows the managed bean code for all the menu items in the SRDemo application. If an item has children items, the list entries are the children managed beans listed in the order you desire. For example, the Management menu tab item has two children.

   Typically each bean should have none as its bean scope. The SRDemo application, however, uses session scoped managed beans for the menu items because security attributes are assigned to the menu items when they are created dynamically, and the SRDemo application uses a session scoped UserInfo bean to hold the user role information for the user currently logged in. The user role information is used to determine which menu items a user sees when logged in. For example, only users with the user role of 'manager' see the Management menu tab. JSF doesn't let you reference a session scoped managed bean from a none scoped bean; therefore, the SRDemo application uses all session scoped managed beans for the menu system.

   Managed Beans for Menu Items in the faces-config.xml File

   <!-- If you were to use dynamically generated global buttons -->
   <!-- Root pages: Two global button menu items -->
   <managed-bean>
     <managed-bean-name>menuItem_GlobalLogout</managed-bean-name>
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope>
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.logout']}</value>
     </managed-property>
     <managed-property>
       <property-name>icon</property-name>
       <value>/images/logout.gif</value>
     </managed-property>
     <managed-property>
       <property-name>type</property-name>
       <value>global</value>
     </managed-property>    
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/SRLogout.jsp</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>GlobalLogout</value>
     </managed-property>
   </managed-bean>
   
   <managed-bean>
     <managed-bean-name>menuItem_GlobalHelp</managed-bean-name>
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope>
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.help']}</value>
     </managed-property>
     <managed-property>
       <property-name>icon</property-name>
       <value>/images/help.gif</value>
     </managed-property>
     <managed-property>
       <property-name>type</property-name>
       <value>global</value>
     </managed-property>
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/SRHelp.jspx</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>GlobalHelp</value>
     </managed-property>
   </managed-bean>
   
   <!-- Root pages: Four menu tabs -->
   <!-- 1. My Service Requests menu tab item -->
   <managed-bean>
     <managed-bean-name>menuItem_MyServiceRequests</managed-bean-name>
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope> 
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.my']}</value>
     </managed-property>
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/SRList.jspx</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>GlobalHome</value>
     </managed-property>
   </managed-bean>
   
   <!-- 2. Advanced Search menu tab item -->
   <managed-bean>
     <managed-bean-name>menuItem_AdvancedSearch</managed-bean-name>  
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope> 
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.advanced']}</value>
     </managed-property>
     <managed-property>
       <property-name>shown</property-name>
       <value>#{userInfo.staff}</value>
     </managed-property>
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/staff/SRSearch.jspx</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>GlobalSearch</value>
     </managed-property>
   </managed-bean>
   
   <!-- 3. New Service Request menu tab item -->
   <managed-bean>
     <managed-bean-name>menuItem_New</managed-bean-name>  
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope> 
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.new']}</value>
     </managed-property>
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/SRCreate.jspx</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>GlobalCreate</value>
     </managed-property>
   </managed-bean>
   
   <!-- 4. Management menu tab item -->
   <!-- This managed bean uses managed bean chaining for children menu items --> 
   <managed-bean>
     <managed-bean-name>menuItem_Manage</managed-bean-name>  
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope> 
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.manage']}</value>
     </managed-property>
     <managed-property>
       <property-name>shown</property-name>
       <value>#{userInfo.manager}</value>
     </managed-property>
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/management/SRManage.jspx</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>GlobalManage</value>
     </managed-property>
     <managed-property>
       <property-name>children</property-name>
       <list-entries>
         <value-class>oracle.srdemo.view.menu.MenuItem</value-class>
         <value>#{subMenuItem_Manage_Reporting}</value>
         <value>#{subMenuItem_Manage_ProdEx}</value>
       </list-entries>
     </managed-property>
   </managed-bean>
   <!-- Children menu bar items for Management tab -->
   <managed-bean>
     <managed-bean-name>subMenuItem_Manage_Reporting</managed-bean-name>  
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope> 
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.manage.reporting']}</value>
     </managed-property>
     <managed-property>
       <property-name>shown</property-name>
       <value>#{userInfo.manager}</value>
     </managed-property>    
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/management/SRManage.jspx</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>GlobalManage</value>
     </managed-property>
   </managed-bean> 
   <managed-bean>
     <managed-bean-name>subMenuItem_Manage_ProdEx</managed-bean-name>  
     <managed-bean-class>oracle.srdemo.view.menu.MenuItem</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope> 
     <managed-property>
       <property-name>label</property-name>
       <value>#{resources['srdemo.menu.manage.prodEx']}</value>
     </managed-property>
     <managed-property>
       <property-name>shown</property-name>
       <value>#{userInfo.manager}</value>
     </managed-property>    
     <managed-property>
       <property-name>viewId</property-name>
       <value>/app/management/SRSkills.jspx</value>
     </managed-property>
     <managed-property>
       <property-name>outcome</property-name>
       <value>Skills</value>
     </managed-property>
   </managed-bean>   
   

   
   

   Note: As you see in Figure: Dynamic Navigation Menus in the SRDemo Application, the Management menu tab has a menu bar with two items: Overview and Technician Skills. As each menu item has its own page or managed bean, so the two items are represented by these managed beans, respectively: subMenuItem_Manage_Reporting and subMenuItem_Manage_ProdEx. The Management menu tab is represented by the menuItem_Manage managed bean, which uses value binding expressions (such as #{subMenuItem_Manage_ProdEx}) inside the list value elements to reference the children managed beans.

   
   

3. Create a class that constructs a ChildPropertyTreeModel instance. The instance represents the entire tree hierarchy of the menu system, which is later injected into a menu model. Example: MenuTreeModelAdapter.java for Holding the Menu Tree Hierarchy shows the MenuTreeModelAdapter class used in the SRDemo application.

   MenuTreeModelAdapter.java for Holding the Menu Tree Hierarchy

   package oracle.srdemo.view.menu;
   import java.beans.IntrospectionException;
   import java.util.List;
   import oracle.adf.view.faces.model.ChildPropertyTreeModel;
   import oracle.adf.view.faces.model.TreeModel;
    
   public class MenuTreeModelAdapter {
       private String _propertyName = null;
       private Object _instance = null;
       private transient TreeModel _model = null;
    
       public TreeModel getModel() throws IntrospectionException
       {
         if (_model == null)
         {
           _model = new ChildPropertyTreeModel(getInstance(), getChildProperty());
         }
         return _model;
       }
    
       public String getChildProperty()
       {
         return _propertyName;
       }
       /**
        * Sets the property to use to get at child lists
        * @param propertyName
        */
       public void setChildProperty(String propertyName)
       {
         _propertyName = propertyName;
         _model = null;
       }
    
       public Object getInstance()
       {
         return _instance;
       }
       /**
        * Sets the root list for this tree.
        * @param instance must be something that can be converted into a List
        */
       public void setInstance(Object instance)
       {
         _instance = instance;
         _model = null;
       }
       /**
        * Sets the root list for this tree.
        * This is needed for passing a List when using the managed bean list  
        * creation facility, which requires the parameter type of List.
        * @param instance the list of root nodes
        */
       public void setListInstance(List instance)
       {
         setInstance(instance);
       }  
   }
   
   

4. Configure a managed bean to reference the menu tree model class in step 3. The bean should be instantiated with a childProperty value that is the same as the property value that represents the list of children as created on the bean in step 1.

   The bean should also be instantiated with a list of root pages (listed in the order you desire) as the value for the listInstance property. The root pages are the global button menu items and the first-level menu tab items, as shown in Example: Managed Beans for Menu Items in the faces-config.xml File. Example: Managed Bean for Menu Tree Model in the faces-config.xml File shows the managed bean for creating the menu tree model.

   Managed Bean for Menu Tree Model in the faces-config.xml File

   <managed-bean>
     <managed-bean-name>menuTreeModel</managed-bean-name>
     <managed-bean-class>
       oracle.srdemo.view.menu.MenuTreeModelAdapter
     </managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope>
     <managed-property>
       <property-name>childProperty</property-name>
       <value>children</value>
     </managed-property>
     <managed-property>
       <property-name>listInstance</property-name>
       <list-entries>
         <value-class>oracle.srdemo.view.menu.MenuItem</value-class>
         <value>#{menuItem_GlobalLogout}</value>
         <value>#{menuItem_GlobalHelp}</value>
         <value>#{menuItem_MyServiceRequests}</value>
         <value>#{menuItem_AdvancedSearch}</value>
         <value>#{menuItem_New}</value>
         <value>#{menuItem_Manage}</value>
       </list-entries>
     </managed-property>
   </managed-bean>
   
   

5. Create a class that constructs a ViewIdPropertyMenuModel instance. The instance creates a menu model from the menu tree model. Example: MenuModelAdapter.java shows the MenuModelAdapter class used in the SRDemo application.

   MenuModelAdapter.java

   package oracle.srdemo.view.menu;
   import java.beans.IntrospectionException;
   import java.io.Serializable;
   import java.util.List;
   import oracle.adf.view.faces.model.MenuModel;
   import oracle.adf.view.faces.model.ViewIdPropertyMenuModel;
   public class MenuModelAdapter implements Serializable {
       private           String    _propertyName = null;
       private           Object    _instance = null;
       private transient MenuModel _model = null;
       private           List      _aliasList = null;
    
       public MenuModel getModel() throws IntrospectionException
       {
         if (_model == null)
         {
           ViewIdPropertyMenuModel model = 
                                  new ViewIdPropertyMenuModel(getInstance(),
                                                              getViewIdProperty());
                                                              
           if(_aliasList != null && !_aliasList.isEmpty())    
           {
             int size = _aliasList.size();
             if (size % 2 == 1)
               size = size - 1;
               
             for ( int i = 0; i < size; i=i+2)
             {
               model.addViewId(_aliasList.get(i).toString(),
                              _aliasList.get(i+1).toString());
             }
           }
           
           _model = model;
         }
         return _model;
       }
    
       public String getViewIdProperty()
       {
         return _propertyName;
       }
       /**
        * Sets the property to use to get at view id
        * @param propertyName
        */
       public void setViewIdProperty(String propertyName)
       {
         _propertyName = propertyName;
         _model = null;
       }
    
       public Object getInstance()
       {
         return _instance;
       }
       /**
        * Sets the treeModel
        * @param instance must be something that can be converted into a TreeModel
        */
       public void setInstance(Object instance)
       {
         _instance = instance;
         _model = null;
       }
       
       public List getAliasList()
       {
         return _aliasList;
       }
       public void setAliasList(List aliasList)
       {
         _aliasList = aliasList;
       }  
   }
   
   

6. Configure a managed bean to reference the menu model class in step 5. This is the bean to which all the menu components on a page are bound.

   The bean should be instantiated with the instance property value set to the model property of the menu tree model bean configured in step 4. The instantiated bean should also have the viewIdProperty value set to the viewId property on the bean created in step 1. Example: Managed Bean for Menu Model in the faces-config.xml File shows the managed bean code for creating the menu model.

   Managed Bean for Menu Model in the faces-config.xml File

   <!-- create the main menu menuModel -->
   <managed-bean>
     <managed-bean-name>menuModel</managed-bean-name>
     <managed-bean-class>
       oracle.srdemo.view.menu.MenuModelAdapter</managed-bean-class>
     <managed-bean-scope>session</managed-bean-scope>
     <managed-property>
       <property-name>viewIdProperty</property-name>
       <value>viewId</value>
     </managed-property>
     <managed-property>
       <property-name>instance</property-name>
       <value>#{menuTreeModel.model}</value>
     </managed-property>
   </managed-bean>
   
   

package oracle.srdemo.view.resources;
import oracle.srdemo.view.util.JSFUtils;
/**
 * Utility class that allows us to expose the specified resource bundle within
 * general EL
 */
public class ResourceAdapter implements Map {
    
    public Object get(Object resourceKey) {
        return JSFUtils.getStringFromBundle((String)resourceKey);
    }
 // Rest of file omitted from here
}
...
/** From JSFUtils.java */
package oracle.srdemo.view.util;
import java.util.MissingResourceException;
import java.util.ResourceBundle;
...
public class JSFUtils {
    private static final String NO_RESOURCE_FOUND = "Missing resource: ";
    /**
       * Pulls a String resource from the property bundle that
       * is defined under the application's message-bundle element in
       * faces-config.xml. Respects Locale.
       * @param key
       * @return Resource value or placeholder error String
       */
    public static String getStringFromBundle(String key) {
        ResourceBundle bundle = getBundle();
        return getStringSafely(bundle, key, null);
    }
    /*
     * Internal method to proxy for resource keys that don't exist
     */
    private static String getStringSafely(ResourceBundle bundle, String key, 
                                          String defaultValue) {
      String resource = null;
      try {
        resource = bundle.getString(key);
      } catch (MissingResourceException mrex) {
        if (defaultValue != null) {
          resource = defaultValue;
        } else {
          resource = NO_RESOURCE_FOUND + key;
        }
      }
      return resource;
    }
//Rest of file omitted from here
}

<!-- Resource bundle -->
<application>
  <message-bundle>oracle.srdemo.view.resources.UIResources</message-bundle>
  ...
</application>

<!-- Managed bean for ResourceAdapater class -->
<managed-bean>
  <managed-bean-name>resources</managed-bean-name>
  <managed-bean-class>
    oracle.srdemo.view.resources.ResourceAdapter</managed-bean-class>
  <managed-bean-scope>application</managed-bean-scope>
</managed-bean>

Creating the JSF Page for Each Menu Item

Each menu item (whether it is a menu tab item, menu bar item, or global button) has its own page. To display the available menu choices on a page, bind the menu components (such as menuTabs, menuBar, or menuButtons) to the menu model. Example: MenuTabs Component Bound to a Menu Model shows the menuTabs component code that binds the component to a menu model.

<af:panelPage title="#{res['srmanage.pageTitle']}"
              binding="#{backing_SRManage.panelPage1}"
              id="panelPage1">
  <f:facet name="menu1">
    <af:menuTabs value="#{menuModel.model}"...>
      ...
    </af:menuTabs>
  </f:facet>
  ...
</af:panelPage>

Each menu component has a nodeStamp facet, which takes one commandMenuItem component, as shown in Example: NodeStamp Facet and CommandMenuItem Component. By using a variable and binding the menu component to the model, you need only one commandMenuItem component to display all items in a menu, which is accomplished by using an EL expression similar to #{var.label} for the text value, and #{var.getOutcome} for the action value on the commandMenuItem component. It is the commandMenuItem component that provides the actual label you see on a menu item, and the navigation outcome when the menu item is activated.

<af:panelPage title="#{res['srmanage.pageTitle']}"
              binding="#{backing_SRManage.panelPage1}"
              id="panelPage1">
  <f:facet name="menu1">
    <af:menuTabs var="menuTab"
                 value="#{menuModel.model}">
      <f:facet name="nodeStamp">
        <af:commandMenuItem text="#{menuTab.label}"
                            action="#{menuTab.getOutcome}"
                            .../>
      </f:facet>
    </af:menuTabs>
  </f:facet>
  ...
</af:panelPage>

Whether a menu item renders on a page is determined by the security role of the current user logged in. For example, only users with the manager role see the Management menu tab. The rendered and disabled attributes on a commandMenuItem component determine whether a menu item should be rendered or disabled.

Following along with the MenuItem class in Example: MenuItem.java for All Menu Items: For global items, bind the rendered attribute to the variable's type property and set it to global. For nonglobal items, bind the rendered attribute to the variable's shown property and the type property, and set the type property to default. For nonglobal items, bind also the disabled attribute to the variable's readOnly property. Example: Rendered and Disabled Menu Item Components shows how this is done for menuTabs (a nonglobal component) and menuButtons (a global component).

<af:menuTabs var="menuTab" value="#{menuModel.model}">
  <f:facet name="nodeStamp">
    <af:commandMenuItem text="#{menuTab.label}"
                        action="#{menuTab.getOutcome}"
                        rendered="#{menuTab.shown and
                                    menuTab.type=='default'}"
                        disabled="#{menuTab.readOnly}"/>
  </f:facet>
</af:menuTabs>
...
<af:menuButtons var="menuOption" value="#{menuModel.model}">
  <f:facet name="nodeStamp">
    <af:commandMenuItem text="#{menuOption.label}"
                        action="#{menuOption.getOutcome}"
                        rendered="#{menuOption.type=='global'}"
                        icon="#{menuOption.icon}"/>
  </f:facet>
</af:menuButtons>

You can use any combination of menus you desire in an application. For example, you could use only menu bars, without any menu tabs. To let ADF Faces know the start level of your menu hierarchy, you set the startDepth attribute on the menu component. Based on a zero-based index, the possible values of startDepth are 0, 1, and 2, assuming three levels of menus are used. If startDepth is not specified, it defaults to zero (0).

If an application uses global menu buttons, menu tabs, and menu bars: A global menuButtons component always has a startDepth of zero. Since menu tabs are the first level, the startDepth for menuTabs is zero as well. The menuBar component then has a startDepth value of 1. Example: PanelPage Component with Menu Facets shows part of the menu code for a panelPage component.

<af:panelPage title="#{res['srmanage.pageTitle']}">
  <f:facet name="menu1">
    <af:menuTabs var="menuTab" value="#{menuModel.model}">
      <f:facet name="nodeStamp">
        <af:commandMenuItem text="#{menuTab.label}"
                            action="#{menuTab.getOutcome}"
                            rendered="#{menuTab.shown and
                                       menuTab.type=='default'}"
                            disabled="#{menuTab.readOnly}"/>
          </f:facet>
    </af:menuTabs>
  </f:facet>
  <f:facet name="menu2">
    <af:menuBar var="menuSubTab" startDepth="1"
                value="#{menuModel.model}">
      <f:facet name="nodeStamp">
        <af:commandMenuItem text="#{menuSubTab.label}"
                            action="#{menuSubTab.getOutcome}"
                            rendered="#{menuSubTab.shown and
                                        menuSubTab.type=='default'}"
                            disabled="#{menuSubTab.readOnly}"/>
      </f:facet>
    </af:menuBar>
  </f:facet>
  <f:facet name="menuGlobal">
    <af:menuButtons var="menuOption" value="#{menuModel.model}">
      <f:facet name="nodeStamp">
        <af:commandMenuItem text="#{menuOption.label}"
                            action="#{menuOption.getOutcome}"
                            rendered="#{menuOption.type=='global'}"
                            icon="#{menuOption.icon}"/>
      </f:facet>
    </af:menuButtons>
  </f:facet>
  ...
</af:panelPage>

<af:page title="Title 1" var="node" value="#{menuModel.model}">
  <f:facet name="nodeStamp">
    <af:commandMenuItem text="#{node.label}" 
                        action="#{node.getOutcome}"
                        type="#{node.type}"/>
  </f:facet>
</af:page>

Creating the JSF Navigation Rules

Create one global navigation rule that has navigation cases for each first-level and global menu item. Children menu items are not included in the global navigation rule. For menu items that have children menu items (for example, the Management menu tab has children menu bar items), create a navigation rule with all the navigation cases that are possible from the parent item, as shown in Example: Navigation Rules for a Menu System in the faces-config.xml File.

<navigation-rule>
  <from-view-id>*</from-view-id>
  <navigation-case>
    <from-outcome>GlobalHome</from-outcome>
    <to-view-id>/app/SRList.jspx</to-view-id>
    <redirect/>
  </navigation-case>
  <navigation-case>
    <from-outcome>GlobalSearch</from-outcome>
    <to-view-id>/app/staff/SRSearch.jspx</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>GlobalCreate</from-outcome>
    <to-view-id>/app/SRCreate.jspx</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>GlobalManage</from-outcome>
    <to-view-id>/app/management/SRManage.jspx</to-view-id>
    <redirect/>
  </navigation-case>
  <navigation-case>
    <from-outcome>GlobalLogout</from-outcome>
    <to-view-id>/app/SRLogout.jspx</to-view-id>
    <redirect/>
  </navigation-case>
  <navigation-case>
    <from-outcome>GlobalAbout</from-outcome>
    <to-view-id>/app/SRAbout.jspx</to-view-id>
  </navigation-case>
</navigation-rule>
<!-- Navigation rule for Management menu tab with children items -->
<navigation-rule>
  <from-view-id>/app/management/SRManage.jspx</from-view-id>
  <navigation-case>
    <from-outcome>Skills</from-outcome>
    <to-view-id>/app/management/SRSkills.jspx</to-view-id>
  </navigation-case>
</navigation-rule>

Defining a JSF Navigation Rule for Launching a Dialog

You manage the navigation into a popup dialog by defining a standard JSF navigation rule with a special dialog: outcome. Using the dialog sample application shown in Figure: Page Flow of a Dialog Sample Application, three navigation outcomes are possible from the Login page:

• Show the Orders page in the same window (successful login)

• Show the Error dialog page in a popup dialog (login failure)

• Show the New Account dialog page in a popup dialog (new user)

Example: Dialog Navigation Rules in the faces-config.xml File shows the navigation rule for the three navigation cases from the Login page (login.jspx).

<navigation-rule>

  <!-- Originating JSF page -->
  <from-view-id>/login.jspx</from-view-id>

  <!-- Navigation case for the New Account dialog page (new user)-->
  <navigation-case>
    <from-outcome>dialog:newAccount</from-outcome>
    <to-view-id>/new_account.jspx</to-view-id>
  </navigation-case>

  <!-- Navigation case for the Error dialog page (upon login failure) -->
  </navigation-case>
    <from-outcome>dialog:error</from-outcome>
    <to-view-id>/error.jspx</to-view-id>
  </navigation-case>

  <!-- Navigation case for the Orders page (upon login success) -->
  </navigation-case>
    <from-outcome>orders</from-outcome>
    <to-view-id>/orders.jspx</to-view-id>
  </navigation-case>

</navigation-rule>

Creating the JSF Page That Launches a Dialog

In the originating page from which a popup dialog is launched, you can use either an action method or a static action outcome on the ActionSource component. Whether you specify a static action outcome or use an action method that returns an action outcome, this action outcome must begin with dialog:.

The sample application uses an action method binding on the commandButton component to determine programmatically whether to navigate to the Orders page or the Error dialog page, and a static action outcome on the commandLink component to navigate directly to the New Account dialog page. Both command components are on the Login page. Example: Login Button on the Login Page shows the code for the Login commandButton component.

af:commandButton id="cmdBtn"
                 text="Login"
                 action="#{backing_login.commandButton_action}"
                 useWindow="true"
                 windowHeight="200"
                 windowWidth="500"
                 partialSubmit="true"/>

The attributes useWindow, windowHeight, and windowWidth are used in launching pages in popup dialogs. These attributes are ignored if the client device doesn't support popup dialogs.

When useWindow="true" ADF Faces knows to launch the dialog page in a new popup dialog. The windowHeight and windowWidth attributes specify the size of the popup dialog.

The action attribute on commandButton specifies a reference to an action method in the page's backing bean, Login.java. The action method must return an outcome string, which JSF uses to determine the next page to display by comparing the outcome string to the outcomes in the navigation cases defined in faces-config.xml. The code for this action method is shown in Example: Action Method Code for the Login Button.

public String commandButton_action()
{
  String retValue;
  retValue = "orders";
  _cust = getListCustomer();
  if (_cust == null || !password.equals(_cust.getPassword()))
  {
    retValue = "dialog:error";
  }
  
  return retValue;
}

Example: New User Command Link on the Login Page shows the code for the New User commandLink component that uses a static action outcome.

<af:commandLink id="cmdLink" 
                text="New User?"
                action="dialog:newAccount"
                useWindow="true"
                partialSubmit="true"
                windowHeight="200"
                windowWidth="500" />

Instead of referencing an action method, the action attribute value is simply a static outcome string that begins with dialog:.

Creating the Dialog Page and Returning a Dialog Value

The dialog pages in our sample application are the Error page, the New Account page, and the Account Details page. The dialog process for a new user actually contains two pages: the New Account page and the Account Details page. The dialog process for a user login failure contains just the Error page.

A dialog page is just like any other JSF page, with one exception. In a dialog page you must provide a way to tell ADF Faces when the dialog process finishes, that is, when the user dismisses the dialog. Generally, you do this programmatically or declaratively via a command component. Example: Cancel Button on the Error Page shows how to accomplish this programmatically via a Cancel button on the Error page.

<af:commandButton text="Cancel"
                  actionListener="#{backing_error.cancel}" />

The actionListener attribute on commandButton specifies a reference to an action listener method in the page's backing bean, Error.java. The action listener method processes the action event that is generated when the Cancel button is clicked. You call the AdfFacesContext.returnFromDialog() method in this action listener method, as shown in Example: Action Listener Method for the Cancel Button in a Backing Bean.

public void cancel(ActionEvent actionEvent)
{
  AdfFacesContext.getCurrentInstance().returnFromDialog(null, null);
}

To accomplish the same declaratively on the Account Details dialog page, attach a af:returnActionListener tag to the Cancel button component, as shown in Example: Cancel Button on the Account Details Page. The af:returnActionListener tag calls the returnFromDialog method on the AdfFacesContext—no backing bean code is needed.

<af_commandButton text="Cancel" immediate="true">
  <af:returnActionListener/>
</af:commandButton>

No attributes are used with the af:returnActionListener tag. The immediate attribute on commandButton is set to true: if the user clicks Cancel without entering values in the required Password and Confirm Password fields, the default JSF ActionListener can execute during the Apply Request Values phase instead of the Invoke Application phase, thus bypassing input validation.

The New Account page and Account Details page belong in the same dialog process. A dialog process can have as many pages as you desire, but you only need to call AdfFacesContext.returnFromDialog() once.

The same af:returnActionListener tag or AdfFacesContext.returnFromDialog() method can also be used to end a process and return a value from the dialog. For example, when the user clicks Done on the Account Details page, the process ends and returns the user input values. Example: Done Button on the Account Details Page shows the code for the Done button.

<af:commandButton text="Done"
                  actionListener="#{backing_new_account.done}" />

The actionListener attribute on commandButton specifies a reference to an action listener method in the page's backing bean, New_account.java. The action listener method processes the action event that is generated when the Done button is clicked. Example: Action Listener Method for the Done Button in a Backing Bean shows the code for the action listener method, where the return value is retrieved, and then returned via the AdfFacesContext.returnFromDialog() method.

public void done(ActionEvent e)
{
  AdfFacesContext afContext = AdfFacesContext.getCurrentInstance();
  String firstname = afContext.getProcessScope().get("firstname").toString();
  String lastname = afContext.getProcessScope().get("lastname").toString();
  String street = afContext.getProcessScope().get("street").toString();
  String zipCode = afContext.getProcessScope().get("zipCode").toString();
  String country = afContext.getProcessScope().get("country").toString();
  String password = afContext.getProcessScope().get("password").toString();
  String confirmPassword =
   afContext.getProcessScope().get("confirmPassword").toString();
  if (!password.equals(confirmPassword))
  {
    FacesMessage fm = new FacesMessage();
    fm.setSummary("Confirm Password");
    fm.setDetail("You've entered an incorrect password. Please verify that you've
     entered a correct password!");
    FacesContext.getCurrentInstance().addMessage(null, fm);
  }
  else
  {
    //Get the return value 
    Customer cst = new Customer();
    cst.setFirstName(firstname);
    cst.setLastName(lastname);
    cst.setStreet(street);
    cst.setPostalCode(zipCode);
    cst.setCountry(country);
    cst.setPassword(password);
    // And return it
    afContext.getCurrentInstance().returnFromDialog(cst, null);
    afContext.getProcessScope().clear();
  }
}

The AdfFacesContext.returnFromDialog() method lets you send back a return value in the form of a java.lang.Object or a java.util.Map of parameters. You don't have to know where you're returning the value to—ADF Faces automatically takes care of it.

Handling the Return Value

To handle a return value, you register a return listener on the command component that launched the dialog, which would be the New User link component on the Login page in the sample application. Example: New User Command Link on the Login Page shows the code for the New User link component.

<af:commandLink id="cmdLink" text="New User?"
                action="dialog:newAccount"
                useWindow="true" partialSubmit="true"
                returnListener="#{backing_login.handleReturn}"
                windowHeight="200" windowWidth="500" />

The returnListener attribute on commandLink specifies a reference to a return listener method in the page's backing bean, Login.java. The return listener method processes the return event that is generated when the dialog is dismissed. Example: Return Listener Method for the New User Link in a Backing Bean shows the code for the return listener method that handles the return value.

public void handleReturn(ReturnEvent event)
{
  if (event.getReturnValue() != null)
  {
    Customer cst;
    String name;
    String psw;
    cst = (Customer)event.getReturnValue();
    name = cst.getFirstName();
    psw = cst.getPassword();
    CustomerList.getCustomers().add(cst);
    inputText1.setSubmittedValue(null);
    inputText1.setValue(name);
    inputText2.setSubmittedValue(null);
    inputText2.setValue(psw);
  }
}

You use the getReturnValue() method to retrieve the return value, because the return value is automatically added as a property of the ReturnEvent.

Passing a Value into a Dialog

The AdfFacesContext.returnFromDialog() method lets you send a return value back from a dialog. Sometimes you might want to pass a value into a dialog. To pass a value into a dialog, you use a launch listener (LaunchListener).

In the sample application, a new user can enter a name in the Username field on the Login page, and then click the New User link. When the New Account dialog page displays in a popup dialog, the First Name input field is automatically populated with the name that was entered in the Login page. To accomplish this, you register a launch listener on the command component that launched the dialog (which would be commandLink). Example: Input Field and New User Command Link on the Login Page shows the code for the commandLink component.

<af:inputText label="Username" value="#{backing_login.username}"/>
<af:commandLink id="cmdLink" text="New User?"
                action="dialog:newAccount"
                useWindow="true" partialSubmit="true"
                launchListener="#{backing_login.handleLaunch}"
                returnListener="#{backing_login.handleReturn}"
                windowHeight="200" windowWidth="500" />

The LaunchListener attribute on commandLink specifies a reference to a launch listener method in the page's backing bean, Login.java. In the launch listener method you use the getDialogParameters() method to add a parameter to a Map using a key-value pair. Example: Launch Listener Method for the New User Command Link in a Backing Bean shows the code for the launch listener method.

public void handleLaunch(LaunchEvent event)
{
  //Pass the current value of the field into the dialog
  Object usr = username;
  event.getDialogParameters().put("firstname", usr);
}
// Use by inputText value binding 
public String username;
public String getUsername()
{
  return username;
}
public void setUsername(String username)
{
  this.username = username;
}

To show the parameter value in the New Account dialog page, use the ADF Faces processScope to retrieve the key and value via a special EL expression in the format #{processScope.someKey}, as shown in Example: Input Field on the New Account Page.

<af:inputText label="First name" value="#{processScope.firstname}"/>