19.1 Designing Editable Pages Using Composer Components

The Composer tag library provides design-time components that you can add to a page in Oracle JDeveloper to enable page editing at runtime. When you create a page with Composer components at design time, at runtime Composer provides options for entering page edit mode and modifying the page according to your requirements.

You can enable customizations in Framework applications and non-Framework applications. Within an application, you can enable customization of the following types of pages:

19.1.1 How to Create a Customizable Page

When you create a new page in JDeveloper, it is listed in the Application Navigator under Web Content as shown in Figure 19-1. Additionally, the page is opened in the editor and becomes the active editor panel.

By default, a Framework application is configured with ADF security. A default user name and password (weblogic/weblogic1) are created automatically for you.

To enable users to edit a page in a secured application, you must grant Edit or Customize privileges on the page to the required users or roles. For more information about granting permissions, see Section 68.4, "Using the Role Manager Task Flow."

If ADF security is not enabled in your application, you can test how user privileges impact runtime customization capabilities by implementing security and configuring your application to authenticate users so that they have distinct identities. For the steps to implement a basic security model in your application, see Section 68.3, "Configuring ADF Security."

19.1.2 How to Enable Runtime Customization Using a Page Customizable

Adding a Page Customizable component to the page ensures that Composer is invoked when users switch to Edit mode of the page. When you add a Page Customizable component, some configuration files are updated automatically with the default Composer-specific settings. For more information, see Section 19.1.9, "What Happens When You Add Composer Components."

In the Structure window, within the top facet of the Panel Stretch Layout that you added in the previous section, drag a Change Mode Link or Change Mode Button component.

You must ensure that the Change Mode Link or Change Mode Button is nested in an af:form element. The Change Mode Link or Change Mode Button component is a rich client component that requires the rich client framework to function properly.

Notes:

If you have not used a Panel Stretch Layout on your page, then add the Change Mode Link or Change Mode Button component above the Page Customizable component in the Structure window. This ensures that the Change Mode Link or Change Mode Button is displayed properly at runtime.

Use a Change Mode Link or Change Mode Button only when you have a Page Customizable on the page. You may have problems running a page that contains a Change Mode Link or Change Mode Button but no Page Customizable component.

The required attributes for a Change Mode Link or Change Mode Button component are set by default when you add the component to the page.

In a secured application, it is recommended that you check all users' privileges and enable the Edit link or button on the page only for privileged users. Unauthenticated users who stumble into page Edit mode can change component properties, though the changes will not be saved.

19.1.4 How to Define Editable Areas of a Page Using Panel Customizable Components

The Panel Customizable component is required for page composition or content management tasks, such as adding, arranging, or removing portlets or regions. By default, one Panel Customizable component is automatically added as a direct child of thePage Customizable component. You can add more Panel Customizable components within this Panel Customizable component according to your requirements.

It is only within a Panel Customizable component that you can drag and drop components at runtime.

Drag a Panel Customizable component to the Structure window and drop it at any suitable location within the form.

You must ensure that the Panel Customizable is nested in an af:form element. The Panel Customizable component is a rich client component that requires the rich client framework to function properly.

Notes:

A Page Customizable component contains one direct child Panel Customizable component by default. Do not add another Panel Customizable as a direct child component of the Page Customizable. If the Page Customizable has multiple child components, only the first child component is picked up while running the page.

Ensure that you do not delete the root Panel Customizable component on the page, because at runtime you can drop components only inside a Panel Customizable component.

The required attributes for a Panel Customizable component are set by default when you add the component to the page.

If you select stretch layout for the Panel Customizable, then the first child component is stretched to fill up available space in the PanelCustomizable component. Any other child components are ignored, though they are not removed from the page.

19.1.5 How to Enable Layout Customization for a Page Using a Layout Customizable

Use the Layout Customizable component to enable the runtime definition or modification of the layout of components on a page or an area of a page. Use this component only if you want to allow users to customize the layout at runtime. For static layouts, use an alternative component, such as a Panel Group Layout or Panel Stretch Layout.

