5 Introduction to Oracle Composer

This chapter provides an overview of Oracle Composer and describes the various tasks users can perform on the application page at runtime.

Typically, the tasks for creating, deploying, and using web applications are performed by different categories of users in different environments:

Consider a dashboard-like application that displays information pertaining to the logged-in user, such as a worklist, open tasks, mail, and so on. The page developer creates the dashboard page and populates it with the required components and task flows. When this application is installed at a customer site, people at different levels in the organization may want the page modified to suit their requirement. For example:

In addition, content contributors, moderators, and end users may want to add, delete, or modify components, task flows and other page artifacts based on the needs of the application or the needs of the business. In a typical application development environment, these requests are passed on to the page developer. The developer modifies the application in the development environment and redeploys it to the customer site.

Rather than pushing these simple modifications back onto the developer, Oracle Composer, in conjunction with Metadata Services (MDS), provides a runtime editing tool that enables business users to edit application pages. Changes made to the page at runtime are saved as metadata, separate from the base application definitions. This eliminates the need to revise the application and redeploy it to the production environment.

The concept of design time at runtime describes an environment that provides users with the option to edit application pages at runtime. Oracle Composer provides components for controlling the application's design time at runtime behavior. This chapter describes the editing capabilities provided by Oracle Composer and the components that enable these capabilities. It contains the following subsections:

5.1 Personalization and Customization

Changes made to a page at runtime are typically available only to the respective users, not everyone viewing the page. However, you can configure your application to make runtime modifications available to all or a subset of users accessing the page. Consider an example of a dashboard page containing a task flow to display details about the expenses incurred by the members of an LOB. When this task flow is modified, the LOB administrator would want all members to see the changes. To address such a requirement, Oracle Composer enables you to edit pages in different modes so that changes are saved as personalizations (affect only the individual user's view of the page) or customizations (affect everyone's view of the page).

To save a user's changes as personalizations or customizations requires that they be saved separately at the back end. In the metadata domain, MDS allows for the saving of customizations in separate layers on top of the base application definitions. Depending on the business requirement, you can save changes in a single layer or in multiple layers.

In a single-layer configuration, changes are saved as customizations to a common layer that is accessible to all users. In this case, you cannot allow for changes to be saved as personalizations.

In a multiple-layer configuration, changes are saved at separate locations based on specified criteria such as the mode in which the page is edited, the user editing the page, or the user role. In this type of configuration, each customization layer is insulated from the other, but the layers can be stacked over each other to provide flexibility during upgrades. For example, a user may want to change the default theme of the page being viewed. It is expected that this change be saved only for this user, without affecting others' view of the page. Therefore, you can set up things so that changes made by end users who have Personalize privilege on the page are saved as personalizations, and changes made by logged-in users with customization-level privileges are saved as customizations. You can decide which tasks are available to users with Personalize and Customize/Edit privileges respectively.

For more information about MDS and customization layers, see Section 10.1, "Introduction to MDS."

5.2 View and Edit Modes of a Page

When a user opens an application page in a browser, the page opens in View mode. Additionally, Oracle Composer provides access to another mode called Edit mode to enable users with appropriate privileges to edit application pages. These modes can be described as follows:

  • View mode—The default view of a page when opened in a browser. In this mode, users can perform tasks such as rearranging components, collapsing and expanding components, and changing the layout. Typically, changes made to a page in View mode are available for the user alone and are saved as personalizations.

  • Edit mode—The mode typically available to authenticated users with access privileges to edit page content. In addition to the tasks that can be performed in View mode, Oracle Composer provides controls for switching to Edit mode and performing tasks such as adding components, deleting components, and editing component properties. Typically, changes made to the page in Edit mode are saved as customizations and are available for all users accessing the page.

Note:

To ensure clarity and consistency while discussing runtime editing, this document uses the terms personalize and edit while referring to the tasks performed in View mode and Edit mode respectively.

5.3 Personalizing Capabilities in Page View Mode

Oracle Composer enables users to personalize pages in View mode and edit pages in Edit mode. This section provides an overview of personalization tasks you can enable for users in page View mode. Such tasks include rearranging components, collapsing and expanding components, and changing the page layout. You can enable the capabilities described in this section by adding the following Oracle Composer design-time components to a page: Panel Customizable, Show Detail Frame, Custom Actions, and Layout Customizable. For information about these components, see Section 5.6, "Oracle Composer Components." Changes made to a page in View mode are available only to the user making these changes.

This section includes the following subsections:

Note:

For a detailed description of the editing tasks that you can perform on a page, see "Personalizing Your Page View" and "Working with Page Content" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter.

5.3.1 Rearrange Components

This capability allows users to organize page components so that the content most useful to them displays at the top of the page. Users can rearrange components in two ways:

  • Dragging and dropping

    Users can rearrange components by dragging and dropping them within the Panel Customizable component or across Panel Customizable components on the page. As it is difficult to identify a Panel Customizable component in View mode, users can simply drag the component over the spot they want to place it. A solid box indicates a receptive drop location.

  • Using the Actions menu

    The Move actions on a Show Detail Frame or portlet component enable users to move these components within a parent Panel Customizable component. If a Panel Customizable has multiple child components, then a child Show Detail Frame or portlet can be moved to the left and right or above and below, relative to the position of other child components. Figure 5-1 shows a sample Show Detail Frame component with Move Up and Move Down actions. In this example, selecting Move Down moves the Latest News component immediately below the Press Release component.

    Figure 5-1 Actions Menu on a Show Detail Frame

    Description of Figure 5-1 follows
    Description of "Figure 5-1 Actions Menu on a Show Detail Frame"

5.3.2 Change the Layout

This capability allows users to switch between a set of predefined layouts provided by Oracle Composer. Through the use of the Change Layout icon, users can choose among eight different layouts to suit their needs and preferences. The Layout Customizable component in the Oracle Composer library enables the display of a Change Layout icon on the page, as shown in Figure 5-2.

Figure 5-2 Change Layout Icon

Description of Figure 5-2 follows
Description of "Figure 5-2 Change Layout Icon "

Figure 5-3 shows the layout options available with the Layout Customizable component. A gray colored border highlights the layout currently applied to the page or area.

Figure 5-3 Layout Options

Description of Figure 5-3 follows
Description of "Figure 5-3 Layout Options"

5.3.3 Expand and Collapse Components

By enabling expand and collapse components on a page, you can include more detailed information on a page without cluttering its visual appearance. Users can collapse and expand the components as desired.

A Collapse icon on the header of a Show Detail Frame or portlet enables users to collapse such a component and display only its header. Figure 5-4 shows the Collapse icons on three Show Detail Frame components.

Figure 5-4 Collapse Icon on a Show Detail Frame

Description of Figure 5-4 follows
Description of "Figure 5-4 Collapse Icon on a Show Detail Frame"

The Expand icon on a collapsed component enables users to disclose the component so that it displays the header and content. Figure 5-5 shows the Expand icons on two collapsed Show Detail Frame components.

Figure 5-5 Expand Icon on a Show Detail Frame

Description of Figure 5-5 follows
Description of "Figure 5-5 Expand Icon on a Show Detail Frame"

5.3.4 Customize Portlets

If the application contains portlets, then users can make them display the information that they want to see, hide them, or remove them from the page. Figure 5-6 shows the actions users can perform on a Web Clipping portlet. The Customize and Personalize options are available on portlets by default.

Figure 5-6 Actions on a Web Clipping Portlet

Description of Figure 5-6 follows
Description of "Figure 5-6 Actions on a Web Clipping Portlet"

5.4 Editing Capabilities in Design View in Page Edit Mode

Oracle Composer's Edit mode provides a wide range of page customization capabilities. In Edit mode users can add content, edit page and component properties, delete components, rearrange components, change the page layout, and so on.

You can provide the capabilities described in this section to your application by adding the following Oracle Composer design-time components to a page: Change Mode Link or Change Mode Button, Page Customizable, Panel Customizable, Show Detail Frame, Custom Actions, and Layout Customizable. For more information about these components, see Section 5.6, "Oracle Composer Components."

The Change Mode Link or Change Mode Button switches the page to Edit mode. In Edit mode, users can add content to the page, edit component properties, edit page properties, and so on. The Page Customizable component on a page enables these editing capabilities.

Figure 5-7 shows a Change Mode Link on an application page. When users click the Change Mode Link or Change Mode Button, the page opens in Oracle Composer.

Figure 5-7 Edit Link While in View Mode

Description of Figure 5-7 follows
Description of "Figure 5-7 Edit Link While in View Mode"

The default Oracle Composer toolbar displays the name of the page being edited, a status indicator, View menu, Page Properties button, Reset Page button, and a Close icon. The View menu (Figure 5-8) provides two viewing options—Design and Source. Users can perform various editing tasks in these views.

Figure 5-8 View Menu in Oracle Composer

Description of Figure 5-8 follows
Description of "Figure 5-8 View Menu in Oracle Composer"

Design view (shown in Figure 5-9) is the default page view that provides a WYSIWYG rendering of the page and its content, where Edit and Delete controls are directly selectable on each component. In Design view users can also perform such tasks as adding content, editing page and component properties, changing page layout, and deleting components.

Figure 5-9 Design View of a Page

Description of Figure 5-9 follows
Description of "Figure 5-9 Design View of a Page"

For information about the Source view, see Section 5.5, "Editing Capabilities in Source View in Page Edit Mode."

This section describes the editing capabilities that Oracle Composer provides in the Design view in page Edit mode. It contains the following topics:

Note:

You can restrict users from performing all or some of these tasks by securing the application and applying customization restrictions on components. For more information, see Section 5.7, "Security and Oracle Composer."

Oracle Composer provides most of these capabilities in the Source view as well. The individual sections mention whether a capability is available in both modes or only in Design mode.

For a detailed description of the runtime editing tasks that users can perform on a page, see "Personalizing Your Page View" and "Working with Page Content" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter.

5.4.1 Add Content

Users may want to add custom content to the page, such as a portlet displaying news, for example, or stock updates. Oracle Composer enables users to add content within any container in page Design view and Source view. The Oracle Composer Catalog, also known as Oracle Business Dictionary, contains resources that users can add to a page. These include documents, Oracle ADF components, portlets, and task flows. The Catalog can be invoked in the following ways:

  • In Design view, by clicking the Add Content button on any container component on the page.

  • In Source view, by selecting a container component and clicking the Add Content button on the Source view toolbar.

Notes:

Figure 5-10 shows the default Catalog available in a custom WebCenter application.

Figure 5-10 Oracle Composer Catalog

Description of Figure 5-10 follows
Description of "Figure 5-10 Oracle Composer Catalog"

The Catalog contains folders and components. An Open link next to an item in the Catalog indicates that the item is a folder. Users can drill down into the folder by clicking this link. An Add link next to an item indicates that the item can be added to the page. An Add link can appear next to a component or a folder. The component is added as the first child in the container on which the Add Content link was clicked.

Note:

The Top icon in the Catalog dialog enables users to return to a top-level folder.

If you configure drop handlers for adding resources to the page, the Add link shows a context menu with different options for adding the component to the page (Figure 5-11). For more information, see Section 8.6, "Configuring Drop Handlers in the Oracle Composer Catalog."

Figure 5-11 Context Menu with Drop Handlers for Adding a Component

Description of Figure 5-11 follows
Description of "Figure 5-11 Context Menu with Drop Handlers for Adding a Component"

Depending on its configuration, the Catalog exposes all or a subset of the following components to users:

Note:

For information about Resource Catalog configurations, see Chapter 12, "Configuring the Resource Catalog for Oracle Composer."
  • ADF Faces Components

    The ADF Faces Components folder provides Box, Movable Box, and Image components that are analogous to the JDeveloper design time components Panel Customizable, Show Detail Frame, and Image Link respectively. In JDeveloper, these components are available in the Oracle Composer tag library.

    Note:

    Panel Customizable and Show Detail Frame components added to the page at design time continue to be called the same. These components are not denoted as Box and Movable Box components respectively at runtime.

    This folder also provides HTML Markup, Hyperlink, Text, and Web Page components that are analogous to the JDeveloper design time components Output Text, Go Link, Rich Text Editor, and Inline Frame respectively. In JDeveloper, these components are available in the ADF Faces tag library.

    The ADF Faces Components folder in the Catalog dialog contains these components, as shown in Figure 5-12.

    Figure 5-12 ADF Faces Components You Can Add to the Page

    Description of Figure 5-12 follows
    Description of "Figure 5-12 ADF Faces Components You Can Add to the Page"

  • Task Flows

    Users can add custom task flows and out-of-the-box Oracle WebCenter Services task flows to the page only if you have configured them in the catalog definition file. See Section 12.2.1.3, "Enabling Task Flows in the Resource Catalog" for details.

    A task flow added to a page is automatically enclosed in a Movable Box component. As a result, the task flow displays a header with options to move or delete the component.

    Note:

    The Movable Box component surrounding a task flow is displayed only if the task flow is displayed on the page. That is, if you do not grant even View permission on a task flow, the Movable Box surrounding it is also not displayed on the page.
  • Portlets

    The Portlets folder lists all the registered producers. Users can navigate to the required portlet and add it to the page. The Portlets folder exposes portlets from any Java-PDK or WSRP producer that was registered in Oracle JDeveloper. For information about registering portlet producers, see Chapter 34, "Consuming Portlets."

  • Documents

    The Documents folder lists documents and folders from the Documents service that users can add to the page.

    To display documents, ensure that you have performed the steps in Section 12.2.1.4, "Enabling Documents in the Resource Catalog."

See "Adding Content to a Page" in Oracle Fusion Middleware User's Guide for Oracle WebCenter for detailed information.

5.4.2 Add Box Components Adjacent to Existing Ones

A toolbar on the Box component in Design view provides options to add another Box component before or after the component. This capability enables users to modify the layout of components on the page.

When a user clicks an Add icon on the Box component, Oracle Composer adds another Box component before or after it and surrounds both Box components with a Panel Group Layout. Depending on the icon used, the new Box component is added to the left, right, above, or below the original Box component, and the layout attribute on the parent Panel Group Layout component is set to horizontal or vertical. Users can add many contiguous Box components in this way. Every time the orientation changes for new a Box component, a new Panel Group Layout with the appropriate layout setting (horizontal or vertical) is added around the new and the existing Box components.

Note:

The Add icons are not rendered on the component if:
  • The allowAction attribute on the Panel Customizable component is set to false

  • The Panel Customizable is stretched

  • The Panel Customizable component is restricted

For more information, see Chapter 11, "Modifying Default Security Behavior of Oracle Composer Components."

Users can delete Box components that they added using the Add icons, in both Design and Source view.

Note:

If the Panel Group Layout has only two Box components and you delete a Box component, then the Panel Group Layout is also deleted.

The Box component toolbar contains the following Add Box icons in addition to the Edit icon:

  • Add Box Above

  • Add Box Below

  • Add Box Left

  • Add Box Right

5.4.2.1 Add Box Above

Clicking the Add Box Above icon (Figure 5-13) adds a Box component above the selected Box component. The layout attribute on the Panel Group Layout is set to vertical.

Figure 5-13 Add Box Above Icon on a Box Component

Description of Figure 5-13 follows
Description of "Figure 5-13 Add Box Above Icon on a Box Component"

Figure 5-14 shows how the Box component appears in Source view before adding another Box component adjacent to it.

Figure 5-14 Box Component Before Adding Another One Adjacent to It

Description of Figure 5-14 follows
Description of "Figure 5-14 Box Component Before Adding Another One Adjacent to It"

Figure 5-15 shows the two Box components vertically aligned in the component navigator.

Figure 5-15 Box Component Added Above

Description of Figure 5-15 follows
Description of "Figure 5-15 Box Component Added Above"

Users can click the Add Box Above icon repeatedly to add many contiguous Box components vertically within the same parent Panel Group Layout.

5.4.2.2 Add Box Below

Clicking the Add Box Below icon (Figure 5-16) adds a Box component below the selected Box component. The layout attribute on the Panel Group Layout is set to vertical.

Figure 5-16 Add Box Below Icon on a Box Component

Description of Figure 5-16 follows
Description of "Figure 5-16 Add Box Below Icon on a Box Component"

Figure 5-17 shows the two Box components vertically aligned in the component navigator.

Figure 5-17 Box Component Added Below

Description of Figure 5-17 follows
Description of "Figure 5-17 Box Component Added Below"

Users can click the Add Box Below icon repeatedly to add many contiguous Box components vertically within the same parent Panel Group Layout.

5.4.2.3 Add Box Left

Clicking the Add Box Left icon (Figure 5-18) adds another Box component to the left of the selected Box component. The layout attribute on the Panel Group Layout is set to horizontal.

Figure 5-18 Add Box Left Icon on a Box Component

Description of Figure 5-18 follows
Description of "Figure 5-18 Add Box Left Icon on a Box Component"

Figure 5-19 shows the two Box components horizontally aligned in the component navigator.

Figure 5-19 Box Component Added to the Left

Description of Figure 5-19 follows
Description of "Figure 5-19 Box Component Added to the Left"

Users can click the Add Box Left icon repeatedly to add many contiguous Box components horizontally within the same parent Panel Group Layout.

5.4.2.4 Add Box Right

Clicking the Add Box Right icon (Figure 5-20) adds another Box component to the right of the selected Box component. The layout attribute on the Panel Group Layout is set to horizontal.

Figure 5-20 Add Box Right Icon on a Box Component

Description of Figure 5-20 follows
Description of "Figure 5-20 Add Box Right Icon on a Box Component"

Figure 5-21 shows the two Box components horizontally aligned in the component navigator.

Figure 5-21 Box Component Added to the Right

Description of Figure 5-21 follows
Description of "Figure 5-21 Box Component Added to the Right"

Users can click the Add Box Right icon repeatedly to add many contiguous Box components horizontally within the same parent Panel Group Layout.

5.4.3 Rearrange Page Content

This capability allows users to organize page components based on where they are easiest to use; for example, users can move content most useful to them to the top of the page. In Design view, users can rearrange content on the page in the following ways:

  • Drag and drop a component within the same Panel Customizable component or across Panel Customizable (or Box) components on the page.

  • Use the Move actions on the Actions menu of a Show Detail Frame or portlet to move it within the parent Panel Customizable component. Depending on the number of child components in the Panel Customizable and how these components are oriented, a component can be moved to the left and right, or up and down.

  • To resequence components within a container, in the Component Properties dialog for the container, click the Child Components tab and use the up and down arrows shown against each child component (Figure 5-22).

    Notes:

    A component on which customization is restricted, can be rearranged inside its parent container if the parent is customizable.

    The Child Components tab displays a list of direct child components at the top (Components list) of the tab, followed by a list of all facets defined for the component (Fixed Components list). There are no up and down arrows against facet components as these components cannot be rearranged. The Fixed Components list is displayed only if the component contains facets.

    Figure 5-22 Resequencing Options on the Child Components Tab of a Container

    Description of Figure 5-22 follows
    Description of "Figure 5-22 Resequencing Options on the Child Components Tab of a Container"

5.4.4 Edit Component Properties and Parameters

The Component Properties dialog enables users to edit component properties and the parameters associated with components, such as portlets and task flows. The Component Properties dialog is accessible in both Design view and Source view.

Note:

A component cannot be edited if:

In Design view, clicking the Edit icon on a component displays the Component Properties dialog, shown in Figure 5-23.

Figure 5-23 Component Properties Dialog

Description of Figure 5-23 follows
Description of "Figure 5-23 Component Properties Dialog"

The Display Options tab enables users to edit visual properties, such as background and title.

The Parameters tab (Figure 5-24) enables users to edit parameters for components such as portlets and task flows.

Note:

While editing task flows, users must define values for all required parameters.

Figure 5-24 Parameters tab in the Component Properties Dialog

Description of Figure 5-24 follows
Description of "Figure 5-24 Parameters tab in the Component Properties Dialog"

Visual Indication of Component Property Customization

An icon next to a property on the Display Options tab indicates that the property has been edited at runtime. Two different icons are used to indicate changes made in the current context and in a different layer. Figure 5-25 shows the two different icons used to indicate that the property was updated.

Note:

Visual indication of property customization is relevant only if you have configured multiple customization layers in your application. For information, see Section 10.3, "Adding Customization Layers to View and Edit Modes: Example."

Figure 5-25 Visual Indication of Property Customization

Description of Figure 5-25 follows
Description of "Figure 5-25 Visual Indication of Property Customization"

The Component Properties dialog also enables users to reset visual properties in the current context. For more information, see Section 5.4.5, "Reset and Override Component Properties in the Current Layer."

5.4.5 Reset and Override Component Properties in the Current Layer

Users can reset and override customizations made to a component's properties in the current layer. The Component Properties dialog provides options to reset a particular property or all properties on that panel in the Component Properties dialog.

Note:

The reset and override capabilities in the Component Properties dialog are relevant only if you have configured multiple customization layers in your application. For information, see Section 10.3, "Adding Customization Layers to View and Edit Modes: Example."

An Override option on the context menu for a property (Figure 5-26) enables users to use a value from another layer as a fixed value for the current layer. For example, a user edits the Short Desc property on a Movable Box component in layer X and sets it to First Frame. A user editing this component in another layer, Y, can choose First Frame as the fixed value for Short Desc in layer Y. All users that are accessing the component in layer Y will see this value henceforth. The value for Short Desc does not change in layer Y even if it is changed in layer X. When a user enters a value for a property, the Override option for that property is grayed out.

Figure 5-26 Reset and Override Options in the Component Properties Dialog

Description of Figure 5-26 follows
Description of "Figure 5-26 Reset and Override Options in the Component Properties Dialog"

A Reset option on the context menu for a property enables users to reset that property to its original state. The Reset option is grayed out when the property has not yet been edited in that layer, or when the user has chosen to override the property with the displayed value, which comes from another layer.

A Reset All button enables users to reset all properties on the Display Options tab. Users can reset only customizations applied to visual properties, which are rendered on the Display Options tab.

5.4.6 Edit Resource Strings

Component properties edited in Oracle Composer are available only in the current language. For example, if you add a task flow to your page, the task flow title you enter in Oracle Composer is available only in the current language. As a result, users in different locales do not see the translated values for such properties. To provide language support for component properties edited at runtime, Oracle Composer enables users to edit resource strings for properties that take String values. This is similar to the resource string editor feature provided by JDeveloper. Changes made to resource strings in Oracle Composer are saved into an application override bundle. This bundle is sent for translation and the translated versions are imported back into the application. This way, users are able to see the property values in their language.

For more information about the override bundle and configuring resource string editing in existing (release 11.1.1) WebCenter applications, see Section 9.11, "Configuring Runtime Resource String Editing."

At runtime, for component display options that can take String values, the Edit menu next to the property field provides a Select Text Resource option, as shown in Figure 5-27. Users can select this option to edit resource strings for properties.

Figure 5-27 Select Text Resource Option on an Attribute

Description of Figure 5-27 follows
Description of "Figure 5-27 Select Text Resource Option on an Attribute"

The Select Text Resource dialog (Figure 5-28) provides options to search existing resources, edit or delete resource keys, and add new resource key/value pairs.

Figure 5-28 Select Text Resource Dialog

Description of Figure 5-28 follows
Description of "Figure 5-28 Select Text Resource Dialog"

The Select Text Resource dialog displays the following:

  • Key field: For specifying a new key name or modifying the existing name. This is a String value used for uniquely identifying a locale-specific object in the resource bundle.

    The key name is automatically prefixed with the MDS layer to which the resource belongs. The prefix helps distinguish keys created at runtime from those created at design time.

    The Edit and New Key/Value icons (Figure 5-29), displayed for existing keys, enable users to perform the following tasks:

    • Edit: Modify the key value for an existing resource string. The string with new values is saved into the override bundle.

    • New Value/Key: Create key and value pairs in the application override bundle.

    Figure 5-29 Icons for Creating and Editing Resource String Keys

    Description of Figure 5-29 follows
    Description of "Figure 5-29 Icons for Creating and Editing Resource String Keys"

    Users can edit only strings that were created in the same MDS layer. Other strings appear as read-only, as shown in Figure 5-30.

    Figure 5-30 Read-Only Resource Strings in the Select Text Resource Dialog

    Description of Figure 5-30 follows
    Description of "Figure 5-30 Read-Only Resource Strings in the Select Text Resource Dialog"

  • Display Value field: For specifying a resource string to translate for display in the UI or modifying an existing string.

  • Description field: For specifying a translatable description of the resource or modifying an existing description.

  • Search field: For searching existing resources. Users can search for strings that were created in the same layer, in a different MDS layer, or resource bundles defined and used in a JSPX file at design time.

  • Search results table: For displaying search results, editing strings, and specifying values for new strings.

    Users can edit strings that were created in the same layer. Other strings created at design time or in a different MDS layer can only be used for the property, but not edited.

    A link or a status indicator toggle displays in the last column and enables users to promote a string to be the active, to-be-translated resource (Figure 5-31) or identifies a string as the active resource (Figure 5-32).

    Figure 5-31 Use Link on a Resource String

    Description of Figure 5-31 follows
    Description of "Figure 5-31 Use Link on a Resource String"

    Figure 5-32 Active Status on a Resource String

    Description of Figure 5-32 follows
    Description of "Figure 5-32 Active Status on a Resource String"

    Note:

    When searching for resource strings created at design time, Oracle Composer searches for the c:set tag that is used when specifying resource strings in JSPX files.

    The following example shows the c:set element used for defining the ComposerBundle in a JSPX page:

    <c:set var="viewcontrollerBundle"
             value="#{compBundle['test.resource.ComposerBundle']}"/>
    
  • Create button: For creating a new resource string. On clicking the Create button, the search results table provides a new row with input fields for creating a new resource. Users can double click inside the row and create a new string by specifying values for the Key, Display Value, and Description, as shown in Figure 5-33, and then click OK.

    Figure 5-33 Fields for Creating a New Resource String in the Search Results Table

    Description of Figure 5-33 follows
    Description of "Figure 5-33 Fields for Creating a New Resource String in the Search Results Table"

    Users can just create inactive strings that get saved to the override bundle. Clicking the Use button in the last column selects this string for use as the current property value.

  • Delete button: For deleting a selected resource from the search results table.

  • Refresh: For refreshing the search results table.

Notes

  • Oracle Composer supports creation of around 500 resource strings at runtime. Beyond this number, application performance slows down.

  • The search criteria in the resource string editor is case-sensitive.

  • To search for the description of a resource string, the user must provide the complete string value in the search criteria.

  • The resource string editor does not display string descriptions for entries created in Properties bundle or List Resource bundle formats in JDeveloper.

  • The option to edit resource strings is disabled for properties on the Parameters and Events tabs.

    If the EL value for an ADF resource is referenced in a page definition parameter such as page parameter, task flow parameter, or portlet parameter, then the binding EL returns an empty value. Users must avoid referencing ADF resource EL values in page definition parameters.

5.4.7 Show or Hide Components

Users can choose to show and hide components selectively on the page using various options. Users can hide or show a component in the following ways:

Note:

Show or hide behavior is tied to the component's rendered property. When a user hides a component, its rendered property is set to false and vice versa. If the rendered attribute on a component has an EL value, then that value is lost on using the show or hide option. The value is set to true or false.
  • Click the Edit icon on the component. In the Component Properties dialog, clear the Show Component check box (Figure 5-34).

    Figure 5-34 Show Component Option in the Component Properties Dialog

    Description of Figure 5-34 follows
    Description of "Figure 5-34 Show Component Option in the Component Properties Dialog"

    Checking the Show Component check box and clicking Apply or OK in the dialog renders the component on the page again.

  • Click the Edit icon on the component's container. On the Child Components tab in the Component Properties dialog, click the Hide Component link shown against the component name.

    Figure 5-35 Hide Component Link in a Container's Component Properties Dialog

    Description of Figure 5-35 follows
    Description of "Figure 5-35 Hide Component Link in a Container's Component Properties Dialog"

    When a component is hidden, the Component Properties dialog for its container displays a Show Component link against that component. Clicking this link and then clicking Apply or OK in the dialog displays the component again.

5.4.8 Delete Components

Users can delete a component from the page by clicking the Delete icon on its header.

A Delete dialog prompts users to confirm deletion.

Note:

If you defined customization restrictions on a component, then the Delete icon is disabled for the component at runtime. For more information, see Section 11.1.1, "How to Define Type-Level Customization Policies."

5.4.9 Change the Layout

In Design view, the Change Layout icon enables users to select a layout from a set of eight predefined layouts. The default page layout is threeColumn.

In Source view, users can select the Layout Customizable component and view its properties. The layout options are displayed in the Component Properties dialog. Users can select any predefined layout and click Apply or OK.

Note:

Predefined layout options are available to users only if you have added a Layout Customizable component to the page at design time. For more information, see Section 5.6.5, "Layout Customizable."

5.4.10 Edit Page Properties

Users can access the Page Properties dialog from both Design view and Source view. In this dialog, users can create or edit a page's parameters and display properties. For pages created at runtime in a secured application, a Security tab enables users with Grant privilege to edit page access privileges for other users.

Figure 5-36 shows the Security tab in the Page Properties dialog.

Figure 5-36 Security Tab on the Page Properties Dialog

Description of Figure 5-36 follows
Description of "Figure 5-36 Security Tab on the Page Properties Dialog"

On the Parameters tab (Figure 5-37), users can create page parameters that can be linked to component properties, thereby enabling any component on the page to adapt to the page context. For example, suppose that a page has a parameter called SYMBOL with the default value ORCL. This page contains the Stock Chart, Stock Price, and Company Info task flows. The task flows can be linked with the page parameter so that all the task flows respond to a change in the value of SYMBOL and are updated accordingly.

Figure 5-37 Parameters Tab on the Page Properties Dialog

Description of Figure 5-37 follows
Description of "Figure 5-37 Parameters Tab on the Page Properties Dialog"

See "Renaming Pages and Revising Page Keywords and Descriptions" and "Wiring Components and Pages" in Oracle Fusion Middleware User's Guide for Oracle WebCenter for detailed information about editing page settings.

5.4.11 Wire Components to Page Parameters

Oracle Composer enables users to link portlets and task flows with page parameters so that these components can read the page parameters and change their behavior accordingly.

Users can wire portlet and task flow parameters to page parameters using the Component Properties dialog. For more information, see "Wiring Pages, Task Flows, Portlets, and UI Components Together" in Oracle Fusion Middleware User's Guide for Oracle WebCenter.

In addition to wiring components and page parameters, Oracle Composer also enables users to pass values for display options and parameters through page URLs. For more information, see "Passing Parameter Values Through the Page URL" in Oracle Fusion Middleware User's Guide for Oracle WebCenter.

5.4.12 Reset Page

The Reset Page button is available on the page in both Design view and Source view. This button invokes the Reset Page dialog that provides options to remove edits made to a page and reset it to a previously saved version or its original, out-of-the-box state.

Note:

The Reset Page button is a default add-on rendered on the Oracle Composer toolbar. You can disable this button if you do not want users to reset the page. For information, see Section 8.2.5, "How to Selectively Display Add-Ons."

Roll Back to a Specific Label

If your application is configured to use a database store, a new version of the page is generated each time a user saves customizations. If a sandbox is configured for your application, by creating a label with the SAVE_LABEL_% convention you can ensure that Oracle Composer resets the page as follows:

  • If there is only one label name following the SAVE_LABEL_% convention, then Oracle Composer resets the page to its state in that label.

  • If there is no label name following the SAVE_LABEL_% convention, then Oracle Composer resets the page to its original, out-of-the-box state.

  • If there are multiple labels following the SAVE_LABEL_% convention, then Oracle Composer resets the page to its state in the latest label among these.

To roll back to a specific label, you must have configured your application to use a sandbox. Specifically, the namespace of the page being customized must be defined in the <metadata-namespaces> section in the application's adf-config.xml file. For more information, see Section 10.2.1, "How to Enable Oracle Composer Sandbox Creation."

Rolling back to a specific label is useful if your application has dependencies on the customization metadata and resetting the page to its original state can cause issues.

Notes:

  • Users can only reset customizations done on a page. Components defined in the base page or a shared component's page are left intact.

  • When a user resets a page, components added to the page at runtime are removed. However, if the page uses a template, then components added inside Panel Customizable components on the template are not removed.

Example 5-1 shows the sample code to create a label with a SAVE_LABEL_ prefix.

Example 5-1 Code to Create a Label Prefixed with SAVE_LABEL_

import oracle.mds.versioning.VersionHelper;
import oracle.mds.naming.Namespace;
 
....
long labelNumber = (long)(Math.random() * 1000000000);
String savedlabel = "SAVE_LABEL_" + labelNumber;

MDSInstance mdsInstance = (MDSInstance)ADFContext.getCurrent().getMDSInstanceAsObject();

VersionHelper vh = VersionHelper.get(mdsInstance);

Namespace[] validNamespaces = new Namespace[1];
Namespace pageNamespace = Namespace.create(<pagePath or taskflow path>, NamespaceRestriction.CUSTOMIZATIONS);

validNamespaces[0] = pageNamespace;
vh.createLabel(savedlabel, null, validNamespaces);

5.4.13 Reset Customizations on Detecting Errors

Oracle Composer provides a mechanism to alert users to customization errors that may cause a page to break. Users are alerted about errors in the following ways:

Errors occurring while performing any of the following operations may cause the page to break:

  • Pasting a component at the wrong position while using the Cut and Paste options; for example, pasting a table column outside the table.

  • Adding components or task flows; for example, adding a task flow that calls a Web service, which in turn gives an error.

  • Dragging and dropping Show Detail Frame components on the page.

5.4.14 Create Labels On Saving Customizations

A Save and Label button on the Oracle Composer toolbar, shown in Figure 5-40, enables users to save their customizations and create a label with those customizations. Creating labels enables users to reset customizations on a selected object to those from a selected label. This can be achieved using the Promote link in Customization Manager. For more information, see the section titled Promote Customization Metadata.

Note:

The Save and Label button is displayed only if you have configured a sandbox with an MDS database store for your application and set the allowLabel attribute on the Page Customizable component to true. For more information about this attribute, see Section B.1.1, "Page Customizable."

Figure 5-40 Save and Label Button on the Oracle Composer Toolbar

Description of Figure 5-40 follows
Description of "Figure 5-40 Save and Label Button on the Oracle Composer Toolbar"

5.4.15 Manage Customizations

The Customization Manager is an Oracle Composer add-on panel that enables users to manage customization metadata for a page and for page fragments or task flows on the page. The Customization Manager dialog displays a list of all task flows, pages, and page fragments on the page, and provides details about the layers in which these objects are customized. Users can download customization metadata for a selected page, fragment, or task flow, edit it, and upload the revised metadata file. Additionally, the Customization Manager also provides options to delete customizations and promote customizations from a previously saved label.

The Customization Manager is not available by default in your custom application. You can enable it by performing certain configurations. For more information, see Section 8.2.4, "How to Display the Customization Manager Add-On." If you configure your application to display the Customization Manager add-on, the Oracle Composer toolbar displays a Customization Manager button, as shown in Figure 5-41.

Figure 5-41 Customization Manager Button

Description of Figure 5-41 follows
Description of "Figure 5-41 Customization Manager Button"

Clicking the Customization Manager button invokes the Customization Manager dialog, shown in Figure 5-42.

Figure 5-42 Customization Manager Dialog

Description of Figure 5-42 follows
Description of "Figure 5-42 Customization Manager Dialog"

The Customization Manager displays Promote, Download, Upload, and Delete links against each task flow, page, or fragment in each layer. Users can specify a JSPX page name in the search field to view customization details about objects on that page and to manage those customizations.

Users can manage customizations in the current layer and other layers configured in the application. The Current Context column displays options to manage customizations in the current layer. This column is useful for all users who want to manage customizations they have made. The All Layers column displays options to manage customizations in all layers in the application. This column is useful for administrators who want to manage customizations made in all layers.

Notes:

  • If you have configured a sandbox for your application, all Customization Manager operations are performed in the sandbox; for example, when a user uploads a customization document, it is stored in the sandbox until the user saves or discards changes made during that session.

  • You can customize the Customization Manager to only display options of your choice. For example, you can show or hide the Download, Delete, or Upload links. Further, you can choose to show the various options for all layers or the current layer only.

    You can make these settings using parameters on the Customization Manager task flow. By enabling parameter support on the task flow, you can enable users also to customize the Customization Manager at runtime. For more information, see Section 8.8, "Enabling Parameter Support on the Customization Manager Task Flow."

This section describes the capabilities provided by the Customization Manager. It contains the following subsections:

Download Customization Metadata

A Download link enables users to download the customization document for the selected page or fragment, from the selected layer. This is useful if a user wants to edit customization metadata for a component.

The Save dialog lets users select a location for saving the document. Users can edit this file locally and upload it to the site again. For information about uploading files, see Upload Customization Metadata.

Download Customization Metadata for All Customized Objects

The Download All Customizations link at the bottom of the page enables users to download a ZIP file containing customization documents for all customized objects on the page.

Upload Customization Metadata

An Upload link enables users to upload a customization document for the selected component in a specific layer. Figure 5-43 shows the Upload Customization dialog that lets users select the file they want uploaded.

Figure 5-43 Upload Customization Dialog

Description of Figure 5-43 follows
Description of "Figure 5-43 Upload Customization Dialog"

The component is then customized based on the metadata in the uploaded document.

Note:

The usesUpload attribute on the Form tag on the page controls the display of Upload links in Customization Manager. If you set usesUpload to false, the Upload links will not work.

Delete Customization Metadata

A Delete link enables users to delete the customization document for the selected object from a specific layer.

Promote Customization Metadata

While customizing a page, users can save customizations at any point and create a new label to save those customizations. A Promote link in the Customization Manager enables users to select a label and reset customizations on the selected object to those from the label.

Notes:

The Promote option is available only in sandbox-enabled applications.

For more information about the Save and Label option in Oracle Composer, see Section 5.4.14, "Create Labels On Saving Customizations."

The Promote link invokes the Promote dialog, which lists all labels created in that layer, as shown in Figure 5-44.

Figure 5-44 Select a Label Dialog

Description of Figure 5-44 follows
Description of "Figure 5-44 Select a Label Dialog"

Users can select a label and promote that label to the sandbox for the selected object. This means that customizations for the selected object are reset to those from the specified label. If a task flow is selected, then all page fragments and page definitions are promoted. If a page or fragment is selected, then the page or fragment and its page definition are promoted.

5.5 Editing Capabilities in Source View in Page Edit Mode

Source view (Figure 5-45) provides a WYSIWYG and a hierarchical rendering of page components in a component navigator. Add Content, Edit, Delete, Cut, and Paste controls are available on the Source view toolbar provide specific operations in Oracle Composer. In Source view, users can access and modify properties of components that are not otherwise selectable in Design view. For example, many ADF Faces components can be edited only in Source view. Users can also edit components within a task flow.

