32 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 32.1, "About User Customization"
Section 32.2, "Implementing Session Change Persistence"

32.1 About 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 32-1 shows the changes by component that provide default personalization capabilities:

Table 32-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 an inline popup dialog is launched using the ADF Faces dialog framework or an ADF taskflow, if the user manually resizes the dialog, any associated `windowHeight` value on the command component that launched the dialog is also changed and will remain This feature only applies to inline dialogs and not browser window dialogs.
`activeCommandToolbarButton` `commandButton` `commandImageLink` `commandLink` `commandMenuItem` `commandNavigationItem` `commandToolbarButton`	`windowWidth`	When an inline popup dialog is launched using the ADF Faces dialog framework or an ADF taskflow, if the user manually resizes the dialog, any associated `windowWidth` value on the command component that launched the dialog is also changed and will remain This feature only applies to inline dialogs and not browser window dialogs.
`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 12.3.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`.
`dvt:areaGraph` `dvt:barGraph` `dvt:bubbleGraph` `dvt:comboGraph` `dvt:horizontal BarGraph` `dvt:lineGraph` `dvt:scatterGraph`	`timeRangeMode`	The time range for the data displayed on a graph time axis can be specified for all data visualization graph components. By default, all data is displayed. The time range can also be set for a relative time range from the last or first data point, or an explicit time range. You will need to write code that allows the user to change this attribute value. For example, you might create a dropdown list to choose the time range for a graph.
`dvt:ganttLegend`	`visible`	The legend for data visualization project, resource utilization, and scheduling Gantt chart components will either be visible or not inside the information panel. You will need to write code that allows the user to change this attribute value, for example, a hide and show button to display the legend.
`dvt:hierarchyViewer`	`layout`	The data visualization hierarchy viewer component supports nine hierarchy layout options including a top-to-bottom vertical, tree, circle, radial, and so on. Users can change the layout in the map control panel and the last selected layout will be retained.
`dvt:map`	`mapZoom`	This data visualization geographic map component attribute specifies the beginning zoom level of the map. The zoom levels are defined in the map cache instance as part of the base map. You will need to write code that allows the user to change this attribute value.
`dvt:map`	`srid`	This data visualization geographic map component attribute specifies the srid (spatial reference id) of all the coordinates of the map, which includes the center of the map, defined by starting X and starting Y, and all the points in the point theme. You will need to write code that allows the user to change this attribute value.
`dvt:map`	`startingX`, `startingY`	This data visualization geographic map component attribute specifies the X and Y coordinate of the center of the map. The srid for the coordinate is specified in the srid attribute. If the srid attribute is not specified, this attribute assumes that its value is the longitude of the center of the map. You will need to write code that allows the user to change this attribute value.
`dvt:projectGantt` `dvt:resource UtilizationGantt` `dvt:schedulingGantt`	`splitterPosition`	The position of the splitter in the panel will remain where last moved by user.
`dvt:timeAxis`	`scale`	Data visualization components for project, resource utilization, and scheduling Gantt charts use this facet to specify the major and minor time axes in the Gantt chart. The time scale (`twoyears`, `year`, `halfyears`, `quarters`, `twomonths`, `months`, `weeks`, `twoweeks`, `days`, `sixhours`, `threehours`, `hours`, `halfhours`, `quarterhours`) can be set by the user using the menu bar View menu and the selection will be retained. Note that a custom time scale can also be named for this component value.
`dvt:timeSelector`	`explicitStart`, `explicitEnd`	Data visualization area, bar, combo, line, scatter, and bubble graph components use this child tag attribute to specify the explicit start and end dates for the time selector. Only value-binding is supported for this attribute. You will need to write code that allows the user to change this attribute value.

32.1.1 User Customization Use Cases and Examples

You can configure an application so that the value of the attributes listed in Table 32-1 can be persisted through the length of the user's session. For example, say your application contains a table, and a user adjusts the width of a column so that the contents all display on one line. If you configure your application to use session change persistence, when the user leaves and then returns to that page, the column will still be expanded to the previously set width.

Note:

For additional functionality, you can configure your application so that changes persist in a permanent data repository, meaning they will persist for that user across multiple sessions. To allow this permanent persistence, you need to use the full Fusion technology stack. For more information, see the "Allowing User Customizations at Runtime" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

32.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.

Note:

MDS requires that pages be XML-based to be customized. Therefore, customizations are not allowed on .jsp files; use .jspx files instead.

Additionally, Facelets files must have a .jsf extension to be customizable. MDS uses this extension to recognize it as a Facelets file.

32.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.

32.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 32-1 shows the context parameter in the web.xml file.

Example 32-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>

32.2.3 What Happens at Runtime: How Changes are Persisted

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.

32.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.