To add a Layout Customizable component:

From the Component Palette, select Composer.

Drag a Layout Customizable component to the Structure window and drop it inside the Panel Customizable component.

The target Panel Customizable component must be a child of the Page Customizable component.

Ensure that the Layout Customizable is nested in an af:form element. The Layout Customizable is a rich client component and requires the rich client framework to function properly.

Note:

You can delete the direct child PanelCustomizable in the Page Customizable and add the Layout Customizable as a direct child of the Page Customizable. However, you must ensure that the Page Customizable has only one direct child component.

The required attributes for a Layout Customizable component are set by default when you add the component to the page.

To ensure that the Layout Customizable component is clearly visible on the page at runtime, provide a descriptive label for the component by using the Text attribute.

The pe:layoutCustomizable tag is located inside a cust:panelCustomizable tag in the Structure window as shown in Figure 19-5. A child Panel Customizable component is added by default in the Layout Customizable component. Additionally, a Panel Customizable component is added within each facet of the Layout Customizable component. These Panel Customizable components enable you to add content inside the Layout Customizable component at runtime.

The Panel Customizable added as a direct child provides the main area—the central area in a layout at runtime. The Panel Customizable components added within the two default Layout Customizable facets provide the two content areas, A and B. When you select a predefined layout at runtime, these three areas are arranged to display content in the selected pattern. See Predefined Layout Types for more information about how the content is laid out for each layout type.

Note:

In a oneColumn layout, A and B are rendered only if the Panel Customizable components contain child components.

19.1.6 How to Enable Component Customization Using Show Detail Frame Components

When you want to enable customizations such as property editing, moving, minimizing, or removing components, you can drop a Show Detail Frame component inside a Panel Customizable component on the page. You can then add a component inside the Show Detail Frame.

Note:

Each Show Detail Frame component should have only one direct child component. If you add multiple child components, then only the first one is rendered. The other direct child components are not rendered at design time or runtime.

If multiple components must be enclosed in a Show Detail Frame, then add a grouping component like Panel Group Layout or Panel Customizable to the Show Detail Frame component and then include the ADF Faces components or other content within this grouping component.

Use the Show Detail Frame component to enable customizations in View and Edit modes of the page. Changes made in View mode are available to that user only, and changes made in Edit mode are available to all application users.

To add a Show Detail Frame component to the page:

From the Component Palette, select Composer.

Drag a Show Detail Frame component to the Structure window and drop it inside a Panel Customizable component.

The Show Detail Frame should be nested in a Panel Customizable component on the page.

The required attributes for a Show Detail Frame component are set by default when you add the component to the page.

19.1.7 How to Create a Page Template for Creating Customizable Pages

If you plan to create many customizable pages in your application, you can base the pages on an ADF page template in which you have enabled customization. By adding Composer components to the template itself, you can save the effort required to add these components to each customizable page.

To create a page template and enable customization on it:

In the Application Navigator in JDeveloper, go to the Portal project of the application in which you want to create the template, right click the Portal project, and choose New.

In the New Gallery, expand Web Tier, select JSF and then JSF Page Template, and click OK.

In the Create JSF Page Template dialog, enter a file name for the template, select a layout, and declare a new facet.

You can now create customizable pages based on this template. Once you create a page, you can add a Panel Customizable or Layout Customizable component inside the facet displayed on the new page. You can then add page content within the Panel Customizable or Layout Customizable component.

19.1.8 How to Enable Customization in a Populated Page

When you have an existing ADF application with JSPX pages that are populated with content, and you want to enable customization, you can do so by moving all content inside a Page Customizable component.

You must first add the Page Customizable, then a Layout Customizable, and then the required hierarchy of Panel Customizable and Show Detail Frame components. Drag each of the existing components and drop them onto suitable locations inside the Page Customizable.

Notes:

Ensure that the Page Customizable component has only one direct child component.

