| Oracle® Fusion Applications Developer's Guide 11g Release 6 (11.1.6) Part Number E15524-11 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Applications Developer's Guide 11g Release 6 (11.1.6) Part Number E15524-11 |
|
|
PDF · Mobi · ePub |
This chapter discusses the UI Shell page template used to build web pages, and the components used to implement user interface features in Oracle JDeveloper (JDeveloper), such as menus and task flows.
This chapter includes the following sections:
For more information about the features, see:
Chapter 15, "Implementing Additional Functions in the UI Shell"
Chapter 16, "Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables"
Chapter 17, "Implementing Applications Panels, Master-Detail, Hover, and Dialog Details"
The UI Shell is a page template containing default information, such as a logo, menus, and facets. To supplement the UI Shell template, there also is a UIShellMainArea template. Because you can load information into dynamic tabs, the Main Area (the center and the right as shown in Figure 13-1) cannot be a part of the page itself because it is loaded dynamically.
The UI Shell design supports task-based and user-based navigation, and organizes screen real estate more effectively by collating tasks, providing dedicated spaces for primary-task supporting information, and maintains general order and appropriate hierarchy among various elements on the screen.
The UI Shell for Applications User Experience (Applications UX) patterns provides a system of containers that fulfill common layout and navigational requirements in a structured, consistent manner. The UI Shell focuses on providing detailed design for defining and organizing various types of navigation and other functionality such as search and auxiliary information for Oracle Fusion Middleware alone.
Before You Begin:
You should be familiar with JDeveloper, be able to create and run JavaServer Faces (JSF) pages, and be able to create an Oracle Application Development Framework (Oracle ADF) task flow.
Almost all shipped Oracle Fusion Applications pages are built using the UIShell page template. Exceptions include the login page, and the password preferences page.
The UI Shell is composed of four default, mandatory areas: global, regional, local, and contextual, as shown in Figure 13-1.
The basic information about the UI Shell includes:
The shell is optimized for a screen resolution of 1280x1024 pixels.
The four areas are:
Global Area: The Global Area, across the full width at the top of the UI Shell, is stable, consistent, and persistent for an individual user. It contains controls that generally affect the contents of the other three areas. See Section 13.1.2.1, "Global Area Standard Links."
Regional Area: The Regional Area is in the left-hand pane of the UI shell. It has controls and content that generally affect the contents of the local and contextual areas. Tasks lists in the Regional Area automatically are bulleted to make it clear when a line item wraps to the next line.
Local Area: The local area is in the center of the UI Shell where users do their work. It is the main work area and typically contains the transaction form with the menus and controls that enable users to be productive. Controls in, and the content or state of, the local area generally affect the contents of the contextual area.
Main Area: This term designates the combination of the Local Area and the Contextual Area.
Contextual Area: The contextual area is in the right-hand pane of the UI Shell, with controls and contents that generally are affected by controls in, or the content or state of, the local area; although in specific cases the contextual area can also affect the contents of the local area (causing a local-area reload).
Application designers, customers, and administrators can set the regional and contextual areas as collapsed for specific applications. End users can expand those areas at runtime.
If there is no content in the regional or contextual area, the area is collapsed and the ability to expand it is disabled.
The contextual area is directly bound to the local area. The application developer can bind the contextual area content to the local area such that each invocation of a local area automatically causes a relevant contextual area in the correct state to appear alongside the local area.
The Global Area incorporates a number of built-in indicators and links:
Home
Click this link to return to the defined Home page. See Section 15.3, "Implementing the Oracle Fusion Home Page UI."
Navigator
The Navigator menu, shown in Figure 13-18, is rendered when the Navigator link is clicked on the UI Shell. See Section 13.5.1.2, "Displaying the Navigator Menu."
Recent Items
The Recent Items link tracks a list of the last 20 task flows visited by a user. See Section 14.2, "Implementing Recent Items."
Favorites
The Add to Favorites link takes the most recent task flow visited by a user (see Section 14.2, "Implementing Recent Items") and adds it to the Favorites list.
Tags
Tagging is a service that allows users to add tags to selected resources in Oracle Fusion Applications to contribute to resources other users have visited. See Section 14.1, "Implementing Tagging Integration."
Watchlist
The Watchlist link is a user-accessible UI that provides a summary of items the user can track using shortcuts. See Section 14.3, "Implementing the Watchlist."
Group Spaces
The Group Spaces link bundles all the collaboration tools and provides an easy way for users to create their own dynamic collaborative groups around a project or business task flow. See Section 14.4, "Implementing Group Spaces."
Personalization
The Personalization menu options let you set your preferences, edit the current page, and reset the content and layout. See Section 13.6, "Using the Personalization Menu."
Accessibility
The Accessibility link appears on all pages. It will allow users to set their accessibility preferences because the Personalization menu, which includes preferences, is hidden for anonymous users.
Administration
The Administration menu options allow you to customize the current page at a multi-user level, to manage sandboxes, and to get access to the setup applications. See Section 13.8, "Using the Administration Menu."
Help
The Help menu options let you control trace levels, run diagnostics, and provide an About page that lists information about the application. See Section 13.9, "Using the Help Menu."
Sign In / Sign Out
Note:
When signing in, users always are directed to the application's home page.
This list provides two possible scenarios during runtime:
The application is not secured. In this case, there is no concept of the user being logged in (authenticated) or logged out (not authenticated).
The commandLink displays the text Sign In and is disabled.
There is no user name displayed next to the commandLink.
The application is secured with ADF Security.
If the user is logged in:
The commandLink displays the text Sign Out and is enabled.
The logged-in user name is displayed next to the Sign Out link.
If Oracle WebLogic Server is configured to authenticate with Oracle Internet Directory LDAP, the user name is the display name of the authenticated user principal. The display name is indexed by a general end user preference. See Section 13.7, "Implementing End User Preferences."
If the user is logged out, the only way for an unauthenticated user to view a page is if a page either has no databinding (no pagedef) or has databinding but is granted to the anonymous role:
The commandLink displays the text Sign In and is enabled.
No user name is displayed next to the Sign In link.
When the Sign Out link is clicked, the page is redirected to the application's default home page if it is accessible. There are cases in which a default home page is not available to the current user. In such cases, the user application should implement the setLogoutUrl() API that is included in the oracle.apps.fnd.applcore.common.ApplSession class of the Oracle Fusion Middleware extensions for Applications Core API. This API is implemented as:
public void setLogoutURL(String pLogoutURL);
The UIShell's Sign Out logic will get the logout URL from ApplSession using the getLogoutURL() API and redirect to it. This API is implemented as:
public String getLogoutURL();
If the logout URL was not set in ApplSession, the application will be redirected to the default home page.
On clicking the Sign Out link, the user session is cleared from the cookie and terminated. If the home page is secured, the login prompt will first appear. If the home page is not secured, the page will appear and the Sign In link will be enabled.
The UIShell is a page template with some facets for content that may be placed directly on the page, but it usually has its content inserted dynamically. The dynamic insertion happens by reading metadata in the form of menu metadata. This informs the UI Shell about which task flows to load and where. The UI Shell also can create a list of tasks, from the same metadata, that, when clicked, can load into the Main Area. All task flows and the page built by the UIShell template follow the standard ADF Security framework.
When you create an application using the Oracle Fusion Web Application (ADF) template, two projects automatically are created for you: the data model and the user interface projects. The default names for these projects that JDeveloper provides are Model and ViewController. You then add the Applications Core (ViewController) tag library to the user interface project. See Section 3.4, "Adding the Applications Core Tag Library to Your User Interface Project."
Creating a page also creates your application's workspace, where you will later place your page fragments and task flows. For more information about task flows, see the "Getting Started with ADF Task Flows" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).
For more information about starting JDeveloper, see Chapter 2, "Setting Up Your Development Environment."
To create a JSF page:
Select the user interface project in the Application Navigator.
Choose File > New > Web Tier > JSF > JSF Page.
The Create JSF Page dialog is displayed, as shown in Figure 13-2.
In the dialog:
Enter a file name and directory path.
The file name should follow these patterns:
[<Product Code><LBA Prefix>]<Role>Dashboard.jspx
[<Product Code><LBA Prefix>]<Object>Workarea.jspx
From the Use Page Template list, select UIShell.
Note:
The af:skipLinkTarget tag has been incorporated in the UIShell.jspx template so developers do not need to code this required accessibility feature in each page.
Specifically, <af:skipLinkTarget/> has been inserted before the SingleObjectContextArea facet in the UIShell.jspx file:
<af:panelGroupLayout inlineStyle="width:100%;"
id="soContextParent">
<af:skipLinkTarget/>
<af:facetRef facetName="SingleObjectContextArea"/>
</af:panelGroupLayout>
Select Create as XML Document (*.jspx).
Click OK.
The new JSF page is displayed in the editor. Note that the page headers in the Design view do not display exactly as they will at runtime.
Note:
This JSPX page is just the container for the UI Shell template. All other page content, such as the regional, local, and contextual area flows, and the dynamic task flows, are defined independently. At runtime, the menu definition assembles the various parts. All task flows are loaded into a page created with the UI Shell template by configuring the Menu file. This is done to control the behavior and the dynamic loading of task flows at runtime. It also creates the Navigator menu and Task List menu. See Section 13.5, "Working with the Global Menu Model" and Section 13.2.1.1, "Working with the Applications Menu Model."
Now you can add components to the page. Table 13-1 lists the itemNode properties that can be used for a JSF page. See Section 13.2.1.1, "Working with the Applications Menu Model" for how to add a menu to the page.
Table 13-1 itemNode Properties of a JSF Page
| ItemNode Property | Property Value | Description |
|---|---|---|
|
|
Name that has been assigned to the action. |
Go to the page defined by the action. |
|
|
String |
The values are This is set at the page level For example: <itemNode id="itemNode_AppsPanelTests_TabsWA" label="label_AppsPanelTests_TabsWA" action="AppsPanelTests_TabsWA" focusViewId="/AppsPanelTests_TabsWA" dataControlScope="isolated"> |
|
|
|
This property provides an option to suppress dynamic tab navigation and just display one Main Area at a time. To do this, add the following property and value to the
Other menu metadata stays the same. The Task List menu will continue to render. Clicking a Task link will replace the current Main Area task flow with the new one. Multiple If the property value is not defined, it defaults to |
|
|
Unique identifier |
|
|
|
String |
This is what appears in the Work Area title. Note: For all UIShell work area pages with Data Visualization Tool (DVT) components in the default Main Area task flow, and for Home pages with DVT components, you must create the <af:document id="d1"
title="#{adfBundle['oracle.apps...resource.xyzGenBundle']['Header.DefaultMain']} -
#{adfBundle['oracle.apps...resource.xyzGenBundle']['Header.WorkAreaLabel']} -
#{adfBundle['oracle.apps.common.acr.resource.ResourcesGenBundle']['Header.OracleApplications']}" >
For UI Shell pages with DVT components in their dynamic Main Area task flows, the title is set on the |
|
|
Name of the view activity. |
|
|
|
|
To set the UI Shell's |
|
|
Numeric value |
See Section 13.4.2, "How to Control Regional Area Task Flows". |
|
|
|
See Section 13.4.2, "How to Control Regional Area Task Flows". |
Page and task flow information are local to a particular JDeveloper application or project and are exposed using the Applications menu model.
An Applications menu is related to a local JSPX file and includes the task lists, defaultMain, and defaultRegional. A menu is created for each Java EE application.
The following information describes how to create an ADF menu to access page elements through the Navigator menu on JSF pages or task flows that are based on the UI Shell template.
Select the JSPX page in the Application Navigator, then right-click and select the Create Applications Menu option.
This step creates the menu file with one itemNode. The menu file will be named <view id>_taskmenu.xml. For example, if there is a PageA.jspx, its view ID in the adfc-config.xmlfile is PageA, and the menu file name is PageA_taskmenu.xml. This step also should add the ApplicationsMenuModel managed bean entry into the adfc-config.xml file. The managed bean entry should not have the topRootModel managed bean property set. Example 13-1 shows a sample of the generated content in the PageA_taskmenu.xml file.
Example 13-1 Example of Generated Content in a taskmenu.xml
<?xml version="1.0" encoding="UTF-8" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
<!-- This is the page level node -->
<itemNode id="itemNode_PageA" label="label_PageA" action="adfMenu_PageA"
focusViewId="/PageA">
<!-- Optional itemNode for Regional Task List task flow. Your task menu definition may omit this if your page does not display a Regional Task List. -->
<itemNode id="__myProduct_RegionalTaskList"
focusViewId="/PageA"
label="#{applcoreBundle.TASKS}" taskType="defaultRegional"
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/TasksList.xml#TasksList"
disclosed="true"
parametersList="fndPageParams=#{pageFlowScope.fndPageParams}"/>
<!-- Typical itemNode entry for a task flow -->
<itemNode id="__myProductTFId"
focusViewId="/PageA"
label="#{myBundle.myProductTFxyz}" taskType="defaultMain"
taskFlowId="<fully qualified-TFid>"
disclosed="true""/>
<!-- .. Additional itemNodes for other task flows on PageA -->
</itemNode>
</menu>
Creating ADF Menus for Multiple JSF Pages
Use this alternate method to create menus for multiple pages at once. This will create an empty menu on each page.
Right-click the adfc-config.xml file and choose Open to display the file in the JDeveloper editor.
The adfc-config.xml file is located in the following location: <project_name> > WEB INF.
Drag pages from the Application Navigator to the adfc-config.xml file in the editor.
View nodes that represent the pages or task flows are displayed in the editor.
When you drag the pages or task flows, they automatically are grouped into the same menu.
Right-click the adfc-config.xml file and choose Create Applications Menus. An empty panel, as shown in Figure 13-3, is displayed.
Click Find Pages to populate the display with all the JSPX pages that have been added to the adfc_config.xml file. As shown in Figure 13-4, pages that do not yet have a menu associated with them will have a checkbox that defaults to being selected, and pages that already have an associated menu are shown with a checkmark to the right.
Click OK to automatically create a menu file for each selected page and to update the task flow with a managed bean.
Note:
Menu files will follow the <focusViewId>_taskmenu.xml naming standard. For example, the menu file for the Example.jspx file will be /WEB-INF/menus/Example_taskmenu.xml.
When you create this menu file, the following occurs:
The menu file is generated and placed into the following directory: ViewController/public_html/WEB-INF/menus
The following are generated and appear in the adfc-config.xml file:
A new control-flow rule
A managed bean entry
The new menu that contains your pages is now accessible from the Navigator panel.
When a user opens an application, he or she expects something to be displayed automatically. A task flow in the default Main Area accomplishes this.
To add a task flow to the default Main Area:
Choose File > New > Web Tier > JSF > JSF Page Fragment.
The Create JSF Page Fragment dialog shown in Figure 13-5 is displayed.
In the Create New JSF Page Fragment dialog:
Enter a page fragment name, for example, you might enter def_main.jsff.
The file name should follow these patterns:
<Object><Function>.jsff
<Object>.jsff
The page name should convey the object it presents (an employee, a supplier, an item, a purchase order, an applicant, and so on), and the function being performed (search, promote, hire, approve, view). For some pages, the object is sufficient.
For update or create pages, just the object should be used (unless the create and update pages are different as shown in the examples).
Never give pages step number names, such as PoCreateStep1.jsff or PoCreateStep2.jsff. Always describe the page function, such as PoDesc.jsff or PoLines.jsff.
From the Use Page Template list, select UIShellMainArea.
Note:
The UIShellMainArea template is only for Main Area task flows, not Regional Area task flows.
Click OK.
The Local and Contextual area facets of the page fragment appear in the editor.
Choose File > New > JSF > ADF Task Flow to create a default task flow.
Note:
Most applications will have multiple task flows for the Regional, Local and Contextual areas. For instance, Figure 13-1, "UI Shell Areas" shows 10 task flows.
The Create ADF Task Flow dialog shown in Figure 13-6 is displayed.
Ensure that the JSF page fragment file is selected in the Application Navigator and is displayed in the Edit view.
In the Edit view, click the Source tab.
Locate the line that resembles <f:facet name="localArea"/>.
In the Application Navigator, select an applicable task flow, such as the one you created in Step 4, to add to the localArea. This should be an XML file located under ViewController > Web Content > WEB-INF > oracle > apps > application_name > ui > flow.
Drag and drop the appropriate flow from the Navigator pane to immediately following <f:facet name="localArea"/>.
From the Create menu that is displayed, select Region.
The <f:facet name="localArea"/> changes to <f:facet name="localArea"> and code resembling that shown in Example 13-2 will be inserted after it.
Example 13-2 Creating Region localArea Facet Added Code
<af:region value="#{bindings.EmpCreateUpdateFlow1.regionModel}"
id="EmpCreateUpdateFlow1"/>
</f:facet>
In the Structure window, an af:region entry is added following the f:facet - localArea entry.
Note: This step is optional. If you do not need a contextualArea, go to Step 6.
In the Structure window, select f:facet - contextualArea.
In the Component Palette, select ADF Faces > Layout.
Click Panel Accordian. An af:showDetailItem entry is created automatically under af:panelAccordian.
In the Source view, find and highlight the new <af:showDetailItem ...> entry.
In the Application Navigator, select an applicable task flow, such as the one you created in Step 4, and drag and drop it onto the highlighted entry in the Source view.
From the Create menu that is displayed, select Region.
Click OK on the Edit Task Flow Binding dialog that is displayed.
Code resembling that shown in Example 13-3 will be inserted after <af:showDetailItem ...> and the page fragment in the editor will resemble Figure 13-7.
Now that you have created the Main Area page fragment, you must wrap it in an ADF task flow.
In the Create ADF Task Flow dialog:
Enter a descriptive name for the task flow.
For example, enter def_main_task-flow-definition.xml.
Ensure that the Create as Bounded Task Flow and the Create With Page Fragments boxes are selected.
Do not change the other default settings.
Click OK.
The new task flow is displayed as a blank visual editor in the JDeveloper middle section.
In the Application Navigator, select your recently created page fragment (.jsff file), and drag and drop it onto the editor.
The page fragment itemNode appears in the editor, as shown in Figure 13-8.
To load the menu metadata:
Note:
The menu data accomplishes several important jobs for you:
It defines properties of the page for you. For instance, it will be displayed in no-tab mode or with dynamic tabs, and define the width of the Regional Area.
It can create a task list menu for each page.
It can create labels for groups of tasks.
In the Application Navigator, select the test_menu_taskmenu.xml file that you created using the ADF Menu Model dialog. For details about creating the menu, see Section 13.2.1.1.1, "How to Create an Applications Menu."
In the test_menu_taskmenu.xml structure view menu tree, shown in Figure 13-9, right-click the itemNode item and choose Insert inside itemNode <task_flow_name> > itemNode.
The Insert itemNode - Common Properties dialog, shown in Figure 13-10, is displayed.
To the right of the focusViewId field, click the ellipsis to display the Edit Property dialog.
In the dialog, choose the ADFc View Activity ID of the page under which you are registering the task flow, then click OK.
Enter a unique ID using this standard format:
<pageID>_<taskFlowName>
This ID example consists of the concatenated page ID (or page name), an underscore, and the task flow name, for example, ExpenseWorkArea_CreateExpense.
Click Finish.
The new item node is displayed in the structure view, under the menu tree.
With the item node selected in the structure view, click the Property Inspector tab, as shown in Figure 13-11.
In the label field, enter a label for the task flow, such as CreateExpense.
This label will be the title of the tab that is opened by the Task Type defaultMain.
Note:
Do not leave this field null. This is the label that will appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Section 13.2.3.4, "Supporting No-Tab Work Areas"), do not leave it blank because this label will be used in other ways, such as Add to Favorites, or when the system tracks the Recent Items.
Select test_menu_taskmenu.xml in the Project Navigator tree, and your task flow in the structure view to display its Property Inspector, or select the Property Inspector tab.
In the Advanced section of the Property Inspector, enter the following values:
Task Type: defaultMain (the task flow is displayed by default whenever the page is rendered).
The Data Control Scope should have been set to isolated, inside the task flow definition for any task flow in the menu (defaultMain or dynamicMain) or any call from openMainTask. See dataControlScope in Table 13-1.
Task Flow Id: ID of the task flow to be loaded.
To enter the ID, click the ellipsis to display the Select Task Flow Id dialog, shown in Figure 13-12, and browse to the task-flow definition location. By default, following the standard naming structure, the location will be in path_to_application directory\ViewController\public_html\WEB-INF.
Click Open to automatically enter the location in the Task Flow field. The task flow ID is a concatenation of the file location for the task-flow definition and the task-flow name. It typically resembles /WEB-INF/MyTaskFlow.xml#MyTaskFlow. The Property Inspector for the itemNode should resemble the example shown in Figure 13-11, "Task Flow Property Inspector".
To run the JSPX page, select the page in the Application Navigator, right-click the page file, and choose Run.
The new page, shown in Figure 13-13, is displayed in a web browser.
Check that the newly rendered page contains one tab whose content is the task flow that you defined in this procedure.
The available itemNode properties for Main Area and Regional Area task flows for application menus are shown in Table 13-2.
Table 13-2 itemNode Properties for Main and Regional Task Flows for Application Menus
| itemNode Property | Property Value | What Happens on the Rendered Page |
|---|---|---|
|
|
Note:
|
|
|
|
String |
Note: When passing parameters, do not leave the label field null. This is the label that would appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Section 13.2.3.4, "Supporting No-Tab Work Areas"), do not leave it blank because this label will be used in other ways, such as Add to Favorites, or when the system tracks the Recent Items. |
|
|
ID of the task flow to be loaded. The task flow ID is a concatenation of the file location for the task flow definition, and the task flow name. For example:
|
|
|
|
|
If A However, if the no-tabs model is used, no new tab is opened. Rather, the current Main Area contents are replaced. (See Section 13.2.3.4, "Supporting No-Tab Work Areas.") |
|
|
String |
Important:
The
In dynamic tabs mode, when looking for a match of an existing tab, these APIs will first look for any instances of the task flow that is already open, which has the same task flow ID as the one passed into them as the parameter. In addition, it will compare the It does not matter if the task flow parameters are the same or different. If the |
|
|
|
See Section 13.2.3.5, "Implementing the Task Popup." This provides a way to load the task flow into a Popup when the user clicks one of the Task List links. |
|
|
|
The no-tab navigation mode can load a Main Area task flow and a dependent task flow simultaneously, while displaying only one flow at a time. (See Section 13.2.3.4, "Supporting No-Tab Work Areas.") The UI Shell is limited to 12 task flows: 10 tabs in tab mode; 1 tab in no-tab mode and 1 dependent in no-tab mode. Dependent Flow is applicable only to the no-tab navigation model. Instead of having only one region for the no-tab navigation model, there are two regions: one for the main task flow and another for the dependent flow. These regions are in a switcher, so that only one is visible at a time. If a dependent task flow is loaded, only the dependent task flow region is shown, and the main task flow region is hidden. When the dependent task flow is closed, the main task flow region is redisplayed, with its state preserved. When |
|
|
True or False |
If |
|
|
|
When the |
|
|
|
All the task flows will be rendered in the Main Area. The task flow that has More than one |
|
|
|
Task flow definitions use conditional activation. There are a number of cases in which Oracle Fusion Applications run with the Regional Area collapsed by default. Unless the user expands it, there is no need to activate the task flows for the Regional Area. However, some use cases depend on the task flow that is under the Regional Area being active even when collapsed. In this case, the
If you require that your task flows be activated or run even though they are not displayed, you must change the |
|
|
The Task List is exposed as a task flow. See Section 13.2.4, "How to Pass Parameters into Task Flows from Tasks List." |
|
|
|
String |
The <itemNode id="__ServiceRequest_itemNode_externalUrl" destination="http://www.yahoo.com"/> |
|
|
String |
Use with the methodParameters property to specify which parameters to pass into a task flow. The value of this property is a delimited list of parameter name-value pairs. See Section 13.2.4, "How to Pass Parameters into Task Flows from Tasks List." |
|
|
String |
Use to pass a Java object into a task flow. See Section 13.2.4, "How to Pass Parameters into Task Flows from Tasks List." |
Unless otherwise noted, follow the procedure outlined in Section 13.2.2, "How to Add Default Main Area Task Flows to a Page," to insert the appropriate itemNode properties listed inTable 13-2.
To add a dynamic Main Area task flow, set taskType="dynamicMain".
To add a default Regional Area task flow, set taskType="defaultRegional".
A tasks list is not a default widget as part of the UI Shell Regional Area. A tasks list is packaged as an ADF Controller task flow. You must manually add this task flow as you would any other defaultRegional task.
Specify the tasks list task flow as a defaultRegional task explicitly. If you do not do this, the tasks list does not render.
Add the following entry to your menu.xml file prior to the item node of tree structure and tree versions:
<itemNode id="__YourPage_itemNode__FndTasksList"
focusViewId="/YourPage" label="#{applcoreBundle.TASKS}"
taskType="defaultRegional"
Note: The taskFlowId value path must appear in a single line to avoid an exception during runtime.
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/patterns/
uishell/ui/publicFlow/TasksList.xml#TasksList"
disclosed="true"
parametersList="fndPageParams=
#{pageFlowScope.fndPageParams}"/>
Id must be unique within the menu metadata.
focusViewId is the focusViewId of your page.
Set label to the default label provided by the Oracle Fusion Middleware Extensions for Applications (Applications Core).
taskType should be defaultRegional.
taskFlowId should point to the tasks list task flow provided by Applications Core.
The disclosed attribute is usually set to true. Although, it can be set to false if you do not want to disclose tasks list by default.
parametersList should set fndPageParams as previously shown so that this object is available in the pageFlowScope of the tasks list task flow. This context is necessary for Single Object WorkArea. For more information, see Section 15.4, "Using the Single Object Context Workarea."
The Task Category is a label that is used to group tasks in a task list.
In the Structure window for the menu, right-click the page itemNode whose taskType value is dynamicMain and choose Surround with... .
The Surround dialog is displayed.
Select itemNode and click OK.
The Insert Item Node dialog page opens to the Common properties tab.
In the Common properties tab, enter these values:
id field: Concatenation of the page ID and a short category name, using the following format, is suggested:
pageId_categoryName
For example, you might enter: ExpenseWorkArea_NewExpense.
focusViewId: Click the ellipsis to open the Advanced Editor.
Select the focusViewId of the page.
Click Finish.
In the Property Inspector for itemNode - ExpenseWorkArea_NewExpense, enter these values:
label: Name of the label, such as NewExpense.
Do not leave this field blank. This is the label that would appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Section 13.2.3.4, "Supporting No-Tab Work Areas"), do not leave it blank because this label will be used in other ways, such as Add to Favorites or when the system tracks the Recent Items.
Note:
The label should be defined in a resource bundle so it can be translated more readily.
Task Type: taskCategory
Run the page by right-clicking the JSPX page file in the Projects tree view and choosing Run
Confirm that the page contains task links arranged by category. The Task List is in the left Regional Area of the page. Items in the Task List are bulleted to make it clear when a line wraps.
The Tasks Pane can link to a task flow in a different JSPX and pass page-level and task-level parameters.
The navigateViewId attribute supports this feature.
Example 13-4 shows a sample of the metadata for a link in a Task List that links to another page.
Example 13-4 Example Metadata for a Link in a Task List that Links to Another Page
<itemNode id="__ServiceRequest_itemNode__toTestPage1"
focusViewId="/ServiceRequest" label="Go to different page"
navigateViewId="/TestPage1"
taskType="dynamicMain"
taskFlowId="/oracle/apps/fnd/applcore/patterns/demo/SRTree.xml#SRTree"/>
You can suppress dynamic tab navigation and just display one Main Area at a time. To do this, add isDynamicTabNavigation="false" to the itemNode that represents your JSPX page, as shown in Example 13-5.
Example 13-5 Implementing a No-Tab Work Area
<itemNode focusViewId="/SelTestWorkarea" id="stp1" taskType="dynamicMain"
taskFlowId="/WEBINF/oracle/.../ProductMainFlow.xml#ProductMainFlow"
label="#{adfBundle
['oracle.apps....SelTestWorkarea_taskmenuBundle'].DEFINE_PRODUCT}"
isDynamicTabNavigation="false"/>
Note that the default value of isDynamicTabNavigation is true.
You also can set the no-tab mode declaratively in the Property Inspector:
Select the itemNode from the Structure window.
Go to Property Inspector.
Select Advanced > Page > Dynamic Tab Navigation. Selecting the Page tab lets you set attribute values for page-level item nodes.
Set the Dynamic Tab Navigation property to false.
Other menu metadata stay the same. Tasks List will continue to render. Clicking a Tasks Link will replace the current Main Area task flow with the new one.
The Task Popup provides a way for you to:
Load a task flow into a popup when the user clicks one of the Tasks List links.
Cancel from the popup or open a new Main Area task flow, passing in parameter values from the popup.
Implementation Notes
The UI Shell provides an af:popup component with a modal af:panelWindow as its immediate child, which would contain a dynamic region defined in it. When selected by the user, the UI Shell will load the task flow into the dynamic region, and show the modal af:popup panelWindow without any buttons. Therefore, the task flow must include the OK and Cancel buttons that are used to open a dynamic tab and dismiss the popup, respectively. The dialog title will be set according to the label mentioned in the menu metadata of the dynamic task link. There is a refresh condition set on the dynamic region that refreshes the task flow and reloads it each time the popup is opened.
Implementation Notes
Remember the following when you implement the Task Popup feature:
For a dynamicMain task that you would like to load into the popup, specify the loadPopup property as true. For example, as shown in Example 13-6, the ChooseSR task flow would be loaded in a popup when the user clicks its link in the Tasks List. The label that is mentioned will be displayed as the dialog title of the popup that starts the task flow.
You can define any components within this task flow, except the af:popup and its child components, such as af:dialog, af:panelWindow, and af:menu.
You cannot have a UIShellMainArea page template or any other templates inside the popup task flow.
You must add the necessary buttons as part of the task flow. For example, if the task flow has a simple .jsff file, it should contain OK and Cancel buttons, along with other components.
Create a managed bean to set the action listener for the Cancel button. See Section 17.4.1.3, "Implementing OK and Cancel Buttons in a Popup."
Create another method for the OK button that calls the method in Example 17-5, and any additional processing logic. The common use case would be opening a new task in the Main Area by using the openMainTask API. For example, you can bind the OK button to a managed bean and add your own action listeners. See Section 17.4.1.3, "Implementing OK and Cancel Buttons in a Popup."
You then can pass the parameters directly from the managed bean to the openMainTask API bindings for the popup task flow page to open a new dynamic tab. The menu data entries for parameters will not have any bearing on the dynamic taskFlow tab that they are loading in the Main Area. The details of that task flow should come from the openMainTask API that is bound to the OK button.
Item nodes with a taskType of dynamicMain, defaultMain, and defaultRegional have parameter support. In addition to specifying the taskFlowId to load when the user clicks a task flow link, you can specify which parameters to pass into that task flow. This is accomplished with the parametersList and methodParameters properties on the itemNode.
For the itemNode where you would like to specify parameter passing, add the parametersList property. The value of this property is a delimited list of parameter name-value pairs that will resemble Example 13-7.
Example 13-7 Using the parametersList Property
<itemNode id="__ServiceRequest_itemNode__SRDefault" focusViewId="/ServiceRequest" label="Pending Service Requests"
taskType="dynamicMain"
taskFlowId="/oracle/apps/fnd/applcore/patterns/demo/SRTable.xml#SRTable"
parametersList="param1=value1;param2=value2;param3=#{ELForValue3}"/>
The methodParameters parameter can be used to pass a Java object into the task flow that is specified in the taskFlowId parameter. Use the setCustomObject() method in FndMethodParameters to set the Java object.
Example of Passing a Java Object Using openMainTask
Bind the methodParameters parameter value to a managed bean property. Example 13-8 shows the methodAction binding in the page definition of the page fragment that calls openMainTask. Also see Table 13-2, "itemNode Properties for Main and Regional Task Flows for Application Menus".
Example 13-8 methodAction Binding to Call openMainTask
<methodAction id="openMainTask" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="openMainTask"
IsViewObjectMethod="false" DataControl="FndUIShellController"
InstanceName="FndUIShellController.dataProvider"
ReturnName="FndUIShellController.methodResults.openMainTask_FndUIShellController_dataProvider_openMainTask_result">
<NamedData NDName="taskFlowId"
NDValue="/WEB-INF/TestPanelSplitterTaskFlow#TestPanelSplitterTaskFlow"
NDType="java.lang.String"/>
<NamedData NDName="keyList" NDType="java.lang.String"/>
<NamedData NDName="parametersList" NDValue="" NDType="java.lang.String"/>
<NamedData NDName="label" NDValue="Test App Panel"
NDType="java.lang.String"/>
<NamedData NDName="reuseInstance" NDType="java.lang.Boolean"/>
<NamedData NDName="forceRefresh" NDType="java.lang.Boolean"/>
<NamedData NDName="loadDependentFlow" NDValue=""
NDType="java.lang.Boolean"/>
<NamedData NDName="methodParameters" NDValue="#{TestOpenMainTaskMBean.fndMethodParams}"
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>
Code in the managed bean for passing a hashmap to the task flow would resemble Example 13-9. A hashmap is a data structure that uses a hash function to map identifying values, known as keys (such as a person's name), to their associated values (such as their telephone number).
Example 13-9 Example Code for Passing a Hashmap
private FndMethodParameters fndMethodParams;
...
public void setRichCommandLink1(RichCommandLink richCommandLink1)
{
this.richCommandLink1 = richCommandLink1;
FndMethodParameters methodParams = new FndMethodParameters();
HashMap testHashMap = new HashMap();
testHashMap.put("param1", "12345");
testHashMap.put("param2", "67890");
methodParams.setCustomObject(testHashMap);
fndMethodParams = methodParams;
}
Then, in the managed bean of the task flow, the Java object can be read, as shown in Example 13-10.
Example 13-10 Reading Java Object in Managed Bean
public String getTestValue()
{
Map pageFlowScope =
AdfFacesContext.getCurrentInstance().getPageFlowScope();
Object custom = pageFlowScope.get("fndCustomObject");
String outputTextString = "";
if (custom != null && custom instanceof HashMap)
{
HashMap myHashMap = (HashMap)custom;
String temp1 = (String)myHashMap.get("param1");
String temp2 = (String)myHashMap.get("param2");
outputTextString = temp1 + temp2;
}
testValue = outputTextString;
return testValue;
}
The testValue parameter is bound to an af:outputText value attribute, such as <af:outputText value="#{TestPanelSplitter1MBean.testValue}"/>, in the page fragment of the task flow.
The UI Shell implements this feature by using the URLView activity that is a task flow component of ADF. URLView generally is used to redirect the current request state of the application to an external or internal URL. With UI Shell, this URLView activity is only being used to open files that are internal to the current web application.
Therefore, the only input that the task list link will need is the internal path (within the webApp) of the file. After the path is provided to UI Shell, it will determine the current contextual root of the application and append it to the internal path of the file. After the Universal Resource Identifier (URI) for the file is generated, this is set on the URLView activity and an action expression is set on the task link to open the URL view. UI Shell also must call an actionEvent JavaScript method on the client side that will not allow the page to lose its current state upon redirection from the URLView activity.
Note:
You can only open data files that are part of your webApp, such as /oracle/apps/fin/acc/file1.xls. This feature supports only opening data files through the task list. Any other URI paths, such as a JSPX or a JSF page, are not supported.
Implementation Notes
For a dynamicMain task item that you would like to use to open the data file, there is a property called filePath in the Menu panel for the UI Shell page XML file. To enable this property in the Menu panel, during design time, the task type of the itemNode must be dynamicMain. The file URI path then should be specified against the filePath attribute in the Menu panel, as shown in Example 13-11.
Example 13-11 Specifying the File URI Path
<itemNode id="__ServiceRequest_itemNode__ChooseSR"
focusViewId="/ServiceRequest" label="Download File"
taskType="dynamicMain" filePath="/WEB-INF/oracle/apps/Accounts.xls" />
You can specify any file type, such as xls, doc, pdf, txt, rtf, and ppt, that is within the application.
Security of menus has two parts: actual access to the page or task flow, and the rendering of the menu itself. Any page or task flow is protected to run for a user only if that user has access to run the page or task flow. Directions for setting this up are in the "Adding Security to an Oracle Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).
Application menus and task list menus will automatically have their page security checked by the menu utilities. If the user does not have access, the menu entry will not be rendered. If the following three conditions are true, security checks if a logged-in user has view privilege for a given task flow:
The application has enabled authorization.
The taskType is dynamicMain for the itemNode.
The taskFlowId attribute is defined in the itemNode.
If any one of these conditions is not true, security is not checked and the itemNode will be protected only by the rendered attribute.
Application menus can have a security Expression Language expression on the rendered attribute that, if it returns false, will not render the menu entry. To do this, set the rendered attribute of the menu entry to an expression that evaluates anything. For instance, if the task list is to edit certain tax forms, this could be a business rule to hide or show links based on whether or not the customer is a nonprofit company. If it evaluates to false, the menu will not appear. For more information on all the security expressions, see the "Adding Security to an Oracle Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).
If your UI Shell pages are secured by ADF Security, you must add a policy similar to that in Example 13-12 to the jazn-data.xml file and the system-jazn-data.xml file.
Example 13-12 Adding a Security Policy to the jazn-data.xml File
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl</class>
<name>anonymous-role</name>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.adf.share.security.authorization.RegionPermission</class>
<name>oracle.apps.fnd.applcore.uicomponents.view.pageDefs.oracle_apps_fnd_applcore_templates_UIShellPageDef</name>
<actions>view</actions>
</permission>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/oracle/apps/fnd/applcore/patterns/uishell/MainArea.xml#MainArea</name>
<actions>view</actions>
</permission>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/oracle/apps/fnd/applcore/patterns/uishell/RegionalArea.xml#RegionalArea</name>
<actions>view</actions>
</permission>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/TasksList.xml#TasksList</name>
<actions>view</actions>
</permission>
</permissions>
</grant>
Task Flow Example
Bounded task flows are secure by default, and require the policy shown in Example 13-13.
Example 13-13 Required Policy for Bounded Task Flows
<permission> <class>oracle.adf.controller.security.TaskFlowPermission</class> <name>/WEB-INF/audit-expense-report.xml#audit-expense-report</name> <actions>view</actions></permission>
If the policy is missing, then framework-level checks will prevent access to the task flow (typically by throwing an error).
But how would a menu item or command link disable or hide itself based on a preliminary check of the same permission? Example 13-14 shows the generic Expression Language expression being used to perform a preliminary check of the Task Flow Permission. Note that this is only needed for an itemNode with taskType="defaultMain" or "defaultRegional". The security check is performed automatically for an itemNode with taskType="dynamicMain" (that is, what is in the tasks list).
Example 13-14 Generic Expression Language Expression Used for Task Flow Permission Preliminary Check
rendered = "#{securityContext.userGrantedPermission['permissionClass=oracle.adf.controller.security.TaskFlowPermission;
target=/WEB-INF/audit-expense-report.xml#audit-expense-report;
action=view']}"
Example 13-15 shows the task flow-specific Expression Language expression.
Example 13-15 Task Flow-specific Expression Language Expression Used for Task Flow Permission Preliminary Check
rendered="#{securityContext.taskflowViewable[/WEB-INF/audit-expense-report.xml#audit-expense-report]}"
Note that both of these checks actually go directly against the policy store; that is, they do not query the task flow definition. This avoids the overhead of loading a large number of ADF artifacts to render links and menus.
UI Shell tasks to open or close a Main Area tab are exposed as data control methods so that you can create such UI artifacts through drag and drop. You do not need to create your own data control methods and manually raise Contextual Events.
Data control APIs are:
FndUIShellController.openMainTask
Note:
When passing parameters, do not leave the label field null. This is the label that would appear in the tab header when in a tabs page. Even if you are in a no-tabs page (see Section 13.2.3.4, "Supporting No-Tab Work Areas"), do not leave it blank because this label will be used in other ways, such as Add to Favorites, or when the system tracks the Recent Items.
FndUIShellController.closeMainTask. See Section 13.4.1.1, "closeMainTask History" for more information.
To open or close a Main Area tab, drag and drop the appropriate data control method to create the UI functionality. Having specified the parameter values for these methods, user clicks will prompt the UI Shell to react accordingly.
To use the openMainTask data control method:
Expand the Data Controls and select the openMainTask item, as shown in Figure 13-14.
Drag openMainTask and drop it onto the page fragment. When you do, the Applications Context menu shown in Figure 13-15 is displayed so you can choose one of the three options.
To use the closeMainTask data control method:
Expand the Data Controls and select the closeMainTask item, as shown in Figure 13-16.
Drag closeMainTask and drop it onto the page fragment. When you do, the Applications Context menu shown in Figure 13-17 is displayed so you can choose one of the three options.
Two APIs shown in Example 13-16 open and close a Main Area tab.
Example 13-16 APIs Open and Close a Main Area Tab
/**
* Opens a Main Area task.
*
* @param taskFlowId Task flow to open
* @param keyList Key list to locate the task flow instance.
* This is a semicolon-delimited key or key-value pair.
* For example, "key1;key2=value2". If only the key is specified,
* the value is picked up from parametersList with the same
* name as the key.
* @param parametersList Parameters list for the task flow.
* This is a semicolon-delimited String
* of name-value pairs. For example,
* "param1=value1;param2=value2".
* @param label Label for the task flow
* @param reuseInstance Default true. If true, refocus an existing instance
* of the task flow, if such exists, without
* opening a new instance of the task flow. If false,
* always open a new instance of the task flow.
* @param forceRefresh Default false. If false, task flow reinitialization
* depends on whether some parameters are passed into parametersList, where
* the presence of parameter values causes reinitialization and the absence of
* parameter values does not. forceRefresh true always causes reinitialization
* of the task flow regardless of the value for parametersList.
* @param loadDependentFlow Effective only in no-tab navigation model.
* Defaults to false. When set to true, the specified
* task flow is loaded into the dependent region
* of the no-tab navigation model, preserving the
* state of the main flow.
* @param methodParameters From Drop 6 Build 7, this can be used for passing
* a Java object into the task flow that is specified
* in the taskFlowId parameter. Use setCustomObject()
* in FndMethodParameters for setting the Java object.
* @return For internal Contextual Event processing
*/
public FndMethodParameters openMainTask(String taskFlowId,
String keyList,
String parametersList,
String label,
Boolean reuseInstance,
Boolean forceRefresh,
Boolean loadDependentFlow,
FndMethodParameters methodParameters)
public FndMethodParameters closeMainTask(FndMethodParameters methodParameters)
Bind the methodParameters parameter value to a managed bean property. Example 13-17 shows the methodAction binding in the page definition of the page fragment that calls the openMainTask method.
Example 13-17 methodAction Binding in Page Definition of Page Fragment That Calls openMainTask
<methodAction id="openMainTask" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="openMainTask"
IsViewObjectMethod="false" DataControl="FndUIShellController"
InstanceName="FndUIShellController.dataProvider"
ReturnName="FndUIShellController.methodResults.openMainTask_FndUIShellController_dataProvider_openMainTask_result">
<NamedData NDName="taskFlowId"
NDValue="/WEB-INF/TestPanelSplitterTaskFlow#TestPanelSplitterTaskFlow"
NDType="java.lang.String"/>
<NamedData NDName="keyList" NDType="java.lang.String"/>
<NamedData NDName="parametersList" NDValue="" NDType="java.lang.String"/>
<NamedData NDName="label" NDValue="Test App Panel"
NDType="java.lang.String"/>
<NamedData NDName="reuseInstance" NDType="java.lang.Boolean"/>
<NamedData NDName="forceRefresh" NDType="java.lang.Boolean"/>
<NamedData NDName="loadDependentFlow" NDValue=""
NDType="java.lang.Boolean"/>
<NamedData NDName="methodParameters" NDValue="#{TestOpenMainTaskMBean.fndMethodParams}"
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>
Example 13-18 shows code in a managed bean for passing a hashmap to the task flow.
Example 13-18 Sample Code in a Managed Bean for Passing a Hashmap to the Task Flow
private FndMethodParameters fndMethodParams;
...
public void setRichCommandLink1(RichCommandLink richCommandLink1)
{
this.richCommandLink1 = richCommandLink1;
FndMethodParameters methodParams = new FndMethodParameters();
HashMap testHashMap = new HashMap();
testHashMap.put("param1", "12345");
testHashMap.put("param2", "67890");
methodParams.setCustomObject(testHashMap);
fndMethodParams = methodParams;
}
Then, in the managed bean of the task flow, the Java object can be read, as shown in Example 13-19.
Example 13-19 Reading Java Object in a Managed Bean
public String getTestValue()
{
Map pageFlowScope =
AdfFacesContext.getCurrentInstance().getPageFlowScope();
Object custom = pageFlowScope.get("fndCustomObject");
String outputTextString = "";
if (custom != null && custom instanceof HashMap)
{
HashMap myHashMap = (HashMap)custom;
String temp1 = (String)myHashMap.get("param1");
String temp2 = (String)myHashMap.get("param2");
outputTextString = temp1 + temp2;
}
testValue = outputTextString;
return testValue;
}
The testValue parameter is bound to an af:outputText value attribute, such as <af:outputText value="#{TestPanelSplitter1MBean.testValue}"/>, in the page fragment of the task flow.
The dynamic tabs mode tracks the last tab that was displayed before the current tab. When the current tab is closed, that last tab is brought back into focus.
In no-tabs mode, a stack of all the task flows that were opened is maintained, along with the parameter values. When the current task is closed, the task flow (with its original parameters) that was open before the current one, is reinitialized.
There are two ways in which the previous tab information is set for a given tab. When a new tab is opened, the tab that was in focus is the new tab's previous tab. When the user clicks a tab UI, the last tab that had the focus becomes the current tab's previous tab.
The MainAreaHandler.handleOpenMainTaskEvent method has a mechanism to handle the new tab. The managed bean for the tab adds an additional property for the previous tab. When a new tab is configured to be opened, the current tab is set as the previous tab for the managed bean for the new tab.
A disclosure listener, the MainAreaBackingBean.setLastDisclosedItem, handles user clicks in the tab UI. When the user clicks a tab, two events occur: one for the tab that is going out of focus, and one for the tab that is coming into focus. First, during the out-of-focus event, the tab that is going out of focus is captured in the managed bean's instance variable. Then, during the in-focus event, that instance variable's value is set as the previous tab in the managed bean for the newly focused tab.
Through user clicks, it is possible to create a circular dependency in which TabA's previous tab is TabB, whose previous tab is TabA. In this case, when TabA is closed, TabB would come into focus. However, when TabB is consequently closed, TabA would have to be focused, but it has already been closed. This corner case is handled by moving the focus to the first tab in the Main Area.
No-Tab Navigation
To keep track of all task flows that have been opened, a Stack instance variable is introduced in the MainAreaHandler method. When a new task flow is opened, the task flow ID and its associated parameter values are added to the stack.
Having this information, the call to closeMainTask pops the stack to get the last task flow ID and its parameter values that were displayed, and reinitializes the Main Area with that task flow and parameter information.
The UI Shell exposes the means to control the disclosure state of the Regional Area as a whole, and the disclosure state of individual panels within the Regional Area panel accordian.
Declarative support: Allows you to specify the initial state of the following on loading a Work Area JSPX page.
Within the Regional Area, whether or not a Regional Area task panel is collapsed or disclosed.
A given Regional Area panel that is disclosed on initial rendering of the page should reflect its assigned pixel height to determine how much screen real estate it occupies.
Programmatic support: Allows you to control the initial or subsequent state of the following within a Work Area JSPX page.
By default, the disclosure state is driven by what is specified declaratively. However, after initial page load, you can override the declarative default and, for example, render the Work Area with the Regional Area collapsed (overriding the declarative setting of rendering that Work Area with the Regional Area disclosed).Disclosing a collapsed Regional Area splitter programmatically in response to a UI action by the user (such as a button click or menu selection).
Declarative support is provided using attributes exposed on the respective item node in the Menu Model.
For regional panels:
There are separate APIs that expose parameters to refresh the task flow and set the disclosure state for the showDetail items in the panel accordian. The showDetail items are identified by the task flow ID specified.
Implementation Notes
Specify the default values for the regional or main splitter position and collapsed state in the menu for the item node that represents the page, using the regionalAreaWidth and isRegionalAreaCollapsed properties. A sample entry in the menu file resembles Example 13-20.
Example 13-20 Sample Menu File Entry
<itemNode id="itemNode_SvcCenter"
label="#{adfBundle['oracle.apps.fnd.applcore.patterns.demo.patterns_demo_menuBundle'].SERVICE_CENTER}"
action="adfMenu_SvcCenter" focusViewId="/SvcCenter"
isDynamicTabNavigation="false" regionalAreaWidth="250" isRegionalAreaCollapsed="false">
If these properties are not set in the menu for the top-level item node that represents the page, then these default values are used:
regionalAreaWidth="256" isRegionalAreaCollapsed ="false"
For programmatic control, drag and drop one of the following corresponding methods from the FndUIShellController data control.
discloseRegionalArea
collapseRegionalArea
setRegionalAreaWidth
Two APIs shown in Example 13-21 are exposed as data control methods under FndUIShellController data control.
Example 13-21 APIs Exposed as Data Control Methods Under FndUIShellController
/**
* Discloses a Regional Area task.
*
* @param taskFlowId Task flow to disclose
* @param keyList Key list to locate the task flow instance.
* This is a semicolon-delimited keys or key-value pair.
* For example, "key1;key2=value2". If only the key is specified,
* the value is picked up from the parametersList with the same
* name as the key.
* @param parametersList Parameters list for the task flow.
* This is a semicolon-delimited String
* of name-value pairs. For example,
* "param1=value1;param2=value2".
* @param label Label for the task flow*
* @param forceRefresh Default false. If false, task flow reinitialization
* depends on whether some parameters are passed into parametersList, where
* the presence of parameter values causes reinitializaiton and the absence of
* parameter values does not. forceRefresh true always causes reinitialization
* of the task flow regardless of the value for parametersList.
* @return For internal Contextual Event processing
*/
public FndMethodParameters discloseRegionalTask(String taskFlowId,
String keyList,
String parametersList,
String label,
Boolean forceRefresh,
FndMethodParameters methodParameters)
/**
* Collapses a Regional Area task.
*
* @param taskFlowId Task flow to collapse
* @param keyList Key list to locate the task flow instance.
* This is a semicolon-delimited list of key-value pairs.
* For example, "key1=value1;key2=value2".
* @return For internal Contextual Event processing
*/
public FndMethodParameters collapseRegionalTask(String taskFlowId,
String keyList,
FndMethodParameters methodParameters)
Notes:
Declarative support allows the inflexibleHeight property to control the pixel height of the Regional Area panel. Programmatic support does not have this allowance.
Programmatic support allows the forceRefresh property to make it possible to refresh a task without passing in any parameters. Declarative support does not have this allowance.
Refreshing a Regional Area task without disclosing the task is not supported.
Multiple Regional Area tasks are allowed to be disclosed at the same time. A switch to force showing only one task at a time is not provided.
Support for persisting any of these settings explicitly altered by the user during a session, across sessions, is not a part of this feature.
The UI Shell provides the means to control the disclosure state of the Contextual Area through either declarative or programmatic support.
Declarative support lets you specify the initial state when loading a Work Area JSPX page. It determines whether or not the Contextual Area (as a whole) is collapsed or disclosed.
Programmatic support lets you control the initial or subsequent state of the Contextual Area within a Work Area JSPX page.
By default, the disclosure state is driven by what is specified declaratively. However, after the initial page load, you can override the declarative default and, for example, render the Work Area with the Contextual Area collapsed (overriding the declarative setting of rendering that Work Area with the Contextual Area disclosed).
Disclosing the collapsed Contextual Area splitter programmatically in response to a UI action by the user, such as a button click or menu selection.
Samples of Expected Behavior
A Work Area JSPX page loads with the Contextual Area collapsed or disclosed when the page renders, based on the declarative setting. If the Work Area is loaded as a result of a Main Menu invocation, then declarative options always are used for the disclosure state.
If a Work Area loads as a result of a page navigation from another Work Area, programmatically set options may override declarative settings.
Implementing the Contextual Area Splitter
Follow these steps to implement the Contextual Area splitter:
Extend the contextual-area-task-flow-template task flow template into the page task flow, as shown in Example 13-22.
Specify values for the Contextual Area splitter position and the collapsed state in the menu for the item node that represents the page using the contextualAreaWidth and contextualAreaCollapsed properties. A sample entry in the menu file will resemble Example 13-23.
Example 13-23 Example of contextualAreaWidth and contextualAreaCollapsed Properties
<itemNode focusViewId="<focus_view_id>" id="<page_id>" label="<page_label>"
taskType="dynamicMain"
taskFlowId="/WEB-INF/page2-task-flow-definition.xml#page2-task-flow-definition"
contextualAreaCollapsed="true"
contextualAreaWidth="0"/>
If these properties are not set in the menu for the top-level item node that represents the page, then these default values are used:
contextualAreaWidth="256" contextualAreaCollapsed ="false"
For programmatic control, drag and drop one of the corresponding methods from the FndUIShellController data control:
collapseContextualArea
contextualAreaWidthSelection
To set these values when opening a new task, drag and drop the openMainTask method from FndUIShellController data control and pass in the contextualAreaWidth and contextualAreaCollapsed parameters through "methodsParameters > NamedData" as shown in Example 13-24.
Set the method in the page managed bean to set the contextualAreaWidth and contextualAreaCollapsed values, as shown in Example 13-24.
Example 13-24 Setting the contextualAreaWidth and contextualAreaCollapsed Values for openMainTask
<methodAction id="openMainTask" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="openMainTask"
IsViewObjectMethod="false" DataControl="FndUIShellController"
InstanceName="FndUIShellController.dataProvider"
ReturnName="FndUIShellController.methodResults.openMainTask_FndUIShellController_dataProvider_openMainTask_result">
<NamedData NDName="taskFlowId"
NDValue="/WEB-INF/page6-task-flow-definition.xml#
page6-task-flow-definition"
NDType="java.lang.String"/>
<NamedData NDName="keyList" NDValue="" NDType="java.lang.String"/>
<NamedData NDName="parametersList" NDType="java.lang.String"/>
<NamedData NDName="label" NDType="java.lang.String"/>
<NamedData NDName="reuseInstance" NDType="java.lang.Boolean"/>
<NamedData NDName="forceRefresh" NDType="java.lang.Boolean"/>
<NamedData NDName="loadDependentFlow" NDType="java.lang.Boolean"/>
<NamedData NDName="methodParameters"
NDValue="#{<ManagedBean.Method>}"
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.
bean.FndMethodParameters"/>
To set these values using the Navigate API to navigate to a task flow, drag and drop the navigate method from FndUIShellController and pass in the contextualAreaWidth and contextualAreaCollapsed parameters through "methodsParameters > NamedData" as shown in Example 13-25.
Set the method in the page managed bean to set the contextualAreaWidth and contextualAreaCollapsed values, as shown in Example 13-25.
Example 13-25 Setting the contextualAreaWidth and contextualAreaCollapsed Values for navigate
<methodAction id="navigate" RequiresUpdateModel="true" Action="invokeMethod"
MethodName="navigate" IsViewObjectMethod="false"
DataControl="FndUIShellController"
InstanceName="FndUIShellController.dataProvider"
ReturnName="FndUIShellController.methodResults.navigate_FndUIShellController_dataProvider_navigate_result">
<NamedData NDName="viewId" NDType="java.lang.String"/>
<NamedData NDName="webApp" NDType="java.lang.String"/>
<NamedData NDName="pageParametersList" NDType="java.lang.String"/>
<NamedData NDName="navTaskFlowId" NDType="java.lang.String"/>
<NamedData NDName="navTaskKeyList" NDType="java.lang.String"/>
<NamedData NDName="navTaskParametersList" NDType="java.lang.String"/>
<NamedData NDName="navTaskLabel" NDType="java.lang.String"/>
<NamedData NDName="methodParameters"
NDValue="#{<ManagedBean.Method>}"
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.
bean.FndMethodParameters"/>
</methodAction>
Multiple Regional Area panels can be open at the same time, instead of showing only one panel at a time.
Because the desired size of each panel will be different, you can set the pixel height for each of the panels by specifying the inflexibleHeight property in the item node that represents a Regional Area panel, as shown in Example 13-26.
Menu metadata used in Oracle Fusion Applications is divided into global menu data, consisting of the Home page tabs, the Navigator menu (also known as the Main menu), and the Preferences menu.
The Navigator menu and Home page tabs contain information from different applications, yet each application must be able to be developed independently. To bring this information together, a Global Menu Model is provided.
Navigation to a page is accomplished by constructing and executing a URL. Matching the application name from the distributed menu metadata to its deployment information will dynamically create the host/port portion of the URL. Other page parameters are held in the existing page-level menu metadata.
The Task Menu, create URL, and navigation API allow other declarative and programmatic access to page navigation. The UI Shell Global Area also will support a Home page link for page navigations.
Global Menu Model Service
This model:
Contains at least the label, the application name, and the viewID
Calls the Policy Store (optimized bulk authorization) to get the subset of these menu items to be rendered for that user
Example of Global Menus
The Global Menu Model presents a cascading appearance, shown in Example 13-31.
Global Menu Behavior
Items to which the user does not have access will not be displayed.
A category is hidden if there is no child to display.
If a menu entry length is greater than 27 characters, ellipses (...)are displayed. The entire entry will be displayed in a tool tip when the pointer hovers over the entry.
Parent and children categories will not be split into different columns.
Note:
Before you create menus, you first must create JSF pages using the UI Shell template.
These Global Menus span JavaEE applications.
Navigator Menu: This is the global menu that is displayed in the UI Shell Global Area.
Home Page Menu: The Home page tabs are actually each a JSPX page assembled using menu metadata.
Preferences Menu: The User Preferences page has a task list link to all other preferences pages within Oracle Fusion Middleware. This is assembled using menu metadata.
Table 13-3, Table 13-4, and Table 15-1 (in Chapter 15, "Implementing Additional Functions in the UI Shell") list the menu attributes added by Applications Core to the menu XML in addition to what is provided by Oracle ADF.
Table 13-3 <groupNode> Attributes
| Attribute | Data Type | Required | Description |
|---|---|---|---|
|
|
xsd:string |
N |
Bundle key used for label; the key will be looked up in the resource bundle specified by the |
Table 13-4 <itemNode> Attributes for Global Menus
| Attribute | Data Type | Required | Description |
|---|---|---|---|
|
|
xsd:string |
Y |
The |
|
|
xsd:string |
N |
This is the page ID. This can be found by looking in the |
|
|
xsd:string |
N |
The resource name that is used for securing the item node. |
|
|
String |
N/A |
This attribute is used for pages. Check the security of the page against the policies that are located in LDAP. The |
|
|
String |
N/A |
This is a task-level |
|
|
String |
N/A |
This is a page-level |
|
|
String |
N/A |
The <itemNode id="itemNode_otn" destination="http://www.oracle.com/technology/index.html"/> |
The Navigator menu, shown in Figure 13-18, is rendered when the Navigator link is clicked on the UI Shell.
Note:
The Navigator menu is used as the example for how a developer implements a Global Menu, but the steps will be similar for the Preferences and Home menus.
The Navigator menu metadata may be pointing to target work area pages in various applications. To simplify the runtime behavior, one XML file contains all the menu entries. An Applications Core application will deploy these menus to Oracle Metadata Services (MDS). Each application will read these directly from MDS.
Each application must be configured so that the shared library can read the menus from MDS.
To implement a Global Menu:
Verify that the web.xml file of the application has the correct Java Authentication and Authorization Service (JAAS) filter to enable checking menu security against Oracle Platform Security Services (OPSS), as shown in Example 13-27.
Example 13-27 Sample JAAS Filter
<filter>
<filter-name>JpsFilter</filter-name>
<filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
<init-param>
<param-name>enable.anonymous</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>remove.anonymous.role</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>application.name</param-name>
<param-value>crm</param-value>
</init-param>
<init-param>
<param-name>oracle.security.jps.jaas.mode</param-name>
<param-value>subjectOnly</param-value>
</init-param>
</filter>
The application.name parameter, as shown in the example, in the web.xml file is the application family value. The choices are crm, fscm, and hcm. This value is used to create the stripe in LDAP.
Update the weblogic-application.xml file. As shown in Example 13-28, set the application-param that has the param-name jps.policystore.migration to OFF.
In the weblogic-application.xml file, ensure that the application-param that has the param-name jps.policystore.applicationid is set to the correct stripe, as shown in Example 13-29. This is the same as the application.name property of the web.xml file.
Add the following entry in the web.xml file:
<listener> <listener-class>oracle.apps.fnd.applcore.menu.service.MenuFragmentServiceContextListener</listener-class> </listener>
Global menu security depends on applications using a standalone LDAP server.
Note:
Global security only works with standalone WebLogic Server.
ADF Menu Security is enabled by default. If you need to disable menu security, such as for testing, start WebLogic Server after setting the JAVA_OPTIONS environment variable in the setDomainEnv.sh file:
JAVA_OPTIONS = -DAPPLCORE_TEST_SECURED_MENU=N
Before you enforce user actions, define roles, principals, and actions in the database.
Functional security will always prevent a user from accessing a page or task flow for which the user does not have privilege. To improve the user experience, global menus can be hidden if the user does not have access to that page. There are two different security features for this:
The global menus have a securedResourceName attribute, which should be the value of the page resource against which security can be checked. For pages, this is the page definition file.
The menus also have a rendered attribute. This can be used to evaluate an Expression Language security expression. If rendered="false" (false being the outcome of the expression), the menu item will be hidden even if the user has access to the page. There are certain times you would want to do this. For instance, consider a person working in HR as a consultant, not an employee. You might want a menu entry for editing employee data under an HR category, without showing an entry under the Employee Self-Service category that also leads to the same page. See Example 13-30.
Example 13-30 Expression Language Expression to Evaluate a User's Access Rights
rendered="#{securityContext.userInRole['EMPLOYEE_ROLE']}"
The Expression Language expression should never check the page definition. However, you can use the Expression Language expression to check security of a person's role because that is in LDAP.
The applicationStripe attribute determines which LDAP stripe is checked for the securedResourceName attribute.
Menu files will be referenced through MDS. This means they can be located in a table or in a file system directory. Determine where you want this directory to be located. This is where your root_menu.xmlfile and other menu files will be located. For Global menu attributes, see Section 13.5.1.1, "Menu Attributes Added by Oracle Fusion Middleware Extensions for Applications (Applications Core)."
Create the Navigator menu.
Example 13-31 shows a sample Navigator menu.
Example 13-31 Example of a Navigator Menu
<menu xmlns="http://myfaces.apache.org/trinidad/menu">
<groupNode id="groupNode_my_information"
idref="_groupNode_my_information_"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].MY_INFORMATION}">
<itemNode id="itemNode_my_information_my_portrait"
label="#{bundleVar.MY_PORTRAIT}" focusViewId="/MyPortrait" webApp="HcmCore"
securedResourceName="oracle.apps.hcm.people.portrait.ui.page.MyPortraitPageDef"
<groupNode id="groupNode_my_information_compensation"
idref="_groupNode_my_information_compensation_"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].COMPENSATION}">
applicationStripe="hcm"
</groupNode>
<groupNode id="groupNode_my_information_career"
idref="_groupNode_my_information_career_"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].CAREER}">
<itemNode id="itemNode_my_information_goals"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].GOALS}"
focusViewId="/ManageGoalsWorkArea" webApp="HcmTalent"
securedResourceName="oracle.apps.hcm.goals.core.publicUi.page.ManageGoalsWorkAreaPageDef"/>
<itemNode id="itemNode_my_information_performance_management"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PERFORMANCE}"
applicationStripe="hcm"
focusViewId="/PerformanceWorkArea" webApp="HcmTalent"
securedResourceName="oracle.apps.hcm.performance.documents.publicUi.page.PerformanceWorkAreaPageDef"/>
</groupNode>
<groupNode id="groupNode_my_information_procurement"
idref="_groupNode_my_information_procurement_"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PROCUREMENT}">
<itemNode id="itemNode_my_information_purchase_requisitions"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].PURCHASE_REQUISITIONS}"
focusViewId="/PrcPorCreateReqWorkarea" webApp="Procurement"
securedResourceName="oracle.apps.prc.por.createReq.publicUi.page.PrcPorCreateReqWorkareaPageDef" applicationStripe="hcm"/>
<itemNode id="itemNode_my_information_self_service_receipts"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].RECEIPTS}"
applicationStripe="hcm"
focusViewId="/RcvSelfServWorkarea" webApp="Logistics"
securedResourceName="oracle.apps.scm.receiving.selfService.workarea.ui.page.RcvSelfServWorkareaPageDef"/>
applicationStripe="hcm"/>
</groupNode>
</groupNode>
</menu>
Create the application's Navigator menu files.
The next files in the menu hierarchy can contain groupNodes that appear as non-clickable categories, itemNodes that are clickable to start a page, or references to more menu files. If itemNodes were included that were not deployed, they will not appear because what was deployed is checked against the deployment tables. Applications Core requires that if a groupNode has no child nodes, which could happen through security enforcement, the groupNode itself will not be rendered.
There are situations, particularly with simpler applications, when the default enterprise-level menu structure is not suitable. In these cases, you may want to display the Navigator menu as a series of dropdown buttons.
To switch the UI Shell rendering so the Navigator menu renders as dropdown buttons in a horizontal row, set the isSelfService attribute to "true" on the .jspx page that extends the UI Shell template. That is, inside the <af:pageTemplate> tag, add the following:
<f:attribute name="isSelfService" value="true"/>
The Personalization menu options shown in Figure 13-19 let you set your preferences, edit the current page, and reset the content and layout. The menu is supplied automatically by the UI Shell and requires no developer work.
The Preferences menu only appears if you have the ApplSession filter and mapping set up. See Section 48.2, "Configuring Your Project to Use Application User Sessions.".
Set Preferences
You create the actual Preferences dialog, such as shown in Figure 13-22. See Section 13.7 for the details of how to implement the Preferences menu.
Edit Current Page
This option is displayed only if the displayed page has been marked as able to be user-edited (if the isPersonalizableInComposer attribute in af:pageTemplate is set to true). Selecting this option will start the editing feature and the page will resemble Figure 13-20. Click Close to return to the page. Click Customization Manager to change the displayed page in Oracle Composer. For more information about the Customization Manager, see the "Customization Manager" section in the "Extending Runtime Editing Capabilities Using Oracle Composer" chapter, and the "Manage Customizations" section of the "Introduction to Oracle Composer" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal (Oracle Fusion Applications Edition). Note that changes are for just this user and therefore are called personalization. See Chapter 62, "Creating Customizable Applications".
Reset Content and Layout
Select this option to discard any personalization changes and return to the default settings. Note that resetting layout and content is for that page. In particular, if any task flows are personalized on that page using Oracle Composer, they are not reset by this menu item.
Set Preferences, shown in Figure 13-21, is a link in the Global Area for easy access to setting preferences for the current application, general user preferences, or for any other application preference in Oracle Fusion Middleware. For more information about this Global menu, see Section 13.5, "Working with the Global Menu Model."
Preferences are pages that can set system wide settings that applications can access. There are general preferences that affect all applications, and there can be application-specific preferences. General preferences include language, date format, and currency. General preferences are stored in LDAP so they can be accessed from any application. Application preferences are usually stored in the applications on database tables, but they can be stored in LDAP also.
The Preferences link from the Global Area will open a Work Area that shows the preferences related to the currently displayed page.
Links in the left hand side will allow navigation to any Preferences Work Area page within the entire Oracle Fusion product. This page will be rendered using Applications Core menu federation abilities. As the developer, you will own the menu files.
If an application is not installed, or the user does not have access, the entry in the task list menu should not appear. If a user does not have access to a particular setting within a page, you must use the rendered property with a security expression behind it.
For each application, there should be a preferences page. The preferences page uses the same path of the current application, but it uses a page name of preferences.jspx.
If no associated preferences page exists, a default General Preferences page will be shown. This page shows global Applications Core most-used preferences.
If there are several preference pages associated with an application, such as a Common Setting page and more specific pages, only one preferences page as a target from the global preferences link can be defined per application. (There will be a default name for the target focusViewID of the preferences page for an application.) In the preferences work area, other links are available from the task list to more specific pages or task flows. (Links in the task list can contain other focusViewIDs that belong to the same application as the default preference page.)
When the first application is deployed, it will become the location of the General Preferences page.
Several pages of an application can all point to the same preferences page.
More than one application cannot point to the same preferences page. This implies that each application can have its own preferences page, and if two applications want to share a common preferences page, they can, but it can be navigated to only from the task list. Therefore, from the Preferences link, the user always sees the more specific preferences page of that application.
A preferences page will be like any other Work Area page. Preference values are not supported in integrated Oracle Weblogic Server LDAP, only an external LDAP is supported. The task list will be loaded as a defaultRegional task flow and the Main Area will be a defaultMain task flow.
Work Area Title
Each preferences page should display a title similar to {Category_name:Page_name}. This can be done though an Expression Language expression and will not be created automatically from the framework.
The name that appears in the task list can be different from the page title. This is allowed because the task list name is generated from the task list preference distributed menu metadata, while the page title will be from the local page-level menu metadata.
Tasklist and Navigation Pane
Each page needs its Application Menu metadata to specify that it wants the Preferences task list menu in the defaultRegional area as well as in the defaultMain task flow.
This menu can be a two-level menu having categories with links under each category.
Task List Federation
The task list will be a task flow that will contain links to all preference pages throughout Oracle Fusion Middleware.
Each application will provide the preferences menu files that contain task list links to preferences pages delivered by that application. The preferences task list should follow the Navigator menu architecture recommendations where it uses sharedNode references to bring in menus from each application so they can be patched independently. Applications Core will automatically federate the menu metadata so the task list that is rendered will contain all the entries from all applications (filtered by security).
Individual menu files will have versions like other distributed menu files, so any application can apply a patch and the new menu will take precedence over an older version when federated.
Task List Can Link Only to Full Pages (Not to Specific Task Flows)
The task list will not start task flows dynamically, but will load a Preferences workarea page. This is because the task list menu must be federated and only page-level entries are allowed in a federated menu.
No-Tabs Mode
The Preferences page should use a no-tabs mode. This is a standard, not controlled through any code. You can use tabs if all task flows are defaultMain. See Section 13.2.3.4, "Supporting No-Tab Work Areas" for more information.
Task List Security
The task list will be filtered by functional page-level security for that user. If all entries in a category are restricted, then the category should not appear either.
Preferences Settings
Settings will be a view activity in a task flow. It will follow other user experience standards so it should be built using an Applications Panel. This means the action buttons will appear at the top.
Different preferences pages can change the same backend setting, depending upon applications design. If this is needed, it should be stored in a common area, such as LDAP, or be in the General Preferences page.
Application preferences pages are deployed with the corresponding product pages.
The design should be similar to that shown in Figure 13-22.
After the WebLogic Server console is configured, follow these steps to create an Oracle Fusion web application that uses UI Shell pages:
Create a UI Shell page that is used solely for the user preferences, such as PreferencesUI.jspx.
Set the isDynamicTabNavigation property to false for the PreferencesUI page entry in the menu.
Add the following task flow as a default Regional Area under the preferences page entry: "/WEB-INF/oracle/apps/fnd/applcore/pref/ui/mainflow/GeneralPreferencesFlow.xml#GeneralPreferencesFlow"
The final menu entries for the page will appear similar to those shown in Example 13-32.
Example 13-32 Sample General Preferences Menu Entries
<itemNode id="itemNode_untitled2" label="Preferences"
action="adfMenu_PreferencesUI" focusViewId="/PreferencesUI"
isDynamicTabNavigation="false" webApp="Demo">
<itemNode id="def1" focusViewId="/PreferencesUI" label="General Preferences"
taskType="defaultRegional"
taskFlowId= "/WEB-INF/oracle/apps/fnd/applcore/pref/ui/mainflow/GeneralPreferencesFlow.xml#GeneralPreferencesFlow"/>
</itemNode>
The results of this example should display the basic Preferences menu entries in the default Regional Area that can be opened to display subflows for each preferences subtask (for instance, Accessibility and Appearance).
The General Preferences task flow that is exposed also renders the Preferences Menu Model links by using a call to the Menu Service API.
The Preferences menu will be part of a central Utility application (menu web service) that will be deployed in the server. As a developer, you maintain the Preferences menu.
On any UI Shell page, the Global Area contains a Personalization menu that contains a Set Preferences link. This link will redirect the user to an application-specific Preferences page, depending upon the entry in the menu data.
Example 13-33 shows sample Preferences menu data.
Example 13-33 Example Preferences Menu Data
<?xml version="1.0" encoding="UTF-8" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu" version="1">
<itemNode id="preferences_node_a" label="Preferences Page A"
action="preferences_node_a" focusViewId="/preferencesA"
webApp="fnd" prefForApps="gl, hr" >
<itemNode id="Flow 1" label="Service Flow"
focusViewId="/preferencesA" taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/ServiceFlow.xml#ServiceFlow"
parametersList="id=userName" />
</itemNode>
<itemNode id="preferences_node_b" label="Preferences Page B"
action="preferences_node_b" focusViewId="/preferencesB"
webApp="fnd" prefForApps="fn" >
<itemNode id="Flow 2" label="Request Flow"
focusViewId="/preferencesB" taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/RequestFlow.xml#RequestFlow"
parametersList="id=userName" />
</itemNode>
<itemNode id="preferences_node_d" label="Preferences Page D"
action="preferences_node_d" focusViewId="/PreferencesUI"
webApp="Demo" prefForApps="Demo"
<itemNode id="Flow 2" label="Request Flow"
focusViewId="/preferencesB" taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/AcceptanceFlow.xml#AcceptanceFlow"
/>
</itemNode>
</menu>
In the example menu XML file, each parent item node represents a Preferences UIShell page. Its child nodes refer to the application-specific task flow in which the Preferences page exists.
For example, the first itemNode entry refers to the preferencesA page that is part of the FND webApp. The Service Flow child node is a task flow that belongs to the FND webApp.
For each parent itemNode, there is an attribute called prefForApps that contains a list of webApp names. This means that the itemNode is a common preferences page for those listed webApps.
For example, the Preferences page is common for two webApps -- gl and hr. This essentially means that all the Dashboards and Work Area UI Shell pages in the gl and hr webApps will be redirected to this preferencesA page, which is in webApp FND, when the Set Preferences link is clicked.
All the task flows under each preferences page itemNode will be displayed in the General Preferences task flow as navigation links. Therefore, all preferences pages will have access to these task flows.
To test the general preferences task flows, configure user session and ADF Security for the test application. See Chapter 48, "Implementing Application User Sessions."
When configuring ADF Security, there is no need to define users, because you already are using an Oracle Internet Directory store that will authenticate the users existing in the policy store.
See Chapter 20, "Working with Localization Formatting."
A use case exists where the UI must use an Expression Language expression to check whether the accessibility mode is set to screenReader to render screen reader-friendly components in screenReader mode. The recommended method to do this uses #{requestContext.accessibilityMode} and is documented in "How to Configure Accessibility Support in trinidad-config.xml" in "Developing Accessible ADF Faces Pages" in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).
The Password link on the General Preferences page will point to the Password Management page from the Oracle Identity Management administration application. This page is maintained by the Oracle Identity Management team. For the Password link to redirect to the pwdmgmt.jspx page, the deployment information of the current application and the Oracle Identity Management administration application must be populated correctly in the Oracle Fusion Applications Functional Core (ASK) tables.
The Preferences most end users want to set are Language, Accessibility, and Regional. This section discusses how to configure these Preferences and what the default rules are, such as what happens if you do not set the Language Preference.
See Chapter 20, "Working with Localization Formatting" for more information about localization of Preferences.
When a session is created, it will use the language provided in the ORA_COMMON_PREFS cookie if it is set to a valid language. Inside the cookie, the fusionapps_language attribute is used to determine the language. There also is a local attribute that is for non-Oracle Fusion applications so that Oracle Fusion applications have their own attribute in the cookie and allowing other applications to keep their own language preference. Oracle Identity Management knows which to use based on a system value oracle.fusion.appsmode that is set at provisioning time.
If it is not a valid language or if the cookie does not exist, the browser language is used.
If for some reason the browser language is not valid, the seeded FND_LANGUAGE profile option is checked to determine the default language, which defaults to American English. If accessing a protected page, the login screen appears. This login screen may allow the user to select a language for the session. If selected, this will override the language. If the user does not select anything on login and if the user has a language preference previously saved, this will override the language if it is an installed language. If saved, it would be held in the LDAP settings for the Oracle Fusion applications Language setting in the orclFALanguage attribute of the orclIDXPerson object. This is controlled by Oracle Identity Manager.
Users can set the Language preference by selecting the Set Preferences link from the Personalization menu in the Global Area. The Language option will look similar to Figure 13-23.
Oracle Fusion applications follow the Apache Trinidad standards for Accessibility.
Users can set the Accessibility preference by selecting the Set Preferences link from the Personalization menu in the Global Area. The Accessibility option will look similar to Figure 13-24.
The default Regional settings are based on the selected Language setting unless the Regional setting is saved explicitly. That is, no matter how the current language is derived, whether it is from login, the browser or LDAP, if the Regional settings are not yet set, they will default from the language. But if the user sets the Regional settings and then sets the Language setting, the Regional settings will not be changed.
Users can set the Regional preferences by selecting the Set Preferences link from the Personalization menu in the Global Area. The Regional options will look similar to Figure 13-25.
The Administration Menu, shown in Figure 13-26, is displayed only if the logged-in user has the appropriate privileges. See Section 13.8.1, "How to Secure the Administration Menu". The menu is supplied automatically by the UI Shell and requires no developer work.
Customize [name_of_page] Pages...
Select this option to customize the current page for multiple users using the customization layer picker dialog.For information about customization, see Chapter 62, "Creating Customizable Applications" and "Customizing Existing Pages" in the Oracle Fusion Applications Extensibility Guide.
Customize Global Page Template
Select this option to open the page in composer mode. All the global items can be selected so you can customize them. Customization is done at the site layer so it will apply to all pages, not just the one you are on. (When you use Customize [name of page] Pages, all the content except the global content is available for customization.)
Manage Customizations...
Select this option to start the Customization Manager.
For information about customization, see Chapter 62, "Creating Customizable Applications" and "Customizing Existing Pages" in the Oracle Fusion Applications Extensibility Guide. For more information about the Customization Manager, see the "Extending Runtime Editing Capabilities Using Composer" chapter, and the "Introduction to Composer" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal (Oracle Fusion Applications Edition).
For information about defining and configuring namespaces when promoting a page fragment to a label, see "Updating Your Application's adf-config.xml File" in the "Performing Composer-Specific MDS Configurations" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal (Oracle Fusion Applications Edition).
Manage Sandboxes...
Select this option to manage sandboxes on your system.
The Sandbox is built on top of the standard Sandbox feature from Oracle Metadata Service. See "Using the Sandbox Manager" in the "Understanding the Customization Development Lifecycle" chapter of the Oracle Fusion Applications Extensibility Guide.
Setup and Maintenance...
Select this option to start the Oracle Fusion Functional Setup Manager application. See the Oracle Fusion Functional Setup Manager User's Guide and the Oracle Fusion Functional Setup Manager Developer's Guide.
Highlight Flexfields
No separate implementation is required. This option is available to any user who has the permission to view the Administration menu.
Select this option to highlight the Descriptive Flexfields (DFF) and Key Flexfields (KFF) on the runtime page.
When this mode is on, the page displays an information icon by each DFF and KFF. This will be displayed whether or not any Flexfield segments have been configured.
Hovering over the icon shows the Flexfield details. Administrators can note the DFF or KFF code so they can search for it in the Manage Descriptive Flexfields setup task in Oracle Fusion Functional Setup Manager.
The option changes to Unhighlight Flexfields so that administrators can return to the normal view of the page.
For more information about Flexfields, see Chapter 21, "Getting Started with Flexfields."
If you need the Administration link, include the privilege and the permission in the JAZN file as defined in Example 13-34. All administrator roles must inherit the Applications Core "Administration Link View Duty" duty role. This duty role gives access to the "View Administration Link" privilege.
Example 13-34 Required Privilege and Permission in JAZN File
<app-role>
<name>FND_ADMINISTRATION_LINK_VIEW_DUTY</name>
<display-name>Administration Link View Duty</display-name>
<description>Provides access to the Administration Link on the UI Shell</description>
<guid>EA1D0BF0BC096F11B18BDEBD5F4BDB48</guid>
<class>oracle.security.jps.service.policystore.ApplicationRole
</class>
<members>
<member>
<class>oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl
</class>
<name>FND_APPLICATION_DEVELOPER_JOB</name>
</member>
<member>
<class>oracle.security.jps.internal.core.principals.JpsXmlEnterpriseRoleImpl
</class>
<name>FND_APPLICATION_ADMINISTRATOR_JOB</name>
</member>
</members>
</app-role>
Privilege
<app-role>
<name>FND_VIEW_ADMIN_LINK_PRIV</name>
<display-name>View Administration Link</display-name>
<description>Privilege to view administration link in UI shell. This privilege is available from Roles(s): Supply Chain Application Administrator,Cost Accountant,Application Implementation Consultant,Application Developer,Application Administrator</description>
<guid>B14A48E74ECF633A3C6E4AF95816474D</guid>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<members>
<member>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<name>FND_ADMINISTRATION_LINK_VIEW_DUTY</name>
<guid>EA1D0BF0BC096F11B18BDEBD5F4BDB48</guid>
</member>
</members>
</app-role>
Permission and Grant to be included in JAZN file
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<name>FND_VIEW_ADMIN_LINK_PRIV</name>
<guid>B14A48E74ECF633A3C6E4AF95816474D</guid>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.ResourcePermission</class>
<name>resourceType=FNDResourceType,resourceName=FND_Administration_Menu</name>
<actions>launch</actions>
</permission>
</permissions>
</grant>
The Help menu, shown in Figure 13-27, provides user access to the standard help system and to troubleshooting and diagnostic tools. The menu is supplied automatically by the UI Shell and requires no developer work.
User Productivity Kit
The User Productivity Kit (UPK) option will be available when the UPK has been purchased, installed and configured.
This context-param entry must be added to the web.xml file:
<context-param>
<description>This parameter notifies ADF Faces that the ExecutionContextProvider service provider is enabled.
When enabled, this will start monitoring and aggregating user activity information for the client initiated
requests. By default this param is not set or is false.
</description>
<param-name>oracle.adf.view.faces.context.ENABLE_ADF_EXECUTION_CONTEXT_PROVIDER</param-name>
<param-value>true</param-value>
</context-param>
For recording, it may be necessary to turn on automation if all client components need to be sent down. The following parameter should be present in the application web.xml:
<context-param>
<description>
This parameter notifies ADF Faces that test automation is being used.
When enabled, this will cause the ids of components with testId
attributes to be set to the value of the testId and the client component
attribute of the component to be forced to true.
TestId attribute is now deprecated; use the 'id' attribute instead.
</description>
<param-name>oracle.adf.view.rich.automation.ENABLED</param-name>
<param-value>true</param-value>
</context-param>
Also, "upk" must be provisioned by the System Administrator. That is, an entry with DEPLOYED_MODULE_NAME = "upk" must be added in the ASK deployment tables. These tables are populated at deployment time through Oracle Fusion Functional Setup Manager tasks. Without the entry, the menu item "User Productivity Kit ..." will not be shown in the Help menu.
Applications Help
Select this option to open the help system in a separate window.
Troubleshooting
When you select the Troubleshooting option, an additional menu, similar to Figure 13-28, is displayed.
Troubleshooting Options
Select this option to display the Options dialog, as shown in Figure 13-29.
Enable all: Select this option to enable all other options on the dialog. When Enable all is selected, removing the selection from any of the other check boxes will deselect Enable all.
Applications logging, severity level and modules are stored as user-level profile options in profile tables. The corresponding profile option names are AFLOG_ENABLED, AFLOG_LEVEL, and AFLOG_MODULE. See "Configuring Settings for Log Files and Incidents" in Oracle Fusion Applications Administrator's Guide for information.
Because applications logging, severity level, and modules are profiles, when users click Save and Close, user-specific profile values will be inserted into the profiles. If users decide to revert the setting to the default site profile, they must use the Functional Setup Manager to remove their own profile.
After making changes to any one of the options for applications logging, severity level, or modules, the user must log out of the Oracle Fusion application, close the browser session, and log back in for the new options to take effect. These logging profiles are cached in the user session and initialized when a user logs into an Oracle Fusion application.
Database trace: This option enables the SQL trace feature for all database connections used by the current user session. See "Understanding SQL Trace and TKPROF" in the Oracle Database Performance Tuning Guide.
For SQL trace, the trace file will have the FND session ID appended to the end. For example, mysid_ora_4473_881497BF7770BEEEE040E40A0D807BB1.trc.
The trace file can be found on the database host in the directory specified by the user_dump_dest init.ora parameter.
Capture bind variables:
Select this option to enable the SQL trace option to also capture bind variables.
Capture wait events:
Select this option to enable the SQL trace option to also capture wait events.
PL/SQL profiler: This option enables the PL/SQL hierarchical profiler for all the connections used by the current user session. See "Using the PL/SQL Hierarchical Profiler" in the Oracle Database Development Guide.
For the PL/SQL profiler, the output will be in the directory defined by APPLLOG_DIR. The exact path for APPLLOG_DIR can be found on the database host by using the SQL statement:
select directory_name, directory_path from dba_directories where directory_name like 'APPLLOG%'
The file names would be PLS_<some number>_<FND session id>_<timestamp>.txt, such as PLS_49774696_88740EC94E3AAD2CE040E40A0D8036D8_100607104716.txt.
To process the collected PL/SQL profiles and view results, run the plshprof command under the $ORACLE_HOME/bin directory.
Applications logging: Applications logging is selected by default. Disabling logging will warn users that no logging will take place.
Severity Level:
Use this option to set what types of information to log, and how much of it to log.
For more information, see "Managing Oracle Fusion Applications Log Files and Diagnostics Tests" and "Troubleshooting for Oracle Fusion Applications Using Logs, QuickTrace, and Diagnostic Tests" in the Oracle Fusion Applications Administrator's Guide.
Modules:
This is the module filter for logging. This is a comma-separated list of modules to be logged. The percent sign (%) is used as a wildcard. For example, % or %financial%. The percent sign (%) is the default value and if no other value is specified, then it means everything will be logged.
When a customer logs a service request with Oracle, the support person will help the customer enter the values necessary to filter the diagnostic logs for the needed information.
Run Diagnostics Tests
Selecting this option opens the Diagnostics Dashboard user interface in a new window. For more information, see "Managing Oracle Fusion Applications Log Files and Diagnostics Tests" and "Troubleshooting for Oracle Fusion Applications Using Logs, QuickTrace, and Diagnostic Tests" in the Oracle Fusion Applications Administrator's Guide.
Privacy Statement
Select this option to display the privacy statement, which will appear in a new browser window. This option is always inactive until it is implemented. To set up the privacy statement, enter a fully-qualified URL in the PRIVACY_PAGE profile option. See Section 55.3, "Setting and Accessing Profile Values."
About Applications
Select this option to display the Oracle copyright statement and information about the application.
About This Page
Select this option to display information for the product and product family of the current page. This makes it easier to know to which product the current page belongs and makes it easy to log a Service Request or find a patch for the correct product.
|
 Copyright © 2011, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