Figure 5-45 Source View of a Page

Description of Figure 5-45 follows
Description of "Figure 5-45 Source View of a Page"

By default, the component navigator displays at the top of the page within Oracle Composer. Users can choose to display it at the bottom, left, or right using the Source Position option on the View menu (Figure 5-46). Users can also drag the border on the edge of the component navigator to alter its height or width.

Figure 5-46 Source Position Option on the View Menu

Description of Figure 5-46 follows
Description of "Figure 5-46 Source Position Option on the View Menu"

At the root of the component navigator is the direct child of the Page Customizable component at design time. When a node is selected in the component navigator, the corresponding component is selected on the page. Similarly, when a component is selected directly on the page, the corresponding node is selected in the component navigator.

A gray area located between the component navigator and the page displays a bread crumb trail for the selected component (Figure 5-47). The bread crumb trail shows how the component is nested on the page. When no component is selected, the bread crumb bar displays just the page name. The container names are links that when clicked highlight the selected component.

Figure 5-47 Bread Crumbs for a Component Selected in Page Source View

Description of Figure 5-47 follows
Description of "Figure 5-47 Bread Crumbs for a Component Selected in Page Source View "

Task flows that can be edited have Edit Task Flow links next to them. On clicking an Edit Task Flow link, the component navigator displays the hierarchy of components within the task flow's page or fragment. Users can edit this page or fragment and click Close to zoom out of the task flow. For more information, see Section 5.5.2, "Edit Content Inside a Task Flow." Similarly, declarative components display Open links that enable users to edit components inside the selected declarative component's facets.

Similar to Design view, in Source view also users can perform such tasks as adding components, editing page and component properties, changing page layout, and deleting components. Users can select a component on the page or in the component navigator and click the buttons on the Source view toolbar to perform these tasks. To edit or delete a component, users can also select options on the context menu for the component. In addition to these tasks, users can perform the following tasks in page Source view:

Notes:

  • The Save button is provided on the Oracle Composer toolbar (both in Design view and Source view) only if the application is configured to use a sandbox. For more information about sandboxes, see Section 10.2, "Using Oracle Composer Sandbox."

  • You can restrict users from performing all or some of these tasks by securing the application and applying customization restrictions on components. For more information, see Section 5.7, "Security and Oracle Composer."

5.5.1 Rearrange Page Content Using Cut and Paste Options

Users can rearrange components on a page using the Cut and Paste options on the Source view toolbar (Figure 5-48). A Paste menu enables users to paste a component into, before, or after any other component in the component navigator.

Figure 5-48 Cut and Paste Options on the Source View Toolbar

Description of Figure 5-48 follows
Description of "Figure 5-48 Cut and Paste Options on the Source View Toolbar"

The Cut and Paste buttons are grayed out if the user selects a component that does not support a cut or paste operation. Cut and paste operations are not supported under the following conditions:

  • The target component is not on the same page as the cut component.

  • The target component is nested inside the cut component.

  • The target component is located before or after a faceted component, that is, a component inside a facet.

  • The parent of the target component is not customizable.

  • The parent of the cut component is not customizable.

Notes:

A component on which customization is restricted can be rearranged inside its parent container if the parent is customizable.

Example

If your customizable page contains an ADF Faces Table component, then in Oracle Composer's Source view, users can resequence or move columns within or across tables and column groups. Consider a sample application created for selling computer accessories. The application home page has two tables containing details about the software and hardware offerings. The Hardware Options table contains four columns. The Hard disk column in turn contains the Magnetic disks and Solid State columns inside a column group, as shown in Figure 5-49.

Figure 5-49 Table in the Sample Application

Description of Figure 5-49 follows
Description of "Figure 5-49 Table in the Sample Application"

Users can switch to Source view and resequence the Magnetic disks and Solid State columns within the Hard disk column or move them out of the column group and paste them next to any other column (the Wireless column, for example). Figure 5-50 shows the table structure in the component navigator.

Figure 5-50 Table Columns in Source View

Description of Figure 5-50 follows
Description of "Figure 5-50 Table Columns in Source View"

Users can select a column and click Cut, then select another column and click Paste Before or Paste After.

5.5.2 Edit Content Inside a Task Flow

Oracle ADF Task flows consist of one or more views and each view in a task flow is associated with a page or page fragment. When you add a task flow to your page, the content on the fragment associated with the current view is displayed on the page. Oracle Composer enables users to edit components on the page or fragment used for the current view of a task flow. Since changes are made to the task flow's page or fragment, they are reflected in all places where the task flow's page or fragment is used.

The Source view provides an option to open a task flow and display only components on its page or fragment in the component navigator. Users can edit the page or fragment and close the task flow to navigate back to the page containing the task flow.

Users with Customize permission on a task flow can edit its page or fragment. By default, users can edit content inside any task flow on the page. However, if the task flow is included inside a Show Detail Frame component, you can disable runtime editing of the task flow by setting the selectChild attribute on the enclosing Show Detail Frame component to false. For information about this attribute, see Section B.1.5, "Show Detail Frame Component." You cannot turn off the editing capability for task flows if they are not included inside Show Detail Frame components.

Each task flow in the component navigator displays an Edit Task Flow link next to it, as shown in Figure 5-51.

Figure 5-51 Edit Task Flow Link on a Task Flow

Description of Figure 5-51 follows
Description of "Figure 5-51 Edit Task Flow Link on a Task Flow"

Clicking the Edit Task Flow link results in the Source view zooming in to display the task flow's page and its components, as shown in Figure 5-52.

Figure 5-52 Components Within a Task Flow

Description of Figure 5-52 follows
Description of "Figure 5-52 Components Within a Task Flow"

Users can select components on the task flow's page and edit them in Oracle Composer just like editing any other page components. However, Oracle Composer does not support moving components from one task flow to another.

If multiple users attempt to edit the same task flow at the same time, a concurrency warning appears in Oracle Composer that alerts each user to the others. However, this warning is displayed only if a sandbox is configured in the application. For information about how changes are saved in such cases, see "What Happens During Concurrent Edits".

Clicking the Up arrow or Close link next to an open task flow (Figure 5-53) results in the component navigator displaying the page containing the task flow.

Figure 5-53 Options to Zoom Out of a Task Flow

Description of Figure 5-53 follows
Description of "Figure 5-53 Options to Zoom Out of a Task Flow"

5.5.2.1 Reset Task Flow

The Reset Task Flow button on the Source view toolbar (Figure 5-54) invokes the Reset Task Flow dialog that provides options to remove customizations made to a task flow and reset it to a previously-saved version or to its original out-of-the-box state. You can ensure that the task flow is reset to its state in a previously-saved label only if your application is configured to use a database store. The Reset Task Flow button is rendered only on zooming into a task flow.

Note:

If you disable the Reset Page button in your application, the Reset Task Flow button is also disabled. Users cannot reset task flows after they make changes. For more information, see Section 5.4.12, "Reset Page."

Figure 5-54 Reset Task Flow Button

Description of Figure 5-54 follows
Description of "Figure 5-54 Reset Task Flow Button"

Roll Back to a Specific Label

If your application is configured to use a database store, a new version of the task flow is generated each time a user saves customizations. If a sandbox is configured for your application, by creating a label with the SAVED_LABEL_% convention you can ensure that Oracle Composer resets the task flow as follows:

  • If there is only one label name following the SAVED_LABEL_% convention, then Oracle Composer resets the task flow to its state in that label.

  • If there is no label name following the SAVED_LABEL_% convention, then Oracle Composer resets the task flow to its original, out-of-the-box state.

  • If there are multiple labels following the SAVED_LABEL_% convention, then Oracle Composer resets the task flow to its state in the latest label among these.

