Customize and Personalize an Application

You can work in JDeveloper's IDE to customize and personalize an application that is built with Oracle ADF Faces and Oracle ADF Business Components.

Install the schema: Download the schema zip file from OTN and install it. The cue cards use tables that are part of the Fusion Order Demo (FOD) schema.

Create a new application: Use the Create Application dialog to create an application that uses the Fusion Web Application (ADF) template.

Create a database connection: Use the Create Database Connection dialog to create a connection to the schema.

Create Oracle ADF Business Component objects: Use the Create Oracle ADF Business Components wizard to create the business components that will provide access to data and implement the business logic.

Define customization layer values and create a customization class: Add customization layer values to the files CustomizationLayerValues.xml and customization.properties. Create the customization class that evaluates which customization layer should be applied to the application's base definition metadata.

Enable seeded customizations and create customizable JSF pages: Use the Project Properties dialog to enable seeded customizations in the ViewController project. Then use the Create JSF Page wizard to create JSF pages that allow customizations to be made.

Use the Customization Developer role to customize a JSF page and view object: Use the Preferences dialog to switch to the Customization Developer role. Then in the Customizations panel, select the layer value before you begin customizing. Run the application after making the customizations.

Enable user customizations for the duration of a session: Use the Preferences dialog to switch to the Default role for user customizations. Use the Project Properties dialog to enable user customizations for the duration of a session. Run the application.

Enable user customizations across sessions: Use the Project Properties dialog to enable user customizations across sessions. Edit the adf-config.xml file to include the configuration elements to use a repository and customization class for change persistence. Then configure the components, attributes, and operations that you want to be persisted in the repository. Run and personalize the application.

Install the Schema

1. Download the schema zip file from OTN. If you created the schema previously, go to the next cue card.
2. Unzip the file to a convenient location (for example, c:\temp).
3. From the File menu, choose Open. Open the workspace c:\temp\Infrastructure\infrastructure.jws.
4. If you are prompted to migrate the project, click Yes to confirm.
5. In the Application Navigator, expand the MasterBuildScript project and double-click build.properties to open it in the editor.
6. Set the appropriate values in the build.properties file (jdeveloper.home, and all the jdbc.* and db.* settings). Keep all other properties set to their default values. The demo user must be named FOD.
   The relevant settings are:
   jdeveloper.home             Location where you have installed JDeveloper, for example, c:/JDeveloper/11g
   jdbc.urlBase                    Base URI for your database, for example, jdbc:oracle:thin:@localhost
   jdbc.port                         Port number for your database, for example, 1521
   jdbc.sid                           Database System Identifier, for example, XE or ORCL
   db.adminUser                  Database user with admin privileges, for example, system
   db.adminUser.password   Password for database user with admin privileges, for example, manager
   db.demoUser.tablespace  Tablespace name where the FOD user will be installed, for example, USERS
7. In the MasterBuildScript project, select the build.xml file.
8. In the Structure window, right-click the refreshSchema target and choose Run Target "refreshSchema."
   

   In the IDE

   After running the Ant task, you should see a build successful message in the JDeveloper Log window.   [tell me more...]

Create a New Application and Project

1. Open the Create Application dialog [File > New > General > Applications] .
2. To follow along with the example, enter CustomizeApp as the application name, and oracle as the application package prefix.
3. Select Fusion Web Application (ADF) in the Application Template listbox, then click Finish.
   

   Application Templates

   Application templates provide you with a quick way to create the project structure for standard applications with the appropriate combination of technologies already specified. The new application created from the template appears in the Application Navigator already partitioned into tiered projects, with the associated technology scopes set in each project.   [tell me more...]

   
   

   In the IDE

   The Application Overview window opens by default in the editor window area when you create a new application. All objects that you create within JDeveloper appear in the Application Overview, arranged by object type. You can create new objects, read about new types of objects that you haven't yet created, and initiate actions from the objects' context menus.   [tell me more...]

Create a Database Connection

1. Open the Create Database Connection dialog [File > New > General > Connections > Database Connection] .
2. Select Application Resources if it is not already selected as the Create Connection In option.
3. Enter a name for the connection, select the connection type, and enter the username and password. To follow along with this example, use FOD for the connection name, fod for the username and fusion for the password.
4. Select Deploy Password to bypass authentication at runtime.
   

   Database Connections and Password Deployment

   When you create a database connection, you specify a username and password to authenticate the connection.   [tell me more...]