When you add multiple direct child components, only the first child component is rendered at runtime. The first child component is stretched to fit the page. All other direct child components are ignored and not rendered on the page.

Use a Layout Customizable component only if you want to allow users to customize the layout at runtime. For static layouts, use an alternative component, such as a Panel Group Layout or Panel Stretch Layout

For best results, move components using the Structure window and not by editing the source code.

19.1.9 What Happens When You Add Composer Components

When you add a Page Customizable component to the page, the following configurations are performed automatically:

A default Resource Catalog definition file, default-catalog.xml, is configured in the application. The default-catalog.xml file is located in the Application_Root/Portal/src/portal directory. To add components to the default Resource Catalog available to end users of your application, see Chapter 15, "Creating and Managing Resource Catalogs."

In a Framework application, the default-catalog.xml file is located in the Application_Root/Portal/public_html/oracle/webcenter/portalapp/catalogs directory out-of-the-box, even without creating a page and adding a Page Customizable component.

A Resource Catalog Viewer is configured for the application. At runtime, Composer provides users the option to add resources from this viewer to the page.

The web.xml file available in the Application_Root/Project_Name/public_html/WEB-INF directory is updated to configure the MDS JSP provider.

When you create an application, a minimal adf-config.xml file is also created. When you add a Page Customizable to an application page, the required configuration is added to the adf-config.xml file. For example, change persistence is configured in the adf-faces-config section in this file. For more information, see Section 21.11, "Configuring the Persistence Change Manager."

The DataBindings.cpx file in the Application_Root/Portal/adfmsrc/portal directory, is updated to enable the presence of task flows on the page.

The page definition file is updated with the binding for the Composer task flow, which is available as part of the WebCenter Portal extension JAR file. Example 19-2 shows the code in the page definition file after a Page Customizable component is added to an application page.

19.1.11 What You May Need to Know When Designing Editable Pages

To enable users to edit a page in a secured application, you must explicitly grant Edit or Customize privileges on the page to the required users or roles. For more information about granting permissions, see Section 68.4, "Using the Role Manager Task Flow."

To enable runtime customization of components, add only one Page Customizable to a page.

Note:

Do not add a second Page Customizable component to your page. Only the first Page Customizable component is picked up when you run the page.

Ensure that the Page Customizable component has only one direct child component.

When you add multiple direct child components, only the first one is rendered at runtime. The first child component is stretched to fit the page. All other direct child components are ignored.

Place all components you want to be customizable within the Page Customizable component.

To enable runtime editing, you must ensure that the ID attribute is defined on all components on the page. Runtime editing of components that have no ID value is not supported in Composer.

If your page includes components with no ID value, then you may encounter problems while editing the page in Composer.

To enable View mode user customization, place a Show Detail Frame component within a Panel Customizable component.

Use a Show Detail Frame to enclose a single child only. If you must enclose multiple components in a Show Detail Frame, then place a grouping component, such as a Panel Group Layout or Panel Customizable, within the Show Detail Frame component and then place the ADF Faces components or other content within this grouping component.

Portlets need not be placed within Show Detail Frame components. Portlets come equipped with a header and display options that are similar to Show Detail Frame components.

19.2 Designing Editable Pages Using Composer Components: Example

In this example, assume you want to create a page that is customizable at runtime. The page is named MyPage.jspx in a Framework application named MyWebCenterApp.

The Panel Stretch Layout component stretches the child in the center facet to fill all the available space in the browser. This is true even if you resize the browser. Therefore, by placing your components within this child component, you can ensure that the customizable portion of your page occupies the complete browser area.

When you run MyPage.jspx, a login screen is displayed. You can log in with any of the three user names that you created.

19.3 Populating Pages with Content

After you create an editable page with the required Composer components, you can populate the page with content just like a regular JSPX page. However, there are certain limitations and recommendations that you must be aware of when adding content to your Composer-enabled page.

Populating editable pages at design time is like populating any other ADF Faces page. You can drag and drop components from different areas of the IDE onto the page. You can add components like portlets, task flows, and ADF Faces components.