To roll back to a specific label, you must have configured your application to use a sandbox. Specifically, the namespace of the task flow being customized must be defined in the <metadata-namespaces> section in the application's adf-config.xml file. For more information, see Section 10.2.1, "How to Enable Oracle Composer Sandbox Creation."

Rolling back to a specific label is useful if your application has dependencies on the customization metadata and resetting the task flow to its original state may cause issues.

When a user resets a task flow, the following changes occur:

  • Only the currently selected fragment is reset. Other fragments of the task flow are not reset.

  • Nested task flows are not affected by the reset operation.

  • When a task flow is reset, changes are reflected on all pages consuming this task flow.

  • Components added to the task flow at runtime are removed. However, if the task flow's page or fragment uses a template, then components added inside Panel Customizable components on the template are not removed.

Example 5-2 shows the sample code to create a label with a SAVE_LABEL_ prefix.

Example 5-2 Code to Create a Label Prefixed with SAVE_LABEL_

import oracle.mds.versioning.VersionHelper;
import oracle.mds.naming.Namespace;
 
. . . 
long labelNumber = (long)(Math.random() * 1000000000);
String savedlabel = "SAVE_LABEL_" + labelNumber;

MDSInstance mdsInstance = (MDSInstance)ADFContext.getCurrent().getMDSInstanceAsObject();

VersionHelper vh = VersionHelper.get(mdsInstance);

Namespace[] validNamespaces = new Namespace[1];
Namespace pageNamespace = Namespace.create(<pagePath or taskflow path>, NamespaceRestriction.CUSTOMIZATIONS);

validNamespaces[0] = pageNamespace;
vh.createLabel(savedlabel, null, validNamespaces);

5.5.3 Edit Content Inside a Declarative Component

If the application page contains declarative components, users can edit these components in Oracle Composer. Editing declarative components is similar to editing task flows. For more information, see Section 5.5.2, "Edit Content Inside a Task Flow."

Figure 5-55 and Figure 5-56 show the Edit Component and Close options available on declarative components.

Figure 5-55 Edit Option On a Declarative Component

Description of Figure 5-55 follows
Description of "Figure 5-55 Edit Option On a Declarative Component"

Figure 5-56 Close Option Displayed While Editing a Declarative Component

Description of Figure 5-56 follows
Description of "Figure 5-56 Close Option Displayed While Editing a Declarative Component"

5.5.4 Show or Hide Components

To hide a component, right-click the component in the component navigator or on the page and choose Hide Component on the context menu (Figure 5-57).

Figure 5-57 Hide Component Option in Source View of the Page

Description of Figure 5-57 follows
Description of "Figure 5-57 Hide Component Option in Source View of the Page"

A hidden component is not displayed on the page, but appears grayed out in the component navigator. The context menu for a hidden component displays a Show Component option. Choosing this option renders the component on the page again.

Note:

Show or hide behavior is tied to the component's rendered property. When a user hides a component, its rendered property is set to false and vice versa. If the rendered attribute on a component has an EL value, then that value is lost on using the show or hide option. The value is set to true or false.

5.6 Oracle Composer Components

To make any JSPX document (*.jspx) editable at runtime, you must add Oracle Composer components to your page in Oracle JDeveloper at application design time.

Note:

Oracle Composer works only with JSPX pages and ADF Faces. You cannot add these components to JSP pages. For information about adding Oracle Composer components to your page, see Section 7.1, "Designing Editable Pages Using Oracle Composer Components."

The Oracle Composer tag library (Figure 5-58) available from the Component Palette provides components that you can add to make a page editable.

Figure 5-58 Oracle Composer Tag Library in the Component Palette

Description of Figure 5-58 follows
Description of "Figure 5-58 Oracle Composer Tag Library in the Component Palette"

This section provides an overview of the Oracle Composer components that are used to enable page editing. It contains the following subsections:

For more information about these components and other Oracle Composer components such as Custom Action, see Appendix B, "Oracle Composer Component Properties and Files."

5.6.1 Page Customizable

The Page Customizable component defines the editable area of a page. Within this area, you can edit component properties, add content to the page, arrange content, and so on.

Adding a Page Customizable component enables the runtime inclusion of Oracle Composer on the page. Users can edit pages in Oracle Composer using page-related controls available across the top of the page, Add Content buttons on components, and Edit icons on each editable page component, as shown in Figure 5-59.

Figure 5-59 Page Customizable Component

Description of Figure 5-59 follows
Description of "Figure 5-59 Page Customizable Component"

To enable runtime editing for multiple application pages in one operation, add a Page Customizable component to the ADF page template used for those pages. This avoids the need to manually add a Page Customizable to each page. For more information about adding the Page Customizable component, see Section 7.1.2, "How to Enable Runtime Customization Using a Page Customizable."

5.6.2 Change Mode Link and Change Mode Button

The Change Mode Link or Change Mode Button component provides an easy way to switch from View mode of the page to Edit mode. Figure 5-60 shows a Change Mode Link component on the page.

Figure 5-60 Change Mode Link Component

Description of Figure 5-60 follows
Description of "Figure 5-60 Change Mode Link Component"

For more information about using Change Mode Link or Change Mode Button, see Section 7.1.3, "How to Enable Switching Between Page Modes Using a Change Mode Link or Change Mode Button."

5.6.3 Panel Customizable

A Panel Customizable defines an area of the page onto which users can add components at runtime. Users can move or minimize Show Detail Frame components and portlets that are added as child components of a Panel Customizable. Users can also drag and drop these components into another Panel Customizable component on the page.

In Edit mode, the Panel Customizable component is rendered as a box with dotted lines. In fact, a Panel Customizable is referred to as a Box in the runtime Catalog. An Add Content button appears on each Panel Customizable component on the page, as shown in Figure 5-61. You can use this button to open the Resource Catalog Viewer and add components within the Panel Customizable.

Figure 5-61 Panel Customizable Component

Description of Figure 5-61 follows
Description of "Figure 5-61 Panel Customizable Component"

For more information, see Section 7.1.4, "How to Define Editable Areas of a Page Using Panel Customizable Components."

5.6.4 Show Detail Frame

A Show Detail Frame component renders a border or chrome around its child component along with a header that contains icons to enable users to perform some operations. The actions available on this menu enable users to move the component, along with its content, to new positions on the page (Figure 5-62). Users can also drag and drop Show Detail Frame components from one Panel Customizable component to another on the page. Note that a Show Detail Frame must be included inside a Panel Customizable component for it to be movable.

Figure 5-62 Show Detail Frame Component

Description of Figure 5-62 follows
Description of "Figure 5-62 Show Detail Frame Component"

A Show Detail Frame component enables the following actions:

  • Collapse and expand the component

  • Move content to different positions on the page

  • If you add a task flow as a child component, then along with custom actions it enables task flow navigation using the Actions menu.

  • If you add an ADF Faces Rich Text Editor as a child component, then it enables end users to edit and save text in the Rich Text Editor.

You can add your own UI controls to further customize the display of content by using facets of the Show Detail Frame. For information about using these facets, see Section 9.1, "Enabling Custom Actions on Show Detail Frame Components by Using Facets."

For information about adding this component to a page, see Section 7.1.6, "How to Enable Component Customization Using Show Detail Frame Components."

5.6.5 Layout Customizable

The Layout Customizable component is a container that enables end users to lay out its child components in several predefined ways (for example, two column, three column, and so on). You can design your page in such a way that all components on the page are enclosed in a Layout Customizable component. In such a case, the layout is applied to the entire page.

Access predefined layouts using the layout changer. By default, the layout changer displays as a small green icon both in page View mode and page Edit mode. By using the Layout Customizable component attributes you can choose to display the layout changer as an icon, text, or icon and text. In addition, you can decide whether to show or hide the layout changer in View mode. Figure 5-63 shows a Layout Customizable component and the predefined layouts that display when users click the layout changer.

Figure 5-63 Layout Customizable Component

Description of Figure 5-63 follows
Description of "Figure 5-63 Layout Customizable Component"