5. Click Test Connection to confirm that you can connect.
6. Click OK if the connection was successful.
7. In the Application Navigator, expand the Connections and Database nodes in the Application Resources panel to see the database objects.
   

   In the IDE

   When you complete the steps for creating a database connection, the Application Navigator should look similar to this when you expand the Application Resources panel. The database connection is now included as a resource for your application under the Connections | Database nodes.   [tell me more...]

Create Oracle ADF Business Components

1. In the Application Navigator, select the Model project and launch the Create Business Components from Tables wizard [File > New > Business Tier > ADF Business Components > Business Components from Tables] .
2. In the Initialize Business Components Project dialog, ensure that FOD is the currently selected database connection. Then click OK.
   

   Business Components Connection

   The Oracle ADF Business Components project requires a database connection that you will use to create business components from database objects. The database connection you specify will also be used by the Oracle ADF Business Components runtime to manage Session Facade failover and state management.  [tell me more...]

3. On step 1, Entity Objects, click Query to populate the Available list. If your schema has many tables, you may experience a short delay.
4. Select the tables, ORDERS, ORDER_ITEMS, and PRODUCTS_BASE from the Available list and then click to move them to the Selected list. Click Next.
   

   Oracle ADF Business Components from Database Tables

   JDeveloper provides a wizard that allows you to easily create a package of business domain components (entity objects, associations, and domains) from existing database objects and optionally to create a default package of data model components (view objects, view links, and an application module) from these newly generated business domain components.  [tell me more...]

5. On step 2, Updatable View Objects, click to move the business components, OrderItems (FOD.ORDER_ITEMS), Orders (FOD.ORDERS), and ProductsBase (FOD.PRODUCTS_BASE) from the Available list to the Selected list. Then click Next.
6. Click Next to skip step 3, Read-Only View Objects, which aren't needed.
7. On step 4, Application Module, change the application module name to FODAppModule. Then click Finish.
   

   Oracle ADF Business Components

   The Create Business Components from Tables wizard does not create a user interface (this is governed by the "view" portion of the application), nor does it determine other application logic such as control flow. It just provides a representation of, and access to, data, and implements business logic.  [tell me more...]

8. Click Save All to save your work.
   

   In the IDE

   After completing the Create Business Components from Tables wizard, the Data Controls panel and the Model project in the Application Navigator should look like the following:  [tell me more...]

Define a Customization Layer

1. From the main menu, choose File Open to select and then open the file CustomizationLayerValues.xml, which is located in <JDEVELOPER_HOME>/jdev.
2. In the XML source editor, edit the file to add a customization layer and its configurable values. Use the sample code provided.
   

   Customization Layers

   In Oracle Application Developer Framework (ADF) applications, the Oracle Metadata Services (MDS) framework allows you to create customizable applications. You create customization classes and layers to support the customization of metadata content, and then customize the metadata within the context of a specified layer. In this cue card you will create a customization layer. You will create a customization class in the next cue card.   [tell me more...]

   
   Use sample code
3. In the Application Navigator, select the Model project and open the Create File dialog [File > New > General > File] .
4. Enter customization.properties as the file name. In the Directory field, append src after Model (for example, <JDEVELOPER_HOME>/mywork/CustomizeApp/Model/src). Then click OK.
5. In the text editor, define the customization layer values.
   Use sample code
6. Click Save All to save your work.
   

   In the IDE

   When you complete the steps for defining a customization layer, the Application Navigator should look like this:   [tell me more...]

Create and Deploy a Customization Class

1. In the Application Navigator, select the Model project and open the Create Java Class dialog [File > New > General > Java Class] .
2. Enter SiteCC as the class name, and oracle.model.mycompany as the package name. In the Extends field, enter oracle.mds.cust.CustomizationClass. Click OK.
   

   Customization Classes

   A customization class is the interface that the Oracle Metadata Services (MDS) framework uses to define which customization layer should be applied to the application's base definition metadata. Each customization class corresponds to a customization layer. The customization class evaluates the current context and returns a String result. This String result is used to locate the customization layer.  [tell me more...]

