31 Allowing User Customization on JSF Pages

This chapter describes how changes to certain UI components that the user makes at runtime can persist for the duration of the session.

Alternatively, you can configure your application so that changes persist in a permanent data repository. Doing so means that the changes remain whenever the user reenters the application. To allow this permanent persistence, you need to use the Oracle Metadata Service (MDS), which is part of the full Fusion technology stack. Using MDS and the full Fusion stack also provides the following additional persistence functionality:

Persisting additional attribute values

Persisting search criteria

Persisting the results of drag and drop gestures in the UI

Reordering components on a page at runtime

Adding and removing components and facets from the page at runtime

For information and procedures for using Oracle MDS, see the "Allowing User Customizations at Runtime" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

31.1 Introduction to User Customization

Many ADF Faces components allow users to change the display of the component at runtime. For example, a user can change the location of the splitter in the panelSplitter component or change whether or not a panel displays detail contents. By default, these changes live only as long as the page request. If the user leaves the page and then returns, the component displays in the manner it is configured by default. However, you can configure your application so that the changes persist through the length of the user's session. This way the changes will stay in place until the user leaves the application.

Users can display or hide content using an icon in the header. Detail content will either display or be hidden, based on the last action of the user.

showDetailItem (used in a panelAccordion component)

flex

The heights of multiple showDetailItem components are determined by their relative value of the flex attribute. The showDetailItem components with larger flex values will be taller than those with smaller values. Users can change these proportions, and the new values will be persisted.

showDetailItem (used in a panelAccordion component)

inflexibleHeight

Users can change the size of a panel, and that size will remain.

panelSplitter

collapsed

Users can collapse either side of the splitter. The collapsed state will remain as last configured by the user.

panelSplitter

splitterPosition

The position of the splitter in the panel will remain where last moved by user.

richTextEditor

editMode

The editor will display using the mode (either WYSIWYG or source) last selected by the user.

calendar

activeDay

The day considered active in the current display will remain the active day.

calendar

view

The view (day, week, month, or list) that currently displays activities will be retained.

panelWindow

dialog

contentHeight

Users can change the height of a panelWindow or dialog popup component, and that height will remain.

panelWindow

dialog

contentWidth

Users can change the width of a panelWindow or dialog popup component, and that width will remain.

activeCommandToolbarButton

commandButton

commandImageLink

commandLink

commandMenuItem

commandNavigationItem

commandToolbarButton

windowHeight

When users change the contentHeight attribute value of a panelWindow or dialog component, any associated windowHeight value on a command component is also changed and will remain.

activeCommandToolbarButton

commandButton

commandImageLink

commandLink

commandMenuItem

commandNavigationItem

commandToolbarButton

windowWidth

When users change the contentWidth attribute value of a panelWindow or dialog component, any associated windowWidth value on a command component is also changed and will remain.

column

displayIndex

ADF Faces columns can be reordered by the user at runtime. The displayIndex attribute determines the order of the columns. (By default, the value is set to -1 for each column, which means the columns will display in the same order as the data source). When a user moves a column, the value on each column is changed to reflect the new order. These new values will be persisted.

column

frozen

ADF Faces columns can be frozen so that they will not scroll. When a column's frozen attribute is set to true, all columns before that column (based on the displayIndex value) will not scroll. When you use the table with a panelCollection component, you can configure the table so that a button appears that allows the user to freeze a column. For more information, see Section 10.2.4, "How to Display a Table on a Page."

column

noWrap

The content of the column will either wrap or not. You need to create code that allows the user to change this attribute value. For example, you might create a context menu that allows a user to toggle the value from true to false.

column

selected

The selected column is based on the column last selected by the user.

column

visible

The column will either be visible or not, based on the last action of the user. You will need to write code that allows the user to change this attribute value. For example, you might create a context menu that allows a user to toggle the value from true to false.

column

width

The width of the column will remain the same size as the user last set it.

table

filterVisible

ADF Faces tables can contain a component that allows users to filter the table rows by an attribute value. For a table that is configured to use a filter, the filter will either be visible or not, based on the last action of the user. You will need to write code that allows the user to change this attribute value. For example, you might create a button that allows a user to toggle the value from true to false.

table

first

This attribute represents the index of the first row in the current range of rows, and is used to control which range of rows to display to the user.The value of this attribute is persisted only in response to a RangeChangeEvent and only when in screen reader mode.

31.2 Implementing Session Change Persistence

In order for the application to persist user changes to the session, you must configure your project to enable customizations.

31.2.1 How to Implement Session Change Persistence

You configure your application to enable customizations in the web.xml file.

To implement session change persistence:

In the Application Navigator, double-click the web project.

In the Project Properties dialog, select the ADF View node.

On the ADF View page, activate the Enable User Customizations checkbox, select the For Duration of Session radio button, and click OK.

31.2.2 What Happens When You Configure Your Application to Use Change Persistence

When you elect to save changes to the session, JDeveloper adds the CHANGE_PERSISTENCE context parameter to the web.xml file, and sets the value to session. This context parameter registers the ChangeManager class that will be used to handle persistence. Example 31-1 shows the context parameter in the web.xml file.

31.2.3 What Happens at Runtime

When an application is configured to persist changes to the session, any changes are recorded in a session variable in a data structure that is indexed according to the view ID. Every time the page is requested, in the subsequent view or restore view phase, the tag action classes look up all changes for a given component and apply the changes in the same order as they were added. This means that the changes registered through the session will be applied only during subsequent requests in the same session.

31.2.4 What You May Need to Know About Using Change Persistence on Templates and Regions

When you use session persistence, changes are recorded and restored on components against the viewId for the given session. As a result, when the change is applied on a component that belongs to a fragment or page template, it is applicable only in scope of the page that uses the fragment or template. It does not span all pages that consume the fragment or template.For example, say your project has the pageOne.jspx and pageTwo.jspx JSF pages, and they both contain the fragment defined in the region.jsff page fragment, which in turn contains a showDetail component. When the pageOne.jspx JSF page is rendered and the disclosed attribute on the showDetail component changes, the implicit attribute change is recorded and will be applied only for the pageOne.jspx page. If the user navigates to the pageTwo.jspx page, no attribute change is applied.

Scripting on this page enhances content navigation, but does not change the content in any way.