For more information, see Section 7.1.5, "How to Enable Layout Customization for a Page Using a Layout Customizable."

5.7 Security and Oracle Composer

In an application that is accessed by end users, application developers, and administrators, it may not be advisable to allow all users to perform all editing tasks. For example, you may want to allow end users to only customize their view of the page by performing tasks like rearranging components or hiding areas they do not want to see. On the other hand, application developers must be allowed to update content on the page, component properties, and so on. The ability to customize a page, component, or component attribute is inherited from security definitions at the tag, page, component, and attribute levels. However, you can override the default security definitions at various levels in keeping with your business requirement.

You can define application security on many levels, including on a page, an operation, a component, or a component attribute. There are several ways in which one can restrict customizations on a component. Oracle Composer determines if a component can be customized by honouring these rules. For example, before users can customize components, the components' sources of security restrictions are queried to determine if customization is allowed. If a component does not permit customization, Oracle Composer considers it restricted; that is, Oracle Composer treats the component as if it were explicitly secured. Table 5-1 describes Oracle Composer behavior to reflect customization restrictions.

Table 5-1 Customization Restrictions on Oracle Composer Components

Restriction Behavior

The page (and its contents) is open for all customizations

Oracle Composer allows editing of components without restrictions.

The page is restricted

Oracle Composer displays but none of the options, for example Page Properties button and Edit icon, are accessible.

Some operations are restricted

Oracle Composer displays but the options corresponding to the restricted operations are disabled.

A component is restricted

The Edit icon is not rendered on the component and its properties cannot be edited.

A component's attributes are restricted

The restricted attributes are not displayed in Oracle Composer.

Oracle Composer's API enables the developer to determine if a component's attributes are restricted or not.


Depending on the privileges granted while implementing security, users can perform different personalization and editing tasks when they log in to the application.

Note:

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.

You can enable the Edit link or button for selected users by specifying an EL value for the rendered attribute on the Change Mode Link or Change Mode Button component. For more information, see Section B.1.2, "Change Mode Link and Change Mode Button."

This section describes the default security behavior of Oracle Composer components. It contains the following subsections:

For information about overriding default security behavior, see Chapter 11, "Modifying Default Security Behavior of Oracle Composer Components."

5.7.1 Page Security

The application's jazn-data.xml file is the repository for page-level security information. Oracle Composer references this file and enables editing capabilities based on a user's privileges:

  • A user with the Personalize privilege on a page can perform only the personalizations described in Section 5.3, "Personalizing Capabilities in Page View Mode."

  • A user with the Edit or Customize privilege can perform all runtime editing tasks such as adding content, editing component properties, and deleting components. Oracle Composer and WebCenter Customizable Components do not differentiate between Edit and Customize privileges.

Notes:

Oracle Composer and WebCenter Customizable Components support cascading of page privileges with Grant being a super set of all privileges. A user with Grant privilege on a page is considered to have Edit, Personalize, and View privileges. A user with Personalize privilege is considered to additionally have the View privilege.

Table 5-2 explains Oracle Composer behavior based on page-level privileges. Only those page privileges that are relevant to Oracle Composer and WebCenter Customizable Components privileges are listed in this table. The Grant privilege is not listed as it is a super set of all privileges. Users with the Grant privilege can perform all editing tasks. The table also does not list the View privilege because users with the View privilege cannot personalize or edit a page.

Table 5-2 Mapping of Page Privileges to Oracle Composer Behavior

Privilege Oracle Composer Behavior

Edit or Customize

Users can switch to Edit mode, where Oracle Composer is invoked, and edit the page.

Users with either the Edit or Customize privilege can perform all runtime editing tasks.

With the Edit or Customize privilege, users can:

  • Add content

  • Edit component properties

  • Rearrange content

  • Delete components in Oracle Composer

  • Personalize or customize a portlet

  • Move a portlet or task flow in View mode. This is persisted as a personalization.

  • Expand and collapse a task flow or portlet in View mode. This is persisted as a personalization.

  • Resize a column of a table in a task flow. This is persisted as a personalization.

  • Reset the page to its original state

  • Delete components in View mode

If users without Edit or Customize permission try to edit a page, a message appears stating that they do not have permission to do so.

Personalize

In View mode users can:

  • Rearrange content

  • Personalize a portlet

  • Move a portlet or task flow in View mode. This is persisted as a personalization.

  • Expand and collapse a task flow or portlet in View mode. This is persisted as a personalization.

  • Resize a column of a table in a task flow. This is persisted as a personalization.

  • Delete components in View mode

Note: Having Personalize permission does not enable users to perform portlet customizations.

If users without Personalize, Edit, or Customize permission try to edit a page, a message appears stating that they do not have permission to do so.


5.7.2 Task Flow Security

When you add a task flow to a customizable page, Oracle Composer provides options for editing the task flow and components on the task flow's page. In a secured application, Oracle Composer provides editing capabilities based on the privileges provisioned on the customizable page and the task flow.

On an application page, components can be located directly on the JSPX page or on page fragments inside shared components such as task flows. Restrictions on components inside a task flow are derived from the page fragment. To understand task flow security better, consider an example of a page containing a task flow, which in turn contains another task flow, as shown in Figure 5-64.

Figure 5-64 Structure of a Page Containing Nested Task Flows

Description of Figure 5-64 follows
Description of "Figure 5-64 Structure of a Page Containing Nested Task Flows"

Components on this page inherit security as follows:

  • Component1, Component2, and Region3 inherit security definitions from Document.jspx.

  • ComponentA, ComponentB, and RegionC inherit security definitions from region3.jsff.

  • ComponentX and ComponentY inherit security definitions from regionC.jsff.

Task flows do not support cascading of permissions. That is, page permissions are not inherited by components inside a task flow. However, users who do not have Edit or Customize permission on the page cannot customize task flows on the page.

For example, if you grant Edit or Customize permission on Document.jspx and regionC.jsff but not on region3.jsff, then users can customize Component1, Component2, RegionC, ComponentX, and ComponentY, but not ComponentA, ComponentB, and RegionC.

In a secured application, task flow permissions are stored in the application's jazn-data.xml file. The list of available actions for a task flow is defined by the task flow permission class, oracle.adf.controller.security.TaskFlowPermission. The permission class defines task flow-specific actions that it maps to the task flow's operations. By default, only View permission is provisioned on task flows. To enable users to edit a task flow at runtime, you must ensure that Customize permission is granted on the task flow. For more information, see Section 7.3.1.1, "Considerations for Adding Task Flows" and Section 11.6, "Applying Task Flow Restrictions."

For more information about task flows and their security behavior, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

5.7.3 MDS Customization Restrictions

WebCenter applications have a default MDS configuration that restricts customization on all application objects. To enable runtime page editing, you must make this default restriction inactive by adding a Page Customizable component to the page. A Page Customizable component enables customization on all components under it. However, it does not enable customization on components of a nested page or fragment. For example, if the Page Customizable is used in a page template and has a Facet Ref inside it, then customization is not enabled by default on the components inside the Facet Ref.

You can enable customization on a set of attributes for the component using MDS type-level restrictions or instance-level restrictions. Type-level restrictions are applicable to a specified component type across instances. At runtime, attributes for which you have enabled customization are shown as editable properties in Oracle Composer, and restricted attributes are not displayed in the Component Properties dialog for the selected component. For information, see Section 11.1, "Applying Component-Level Restrictions by Defining Customization Policies."

5.7.4 Component Action-Level Security

Panel Customizable and Show Detail Frame components enable the placement of restrictions on individual supported actions. For example, one can specify a restriction on whether the current user is allowed to minimize the Show Detail Frame.

It is left to you to enforce restrictions on the actions on a component. You can specify restriction on component actions in adf-config.xml. If a restriction is specified and applicable to the current user, the Panel Customizable or Show Detail Frame does not render the action.

For information about applying action-level restrictions, see Section 11.5, "Applying Action-Level Restrictions on Panel Customizable and Show Detail Component Actions."