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.

This chapter includes the following sections:

Section 31.1, "Introduction to User Customization"
Section 31.2, "Implementing Session Change Persistence"

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.

Table 31-1 shows the changes by component that provide default personalization capabilities:

Table 31-1 Implicitly Persisted Attribute Values

Component	Attribute	Affect at Runtime
`panelBox` `showDetail` `showDetailHeader` `showDetailItem`	`disclosed`	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.

Example 31-1 Context Parameter in web.xml Used for Change Persistence

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
  <param-value>session</param-value>
</context-param>

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.