3. In the Java source editor, add code to build the customization layer.
   Use sample code
4. In the Application Navigator, select the Model project, then click Rebuild to rebuild the project.
5. In the Application Navigator, select the Model project and open the Create Deployment Profile - JAR File dialog [File > New > General > Deployment Profiles > JAR File] .
6. Enter oracle.model.mycompany.customization.layers.1.0 as the deployment profile name, and click OK.
   

   Deployment Profiles

   Deployment profiles are used to define the settings for archives in order to deploy a project or an application to an external server. In the example, you are creating a profile for deploying a simple archive to the file system. JDeveloper will use the deployment profile name you enter in the Create Deployment Profile dialog as the name of the generated JAR when you deploy the project.   [tell me more...]

7. In the Edit JAR Deployment Profile Properties dialog, JAR Options, make sure Include Manifest File is selected. In the JAR File field, accept the default JAR file name, but change the location of the JAR to <JDEVELOPER_HOME>\jdev\lib\patches\<jar_file_name>.
8. Under File Groups | Project Output on the left, select Filters. In the Files tab, deselect the top node Merged Contents of This File Group's Contributors. This should deselect all the checkboxes. Expand model under oracle, then select mycompany. Click OK. In the Project Properties dialog, click OK.
9. Click Save All to save your work.
10. In the Application Navigator, right-click the Model project, and choose Deploy oracle.model.mycompany.customization.layers.1.0 to JAR. You should see some messages followed by a Deployment Finished message in the Deployment log window.
11. In the Application Navigator, expand the Application Resources panel. Under Descriptors, expand ADF META-INF. Double-click adf-config.xml to open the file in the default editor. Add the customization class to the file.
    

    Registering Customization Classes

    Multiple customization layers can be applied on top of the application's base metadata. Layered customization is applied in the order of precedence as defined by the order of customization classes in the configuration file adf-config.xml.   [tell me more...]

    
    Use sample code
12. Click Save All to save your work.
    

    In the IDE

    When you complete the steps for creating and deploying a customiation class, the Application Navigator should look like this:  [tell me more...]

Create Customizable JSF Pages

1. In the Application Navigator, select the ViewController project and open the Project Properties - ADF View dialog. Select Enable Seeded Customizations, and click OK.
   

   Seeded Customizations

   Seeded customization of an application is the process of taking a generalized application and making modifications to suit the needs of a particular group, such as a specific industry or site.   [tell me more...]

2. In the Application Navigator, select the ViewController project and open the Create Task Flow dialog [File > New > Web Tier > JSF > ADF Task Flow] . Enter orders-task-flow-definition.xml as the file name. Make sure Create as Bounded Task Flow is selected. Deselect Create With Page Fragments, if selected. Then click OK.
   

   Bounded Task Flows

   An ADF task flow is a reusable unit for defining control flow between activities in an application. Each task flow in the application contains a portion of the application's navigational graph, enabling users to complete a task. For example the following illustration shows a simple task flow with two activities, Create and Confirm. The arrows between the activities are known as control flow cases. Activities could be view pages, method calls, or operations calling other task flows.   [tell me more...]

3. In the Component Palette, ADF Task Flow page, Components panel, click View, then click on the blank diagram in the visual editor to add an icon to represent the first application page. Rename the page to Browse. In the Component Palette, click View again, and then click the diagram to add a second page icon. Rename the second page to More.
4. In the Component Palette, ADF Task Flow page, Components panel, click Control Flow Case. On the diagram, click the browse page icon, then click the more page icon. Rename the control flow case element to goMore.
5. In the Component Palette, click Control Flow Case again. On the diagram, click the more page icon, then click the browse page icon. Rename the control flow case element to goBrowse.
   

   Task Flow Definition

   At this point the task flow diagrammer should look similar to this:  [tell me more...]

6. On the diagram, double-click the Browse page icon. In the Create JSF Page dialog, accept the default file name and location. Make sure Allow Customizations is selected. Do not use a template or managed bean. Click OK.
   

   Creating JSF Pages

   When working with customizations, you are allowed to create .jspx page files only. In the Create JSF Page wizard, for each page that you create you can decide whether you want the page to be customizable.  [tell me more...]