When you drag and drop a component anywhere inside a Page Customizable component, the Id attribute is set to a unique value. The Id attribute is required for editing a component and persisting its changed state. When you add a component to a page at runtime, the Id attribute is set automatically.

19.3.1 What You May Need to Know When Adding Content to the Page

Consider the following when adding content to your editable page:

Add components inside Panel Customizable components that are nested in the Page Customizable component. This ensures that the components can be edited at runtime.

You can include any Oracle ADF Faces component or task flow as child component of a Show Detail Frame component. However, portlets contain headers similar to those provided by Show Detail Frame components and can be added to Panel Customizable components directly. There are no additional benefits to including portlets in Show Detail Frame components.

For components that you want to make selectable in Source view in Composer, ensure that the component is compliant with rich client framework and generates a client side component.

If your page has the ADF Faces components Output Text and Output Formatted nested inside a Page Customizable component, then ensure that you set the clientComponent attribute value. If this attribute value is not set, then you may encounter errors while trying to move or rearrange components on the page at runtime.

To consume portlets in your editable page, you must first register the portlet producers with your application. See Chapter 62, "Consuming Portlets" for details.

19.3.1.1 Considerations for Adding Task Flows

Users can personalize, customize, and edit task flows that are added to a customizable page. In a secured application, users with Customize permission on the task flow can also edit components on the task flow's page.

Consider the following points when adding task flows to your customizable page:

In a secured application, to enable users to view task flow content in Composer, ensure that the task flow has a TaskFlowPermission grant in the application's jazn-data.xml file, with at least View action provisioned. You must set this explicitly as it is not enabled by default.

In a secured application, to enable users to edit components on the task flow's page, ensure that the task flow has a TaskFlowPermission grant in the application's jazn-data.xml file, with Customize action provisioned. You must set this explicitly as it is not enabled by default.

Ensure that you specify valid values for all required parameters on the task flow.

For more information, see Section 0.1, "Implementing Task Flow Security."

19.4 Troubleshooting Composer Problems

This section provides information to assist you in troubleshooting problems you may encounter while using Composer.

Configuring ADF Logging for Composer

While creating your applications in JDeveloper, you can use the JDeveloper debugging tools to easily find errors in your web pages or page definition files. You can also set up the Java logger to display Java diagnostic messages. For detailed information about configuring logging, see the chapter titled "Testing and Debugging ADF Components" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. To configure logging for Composer, perform the tasks in that guide and ensure that the oracle.adf.view.page.editor and oracle.adfinternal.view.page.editor packages are configured in the logging.xml file, with the desired logging level.

Problem

When you run a page, the following error displays:

java.lang.IllegalStateException: The expression "#{bindings.pageeditorpanel.regionModel}"
(that was specified for the RegionModel "value" attribute of the region component with id "pePanel")
evaluated to null. This is typically due to an error in the configuration of the
objects referenced by this expression. If it helps, the expression
"#{bindings.pageeditorpanel}" evaluates to "null". If it helps, the expression
"#{bindings}" evaluates to "view_untitled1PageDef". Now using an empty RegionModel instead.

Solution

This error occurs if a page containing the Page Customizable component does not have the required task flow binding in its page definition file. Ensure that the page definition file contains the following valid entry under the <executables> node:

This error may also occur if your page is based on a page template and that page template contains the Page Customizable component. In such a case, the af:pageTemplate tag does not contain the value="#{bindings.pageTemplateBinding}" attribute.

Ensure that the page definition file has the following entry under the <executables> node:

The user may have only view privilege on the page. Ensure that the user has the edit privilege on the page. For the page template on which the page is based, it is sufficient to have only view privilege.

Problem

Users encounter an exception while wiring events in the Component Properties dialog in Composer.

Solution

This error occurs if your application page includes both ADF Data Visualization components and Composer components.

Register the DvtElementObjectFactory class with the Oracle ADF FactoryManager object by adding the following code to the application class that gets loaded the earliest: