28 Persisting Component Changes

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

This chapter includes the following sections:

• Section 28.1, "Introduction to Using Change Persistence"

• Section 28.2, "Implementing Session Change Persistence"

28.1 Introduction to Using Change Persistence

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 can persist through the length of the user's session. This way the changes will stay in place until the user leaves the application.

Table 28-1 shows the changes by component that provide implicit persistence:

Table 28-1 Implicitly Persisted Attribute Values

Component	Attribute	Effect at Runtime
showDetail showDetailHeader showDetailItem	disclosed	Users can display or hide content using an icon in the header. Detail content will either be displayed or be hidden, based on the last action of the user.
panelSplitter	splitterPosition	The position of the splitter in the panel will remain where it was last moved by the user.
column	displayIndex	Columns in a table 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 be displayed 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	Columns in a table 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. You must create code that allows the user to change this attribute value. For example, you might create a context menu that allows users to toggle the value from true to false.
column	noWrap	The content of the column will either wrap or not. You must 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 must 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.
richTextEditor	editMode	The rich text editor can display in either "what-you-see-is-what-you-get" (WYSIWYG) mode or source mode. The rich text editor will display in the mode last selected by the user.
table	filterVisible	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 must 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.

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

28.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:

1. Double-click the web project in your application to open the Project Properties dialog. In the tree on the left, select the ADF View node.

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

28.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, as shown in Example 28-1.

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

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

28.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, and 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.