7. In the Component Palette, ADF Faces page, Layout panel, drag and drop Panel Stretch Layout on the blank page in the visual editor. In the Property Inspector, Style panel, enter AFVisualRoot in the StyleClass field. Then drag and drop Panel Splitter into the center facet in the visual editor. In the Property Inspector, Common panel, change the Orientation property value to vertical. In the Component Palette, Layout panel, drag and drop Panel Group Layout into the first facet of the panel splitter in the visual editor. In the Property Inspector, change the Layout property value to scroll.
8. In the Application Navigator, expand the Data Controls panel. Expand FODAppModuleDataControl. Drag and drop OrdersView1 into af:panelGroupLayout - scroll in the Structure window. From the Create context menu, choose Forms ADF Read-Only Form.
9. In the Edit Form Fields dialog, select both Include Navigation Controls and Include Submit Button checkboxes. Select all the fields except OrderId, OrderDate, OrderShippedDate, OrderStatusCode, and OrderTotal. Click to delete the selected fields. Then click OK.
10. In the visual editor, select the Submit button. In the Property Inspector, Common panel, change the Text value to More Details. In the Action field, select goMore from the dropdown list.
11. In the Data Controls panel, expand OrdersView1. Under OrdersView1, locate OrderItemsView2, then drag and drop OrderItemsView2 into the second facet of af:panelSplitter in the Structure window. From the Create context menu, choose Tables ADF Read-Only Table. In the Edit Table Columns dialog, select Sorting. Select the columns ObjectVersionId, LastUpdateDate, LastUpdatedBy, CreationDate, and CreatedBy. Click to delete the selected fields. Then click OK.
12. In the editor window, select the document tab orders-task-flow-definition.xml to bring the diagram to the front. Double-click the More page icon. In the Create JSF Page dialog, accept the default file name and location. Confirm that Allow Customizations is selected, and do not use a template or managed bean. Click OK.
13. In the Component Palette, ADF Faces page, Layout panel, drag and drop Panel Stretch Layout on the blank page in the visual editor. In the Property Inspector, Style panel, enter AFVisualRoot in the StyleClass field. Then drag and drop Panel Group Layout into the center facet on the page. In the Property Inspector, change the Layout property value to scroll. Drag and drop Show Detail Header into the panel group layout component you just added. Right-click af:showDetailHeader in the Structure window and choose Insert inside af:showDetailHeader Panel Group Layout.
14. In the Data Controls panel, drag and drop OrdersView1 into af:panelGroupLayout that is under af:showDetailHeader in the Structure window. From the Create context menu, choose Forms ADF Read-Only Form. In the Edit Form Fields dialog, click OK.
15. In the Component Palette, ADF Faces page, Common Components panel, drag and drop Button into af:panelGroupLayout - scroll in the Structure window. In the Property Inspector, Common panel, change the Text value to Return. In the Action field, select goBrowse from the dropdown list.
16. Click Save All to save your work.
17. Test run the pages you have created. In the Application Navigator, right-click orders-task-flow-definition.xml and choose Run. In the Confirm Run/Debug Bounded Task Flow dialog, select Skip This Message Next Time, then click Yes.
    

    In the IDE

    When you complete the steps for creating customizable JSF pages, the Application Navigator should look similar to this:  [tell me more...]

Customize a JSF Page and a View Object

1. Open the Preferences - Roles dialog. Select Customization Developer and click OK. When prompted in the Confirm Restart dialog, click Yes to restart JDeveloper.
2. In the Customizations window, select Headquarters (headquarters) in the Value dropdown list of the site layer.
   

   Customizations Window and Tip Layer

   You can make metadata customizations in a project only when you are working in the Customization Developer role. In that role, customization features are enabled in the IDE (for example, the Customizations window), while some other features are disabled (for example, you cannot create new customizable objects and non-customizable objects cannot be modified).  [tell me more...]

3. In the Application Navigator, double-click Browse.jspx to open the page in the visual editor. Click the first column in the table.
4. In the Structure window, right-click af:table and choose Surround With. In the Surround With dialog, select Panel Collection, and click OK. In the Property Inspector, Behavior panel, enter pc1 in the CustomizationId field. Click Save All to save the changes.
   

   Customizing Metadata in the View Layer

   In the example, you have customized the Browse page by adding a panel collection component around the OrderItems table.  [tell me more...]

5. In the Customizations window, select Remote Offices (remoteoffices) from the Value dropdown list. If prompted by a message in the Customization Context Change dialog, just click OK.
6. In the Application Navigator, double-click Browse.jspx to open the page again. Click the first column in the table. (You should not see the panel collection component around the table component.)
7. In the Structure window, select af:table. In the Property Inspector, Style panel, click Box. In the Width field, enter 100%.
8. In the Structure window, right-click af:table and choose Surround With. In the Surround With dialog, select Show Detail, and click OK. In the Property Inspector, Behavior panel, enter sd1 in the CustomizationId field. Click Save All to save the changes.
   

   Customization Document for Remote Offices Layer Value

   To reiterate, each customization document is created in its own customization layer value folder. When implementing customizations for the Browse page in the site/remoteoffices layer value, another Browse.jspx.xml is created, this time in the /mdssys/cust/site/remoteoffices folder, as shown in the following Application Navigator illustration:   [tell me more...]

9. In the Application Navigator, expand the Model project. Under Application Sources, expand oracle.model, then double-click OrderItemsView. In the overview editor for view objects, select Entity Objects on the left. In the Available list, select ProductsBase. Then click to move it to the Selected list.
10. In the overview editor for view objects, select Attributes on the left. Click Add From Entity. In the Attributes dialog, under ProductsBase in the Available list, select ProductName. Then click to move it to the Selected list. Click OK. Click Save to save the file.
    

    Customizing Metadata in the Model Layer

    In the example, you have customized the model view object OrderItemsView by adding the ProductName attribute from the ProductsBase entity object. This will enable you to add a ProductName column to the OrderItems table on the Browse page in the next step.  [tell me more...]

11. In the editor window, click the document tab Browse.jspx to bring the page visual editor to the front. Click the first column in the table. In the Structure window, select af:table.
12. In the Data Controls panel, expand OrdersView1, then expand OrderItemsView2. Drag the new attribute ProductName and drop it into af:table in the Structure window. From the Create context menu, choose Columns ADF Read-Only Column. In the Property Inspector, Behavior panel, enter newcol1 in the CustomizationId field.
    

    Page Definition Customization Document

    You choose ADF Read-Only Column from the Create context menu because the table you created earlier is read-only.   [tell me more...]

13. Click Save All to save your work.
    

    In the IDE

    When you complete the steps for customizing the Browse view page and the OrderItemsView view object in the model layer, the Browse page in the visual editor should look similar to this:  [tell me more...]

Run the Application in the Customization Layer

1. In the Application Navigator, ViewController project, right-click orders-task-flow-definition and choose Run. The OrderItems table should have a View and Detach menu above the column names. In the table, you should not see a ProductName column.
   

   Customization Properties File

   At this point, your customization.properties file contains the following layer values:  [tell me more...]

2. In the application running log window, click to stop the application.
3. In the file system, open the file customization.properties, which is located in the /Model/src folder in the application folder (for example, <JDEVELOPER_HOME>/mywork/CustomizeApp/Model/src). In the text editor, add # in front of site=headquarters. Remove # from site=remoteoffices. Save the file.
4. In the Application Navigator, right-click orders-task-flow-definition and choose Run again. You should be able to hide or show the OrderItems table. In the table, you should see the sixth column ProductName.
   

   In the IDE

   When you run the application with the site=headquarters layer value active, the Browse page in your browser should look similar to this:  [tell me more...]

Enable User Customizations For the Duration of a Session

1. If you are not already in the Default role, open the Preferences - Roles dialog. Select Default Role and click OK. When prompted in the Confirm Restart dialog, click Yes to restart JDeveloper.
2. In the Application Navigator, select the ViewController project and open the Project Properties - ADF View dialog.
3. Select Enable User Customizations, then click For Duration of Session. (Don't deselect Enable Seeded Customizations.) Click OK.
   

   User Customizations

   User customizations or change persistence allow end users to make changes to certain UI components at runtime to suit individual preferences (for example, which columns are visible in a table). There are two types of user customizations:  [tell me more...]

4. Click Save All to save your work.
5. In the Application Navigator, ViewController project, right-click orders-task-flow-definition and choose Run.
6. On the Browse page, increase the width of a table column. Click More Details to navigate to the More page. On the More page, click Return to go back to the Browse page. The width of the column you changed should remain at the new width.
   

   Session Change Persistence

   Many ADF Faces components allow users to change the display of the component at runtime. For example, a user can change the position of the splitter in the Panel Splitter component or change whether or not a Show Detail or Show Detail Header component displays the children contents. By default, these changes live only as long as the page request. If the user leaves the page and then returns, the component displays in the manner it is configured by default.   [tell me more...]

7. Try moving a column or hiding the table on the Browse page by collasping the show detail component, or hiding the form on the More page by collasping the show detail header component. Navigate back and forth between the pages each time you make a change. All changes you make should persist during the session.
8. In the application running log window, click to stop the application. Rerun the application. You should not see any of the changes you made.
   

   In the IDE

   In the Application Navigator, ViewController project, WEB-INF folder, if you double-click web.xml to open the file in the default overview editor, you should see that CHANGE_PERSISTENCE has been added to the Context Initialization Parameters subsection in the Application section. The value of CHANGE_PERSISTENCE should be session.   [tell me more...]

Enable User Customizations Across Sessions

1. If you are not already in the Default role, open the Preferences - Roles dialog. Select Default Role and click OK. When prompted in the Confirm Restart dialog, click Yes to restart JDeveloper.
2. In the Application Navigator, select the ViewController project and open the Project Properties - ADF View dialog.
3. Select Enable User Customizations, then click Across Sessions Using MDS. (Don't deselect Enable Seeded Customizations.) Click OK.
   

   Change Persistence Using MDS

   User customizations or change persistence allow end users to make changes to certain UI components at runtime to suit individual preferences (for example, which columns are visible in a table). There are two types of user customizations:  [tell me more...]

4. In the Application Navigator, expand the Application Resources panel. Under Descriptors, expand ADF META-INF. Double-click adf-config.xml to open the file in the default editor. Add the customization class for user customizations: <customization-class name="oracle.adf.share.config.ADFUserCC"/>. Set the MDS repository to the path from where the page files are served. Add code to declare the components and associated attribute values or operations that you want to be persisted in the repository. (This needs to be done not only for any explicit changes that you will be creating, but also for components that implicitly persist certain attribute values.)
   

   MDS Change Persistence

   Certain ADF Faces components have built-in support for session change persistence, that is, they provide persistence through implicitly persisted attributes, without any coding or event handling on your part. For example, the splitterPosition attribute of Panel Splitter, width attribute of Column, and disclosed attribute of Show Detail Header and Show Detail. For a complete list of implicitly persisted attributes and components, see the ADF Faces documentation on OTN.   [tell me more...]

   
   Use sample code
5. Click Save All to save your work.
   

   In the IDE

   In the Application Navigator, ViewController project, WEB-INF folder, double-click web.xml to open the file in the default overview editor. In the Context Initialization Parameters subsection of the Application section, you should see that the value of CHANGE_PERSISTENCE should be oracle.adf.view.rich.change.FilteredPersistenceChangeManager.   [tell me more...]

Run and Personalize the Application

1. In the Application Navigator, ViewController project, right-click orders-task-flow-definition and choose Run.
2. In the OrderItems table in the browser, move the ProductId column to place it after the OrderId column. Click More Details to navigate to the More page. On the More page, click Return to go back to the Browse page. The change you made should be persisted.
   

   Change Persistence Metadata Files

   The first time you make a persistent component attribute change on the Browse or More page, JDeveloper creates an XML metadata change persistence file using the page's file name, and stores the XML file in the mdssys|cust|user folder under Web Content in the ViewController project in the Application Navigator:   [tell me more...]

3. On the Browse page try decreasing a column width, sorting a column, or hiding the table. On the More page, try hiding the form. Navigate back and forth between the pages each time you make a change. All changes you make should be persisted.
4. In the application running log window, click to stop the application.
5. In the Application Navigator, right-click orders-task-flow-definition and choose Run again. The last change you made on each persistent component attribute should be available, except sorting on a column.
   

   In the IDE

   In the Application Navigator, ViewController project, under the mdssys|cust|user|anonymous folder in Web Content, you should see the XML metadata change persistence files created for Browse.jspx and More.jspx.   [tell me more...]