|Oracle® Fusion Middleware Tutorial for Oracle WebCenter Developers
11g Release 1 (11.1.1)
Part Number E10273-03
In this lesson, you will create a basic custom WebCenter application, then create a page within the application where you will later add services, content, and portlets. You will update your application with existing resources (like images and a CSS file) that we have provided so that you can use them with your application. You will also add layout components and Oracle Composer to the page, so that you (and your users) can customize the page at runtime. At the end of the lesson, we will experiment with customizing our page at runtime using Oracle Composer.
Figure 3-1 shows the page you will create in this lesson.
Figure 3-1 MyPage.jspx at the End of this Lesson
This lesson contains the following steps:
Before you begin the steps in this lesson, ensure you have followed the steps up to this point in the Tutorial.
Let's begin by building a simple custom WebCenter application. You will then create a page for this application that will serve as the interface for the application. This step introduces you to the WebCenter application template, as well as the Application Navigator, which helps you view various parts of your application.
To create a custom WebCenter application:
In Oracle JDeveloper, from the File menu, choose New.
In the New Gallery, on the Current Project Technologies tab, you should see the General category highlighted. Under General, click Applications.
In the Items list, scroll down and select WebCenter Application, then click OK (Figure 3-2).
Figure 3-2 Create New WebCenter Application
On the Application Name tab, in the Application Name field, enter
MyTutorialApplication and leave the other default values as they are, as shown in Figure 3-3. In this example, the
d:\jdev_system. However, your directory may be different.
Figure 3-3 Name a New WebCenter Application
Click Finish. Oracle JDeveloper generates the base files, including two projects, for your application, which you can see in the Application Navigator (Figure 3-4):
Model, in which you define the JavaBeans and other data controls you need if the application is to perform any back-end logic.
ViewController, in which you create the JavaServer Faces (JSF) page that will consume WebCenter services and portlets.
Figure 3-4 Generated Application Project Files in the Application Navigator
Let us make a few adjustments for the purposes of testing our application. Right-click the ViewController project, then choose Project Properties (Figure 3-5).
Figure 3-5 Editing the Project Properties
In the Project Properties dialog, in the left column, choose Java EE Application (Figure 3-6).
Figure 3-6 Project Properties: Java EE Application
Here, we will change the context root of the application to make it easier for us to reference the application resources that we will use throughout this Tutorial. In the Java EE Web Application Name field, enter:
In the Java EE Web Context Root field, enter the same value:
The Project Properties dialog should now look like Figure 3-7:
Figure 3-7 Project Properties with the Modified Context Root Values
Click OK to accept your changes.
Save your application by clicking the Save All icon in the toolbar.
For more information on creating an application based on the WebCenter template, see Chapter 3, "Preparing Your Development Environment" in Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
Now that you have created a basic custom WebCenter application, you can create a page. Before we create the page, though, we must add the resource files to our application so that we can use them with our page.
Now that you have created the application, you can add the resource files that you will need to complete the steps in the Tutorial. Here, you will add the image files, the CSS file, and the login page that you downloaded in Chapter 2, "Preparing for the Tutorial." This step shows you how you can take existing files (for example, your own organization's logo images) and incorporate them into a WebCenter application.
To add the resource files to the application:
Ensure that you have followed the steps in Chapter 2, "Preparing for the Tutorial," which includes the step for obtaining the Tutorial sample files you will add.
In your file system directory (for example, Windows Explorer), navigate to the location where you installed Oracle JDeveloper (
JDev_Home) and locate the following directory:
JDEV_USER_HOME refers to the default directory where JDeveloper stores your projects, and depends on how the
JDEV_USER_HOME environment variable is set. This could be, for example, your
C:\ drive, or it could be
D:\Oracle\Middleware\, and so on. You should examine your file system to find out where this directory is set.
Figure 3-8 shows an example of where the images folder will be located where the
JDEV_USER_HOME is set to
Figure 3-8 Example of the Images folder in the JDEV_USER_HOME
MyTutorialApplication subdirectory was automatically generated when you created the application.
Locate the Tutorial sample files you downloaded and extracted in Chapter 2, "Preparing for the Tutorial," and copy the
C:\TutorialContent\images folder to your
Return to Oracle JDeveloper and click the Refresh icon next to the Projects list in the Application Navigator. You should now see the
images folder in the Application Navigator (Figure 3-9).
Figure 3-9 Images in the Application Navigator
Note:Notice that the image names are enumerated:
2.jpg, and so on. These image names match the product ID of the items we will retrieve when we create our portlets in Chapter 6, "Building Portlets and Wiring Them in Your Application." If you change the names of these image files, the statement may not return the correct results.
You can now use these images with your application.
While you are here, also add the CSS skin and its associated images that you will apply to the application in Chapter 7, "Step 1: Change the Application Look and Feel Using a Skin". You will not do anything with this skin just yet.
Return to your file system.
In your file system explorer, copy the
C:\TutorialContent\css folder to your
\mywork\MyTutorialApplication\ViewController\public_html directory (Figure 3-10).
Figure 3-10 CSS Directory with the TutorialSkin.CSS file in the JDEV_USER_HOME
Return to JDeveloper and refresh the Application Navigator to see the css directory and its contents (
TutorialSkin.css), as shown in Figure 3-11.
Figure 3-11 CSS File in the Application Navigator
Next, add the new
mylogin.html page that you will use in Chapter 4, "Adding Security to Your Application." In the files that you downloaded,
Copy and paste this file to the
Return to JDeveloper and refresh the Application Navigator. You should see the mylogin.html file in the Web Content directory, as shown in Figure 3-12.
Figure 3-12 Mylogin.html Page in the Web Content Directory
You now have all the resource files you need to complete the steps in this Tutorial.
In this step, you will learn how to create a simple JSF page for your application, which will contain the services and portlets that you will configure and add in the subsequent steps of this Tutorial. You will use one of Oracle WebCenter Framework's pre-built "quick start" layouts as a starting point. This step introduces you to the Create JSF Page dialog and the Visual Editor, as well as the Structure window.
To create a page:
In the Application Navigator for
MyTutorialApplication, right-click the ViewController project, then choose New.
In the New Gallery, under Web Tier, choose JSF.
Under Items, choose JSF Page, then click OK (Figure 3-13).
Figure 3-13 Choosing JSF Page from the New Gallery
In the Create JSF Page dialog, in the Name field, enter
Select the Create as XML Document (*.jspx) checkbox.
Set up an initial layout for our page. WebCenter Framework includes a few "quick start" layouts that help you get started with creating a page layout. You can use these layouts when you begin creating your own applications, or create your own layout from the beginning. In this Tutorial, you will use a quick start layout.
Under Initial Page Layout and Content, select Quick Start Layout, then click Browse (Figure 3-14).
Figure 3-14 Create JSF Page Dialog
Under Categories, select One Column.
Under Types, select the second type.
Under Layouts, select the second layout. The Component Gallery should look like Figure 3-15.
Figure 3-15 Selecting an Initial Layout
Click OK, then click OK again.
JDeveloper finishes the wizard and displays your page in the Application Navigator (Figure 3-16).
Figure 3-16 MyPage in the Application Navigator
To the right of the Application Navigator, notice that your page displays in the Visual Editor (the large area between the Application Navigator and the Component and Resource Palettes) in the Design view (notice the Design tab is highlighted at the bottom of the view), as shown in Figure 3-17.
Figure 3-17 Design tab
Below the Application Navigator, notice the Structure window for your page. This view shows all the elements of your page in a hierarchical view. Just below that Structure tab, notice the pushpin icon (Figure 3-18).
Figure 3-18 Pushpin in the Structure Window
Clicking this icon toggles the behavior of the Structure window -- if it is pressed, then the Structure window displays the current view no matter where you click in Oracle JDeveloper. If it is not pressed, the Structure window updates according to where you click in JDeveloper.
You can expand the nodes in this view to see the various components that were automatically added to your page, since you chose to use the Quick Start Layout. Notice the Panel Splitter and Panel Splitter facets under
f:view, for example (Figure 3-19).
Figure 3-19 Structure Window for MyPage.jspx
Note:You can alternatively change to the Source view of the page. For the purposes of the Tutorial, using the Structure window enables you to see clearly where you've added a new component.
For more information on creating pages using Oracle WebCenter Framework, see Chapter 3, "Preparing Your Development Environment" in Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
Now that we have created our application and a JSF page, we can adjust the layout of our page and add Oracle Composer to our page to enable users to customize the page at runtime.
Selecting the Quick Start Layout when we created the page gave us a few "starter" layout components, specifically the Panel Splitter, which provides the basic framework of your page. In this step, you will enhance the layout and create a structure for the header section where you can add content, such as a corporate logo. You will learn about using the Structure window to tightly control the layout components on your page, as well as using components on the Component Palette.
To add layout components to the page:
In the Structure window, select the Panel Splitter, which is listed as
af:panelSplitter - vertical. You'll notice that the Property Inspector for this component displays to the right and below the Component Palette (Figure 3-20). The contents of the Property Inspector update depending on your focus in Oracle JDeveloper. Similar to the Structure window, you can use the pushpin icon in the Property Inspector to freeze the view according to the currently selected component.
Note:You can always view the Property Inspector for a component by right-clicking the component, then choosing Go To Properties from the context menu.
Figure 3-20 Property Inspector for the Panel Splitter
In the Property Inspector, under Common, locate the SplitterPosition property, and change the value from
85 (Figure 3-21). Clicking elsewhere in JDeveloper sets the property.
Figure 3-21 Setting the SplitterPosition Property
In the Structure window, expand the Panel Splitter. Notice that it contains two facets. In the next step, we will drop an ADF Faces component onto the
Add an ADF Faces layout component to our page to control how the content will display.
In the Component Palette, choose ADF Faces from the list. If the Component Palette is not currently displaying, you can show it by choosing Component Palette from the View menu.
Note:The Component Palette is context sensitive. That is, the contents of the Component Palette update according to the focus of your view in Oracle JDeveloper. As you're going through this Tutorial, if you suddenly "lose" components in the Component Palette or do not see the components described, try ensuring that you have the correct page or panel selected.
Under Layout, scroll down to Panel Stretch Layout, select it (Figure 3-22), and drag and drop it onto the
first facet in the Structure window.
Figure 3-22 Panel Stretch Layout in the Component Palette
Figure 3-23 shows the Panel Stretch Layout in the Structure window.
Figure 3-23 Panel Stretch Layout in the Structure Window
When you drop the Panel Stretch Layout component, you'll notice that the Property Inspector now displays the properties for this component(Figure 3-24).
Figure 3-24 Properties of the Panel Stretch Layout
Set the following properties in the Property Inspector, as shown in Figure 3-25:
Figure 3-25 Property Inspector for the Panel Stretch Layout with Updated Values
Next, add a logo to the header of the page, in the
start facet of the Panel Stretch Layout. In the Structure window, expand the Panel Stretch Layout you just added so that you can see the different facets (Figure 3-26), then select the
Figure 3-26 Panel Stretch Layout Facets
Notice how the corresponding facet is highlighted in the Design view (Figure 3-27). This is where we will add the logo image.
Figure 3-27 Start Facet in the Design View
The logo we will add is an image file we added to our application in Step 2: Add the Resource Files to the Application. In the Application Navigator, under ViewController, then Web Content, open the images folder.
Drag and drop logo.png onto the
start facet in the Design view of your page. When you drop the image, choose ADF Faces Image from the context menu (Figure 3-28).
Figure 3-28 Choosing ADF Faces Image from the Context Menu
The logo displays on your page, as shown in Figure 3-29.
Figure 3-29 Logo Image on Page in the Start Facet
Also notice that the image now displays in the Structure window, as shown in Figure 3-30.
Figure 3-30 Logo Image in the Structure Window
Now, you can finish the layout of the header. In the Design view, notice the
end facet (Figure 3-31) that displays to the right of the logo.
Figure 3-31 End Facet in the Design View
From the Component Palette, drag and drop the Panel Group Layout ADF Faces component onto this facet. You can see this now either in the Design view or, more easily in the Structure window (Figure 3-32).
Figure 3-32 Panel Group Layout in the End Facet
While the Panel Group Layout is selected, in the Property Inspector, under Appearance, change the Halign property to end. This changes the alignment of the components you will add to this layout component.
Change the Layout property to vertical (Figure 3-33).
Figure 3-33 Changing the Properties of the Panel Group Layout
For the purposes of this Tutorial, let's add a Status Indicator. The Status Indicator keeps us informed of the application's activity during runtime. For example, if you click a link, the Status Indicator will let you know the application is accessing the target of that link.
Ensure that the MyPage.jspx tab is displaying in the Design view.
In the Component Palette, choose ADF Faces from the list to display the ADF Faces components.
Under Common Components, scroll down the list and locate Status Indicator, then select it (Figure 3-34).
Figure 3-34 Status Indicator in the Component Palette
Drag and drop the Status Indicator onto the Panel Group Layout in the
end facet, as shown in Figure 3-35.
Figure 3-35 Status Indicator on the Panel Group Layout
Let us examine how the page looks at runtime. Right-click the page in the Design view, then choose Run. The page containing the logo and status indicator displays in your browser, as you can see in Figure 3-36.
Figure 3-36 MyPage with Logo and Status Indicator at Runtime
Return to JDeveloper.
Now that we have set up the initial header for our page, we will add Oracle Composer so that we can customize our page at runtime.
In traditional Java EE applications, if you wanted to edit pages (for example, add content, edit security definitions, and so on), you had to make these changes in Oracle JDeveloper, which is the application design time, and then redeploy the updated application to the production environment. With Oracle Composer, you and your application users can now edit your pages at runtime and see the results of your modifications immediately. Using Oracle Composer, you can give users the ability to move objects around on their page, hide or show content, as well add new content to the page.
In this step, we will add a few features that Oracle Composer offers. For a more in-depth description of Oracle Composer, however, see the chapters in Part II, "Using, Extending, and Customizing Your Application with Oracle Composer" in Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
To add Oracle Composer to the page:
First, add a Change Mode Link to the page. This link will enable runtime users of your application to switch between viewing the page and editing it using Oracle Composer.
In the Component Palette, choose Oracle Composer from the list at the top. In the previous step, you chose ADF Faces from this list, but let's switch views so we can see Oracle Composer's components.
Under Common Components, drag and drop the Change Mode Link component onto the Panel Group Layout in the Structure window. Adding this component will let you switch back and forth between the Edit mode and the View mode of your page at runtime. Figure 3-37 shows the Change Mode Link in the Component Palette.
Note:You can adjust the display of the Component Palette to see all of the options. You can do so by clicking and dragging the bars (such as the Layout bar) up and down to view the component names.
Figure 3-37 Change Mode Link in the Component Palette
If necessary, you can move the link above the Status Indicator by dragging it in the Structure window (Figure 3-38).
Figure 3-38 Change Mode Link in the Structure Window
When you add security to your application, as you will in the subsequent Chapter 4, "Adding Security to Your Application,"you can determine which users can edit this page, thus disabling the Change Mode Link you just added. You can adjust the attributes of this link to hide Change Mode Link from users who do not have privileges to edit the page.
To hide the Change Mode Link from users without Edit privileges, select the link in the Structure Window, then find the Rendered property in the Property Inspector under the Common category, as shown in Figure 3-39.
Figure 3-39 Rendered Property in the Change Mode Link Property Inspector
You can use the Expression Builder to specify how you want components to display in your application. Alternatively, if you are more comfortable coding, you can go to the Source view of the page, then manually enter the code.
To the right of the Rendered property, click the down arrow, then choose Expression Builder from the context menu.
In the Expression Builder, navigate to JSF Managed Beans, composerContext, inEditMode, securityContext, then click editAuthorized. You'll notice that doing so updates the Expression field at the top of the dialog (Figure 3-40). Example 3-1 shows the code you just created, which you can alternatively copy and paste into the Expression field.
Figure 3-40 Expression Builder with the Values Filled In
Click OK to accept the expression for the Rendered property. Until you implement security in your application, the value of this property does not affect the display of the Change Mode Link.
Add a Spacer component between the Change Mode Link and Status Indicator components. From the Component Palette, under ADF Faces, expand Layout.
Drag and drop a Spacer component onto the Structure window between the Change Mode Link and Status Indicator, as shown in Figure 3-41.
Figure 3-41 Adding a Spacer Component
Add a Page Customizable component to the layout. The Page Customizable, which is an Oracle Composer component, adds the runtime customization capabilities to the page.
In the Component Palette, choose Oracle Composer from the list.
Figure 3-42 Page Customizable in the Component Palette
Figure 3-43 Page Customizable in the Second Facet
In the Structure window, expand the Page Customizable, then delete the Panel Customizable since we do not need it (Figure 3-44). You can delete it by selecting it, then pressing your Delete key.
Figure 3-44 Deleting the Panel Customizable
Expand the Page Customizable facets node to view the list of components you added. One of these components is a status indicator. This status indicator only displays once you are in Composer at runtime. As you will see in the next step, "Step 6: Customize the Page at Runtime Using Oracle Composer", you will see two status indicators: one that you added earlier in this chapter, and another that displays only once you enter Edit mode at runtime in your application.
To remove this new status indicator, select the Page Customizable in the Structure Window.
In the Property Inspector for the Page Customizable, expand the Other node, then set the ToolbarLayout property to the following:
message stretch menu button
Figure 3-45 Removing the Second Status Indicator from the Page Customizable
Let's continue to add layout components to the page. In the Component Palette, from the ADF Faces list, drag and drop a Panel Group Layout component onto the Page Customizable component, then set the Layout property to scroll. Doing so enables a scrollbar in this area of the layout.
Figure 3-46 Panel Group Layout
Now, we will add a Layout Customizable to our page to create a layout for this region. In the subsequent chapters, we will add services and portlets to this area. From the Component Palette, under Oracle Composer, drag and drop a Layout Customizable onto the Panel Group Layout in the Structure window (Figure 3-47).
Figure 3-47 Layout Customizable in the Page Customizable
While the Layout Customizable is selected, in the Property Inspector, under Common, set the Type property to twoColumnTop (Figure 3-48).
Figure 3-48 Setting the Layout Customizable Properties
Now that you have added a few Oracle Composer components to our page, run the page and check out some of its features at runtime.
Right-click MyPage in the Design view, then choose Run from the context menu to view your page at runtime (Figure 3-49).
Figure 3-49 MyPage at Runtime with the Change Mode (Edit) Link
For more information on adding Oracle Composer to your application, see the chapters in Part II, "Using, Extending, and Customizing Your Application with Oracle Composer" in Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
We will use Oracle Composer in the application at runtime in the next step.
After you add Oracle Composer to a page at design time (in JDeveloper), you can run your page and customize the page at runtime (in a web browser). Your application users can also customize their pages at runtime -- this way, you do not have to go back to JDeveloper every time you want to modify the appearance of your application.
In this step, we will test a few features that Oracle Composer offers. Later in the Tutorial, after you implement security and add a few features to your application, you will test the application at runtime again for a more in-depth look at personalizing your application.
While MyPage displays in your browser, you'll notice an Edit link above the Status Indicator. Click Edit to see how the page looks in Edit mode (Figure 3-50).
Figure 3-50 Edit Mode of MyPage
Take a quick look at what you can do in Edit mode.
In the top left horizontal region, click Add Content to view the runtime catalog. Here, you can click ADF Faces Components to see the different ADF Faces Components you can add at runtime (Figure 3-51).
Figure 3-51 Adding Content at Runtime
Add a Text object to see how it looks. In the Catalog, next to Text, click Add, then click Close. A text box now displays in the region, as shown in Figure 3-52.
Figure 3-52 Text Box in the Edit Mode at Runtime
In the upper right corner of the region, click Edit Text to switch to the Rich Text Editor.
Place your cursor in the text box and enter some sample text. You can play around with the different functions in the toolbar, as well, such as changing the text to bold or switching the font, as shown in Figure 3-53.
Figure 3-53 Entering and Modifying Text in the Rich Text Editor at Runtime
When you are finished, click Done Editing.
You can change the overall layout of your page by clicking Change Layout, then choosing a layout option (Figure 3-54).
Figure 3-54 Changing the Layout at Runtime
Try selecting a layout option, such as the three column layout. The page automatically refreshes with your changes, as you can see in Figure 3-55.
Figure 3-55 MyPage in a Three Column Layout at Runtime
You can also change the layout of each of the component boxes by clicking the pencil icon in the upper right corner of the box (Figure 3-56).
Figure 3-56 Component Properties: Box
In the Component Properties for the layout box, you can change the layout of the box, the background color, and so on. Click Cancel to exit the Properties panel.
You can perform several other tasks at runtime, as well. For example:
Drag and drop components from one region to another. Hover your mouse over the text box, and while you see the crosshairs, click and drag the text box from one region to another on the page.
Delete components. In the upper right corner of the box, click the X to delete the component.
Return to Oracle JDeveloper.
Notice that the changes you made, for example the sample text, does not display in your Design view. Modifications that you or your application users make at runtime in Oracle Composer are stored behind the scenes, which means that the changes you make do not affect the source of your application.
Although your application view is not affected by runtime modifications, the customizations made at runtime are stored in the MDS (Metadata Services). So, while you are developing an application, it is good practice to clear out these changes.
In the Application Navigator, next to MyTutorialApplication (in the list), click the Application Menu icon.
Figure 3-57 Application Menu
From the context menu, choose Application Properties....
In the Application Properties dialog, expand the Run node in the left pane, then select MDS.
In the right pane, under Run: MDS, select Delete customizations before each run (Figure 3-58). Doing so clears the changes you made when you entered Edit mode at runtime the next time you run the application. Other changes you make at runtime (for example, in the services you add in Chapter 5, "Adding Oracle WebCenter Services to Your Application") are not stored in the MDS, and thus this option does not clear those change every time you run the application.
Figure 3-58 Application Properties Dialog
You can learn more about Oracle Composer and Oracle Metadata Services in Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
Now that we've created a custom WebCenter application added the resource files to your application, built a customizable JSF page, and taken a quick tour of Oracle Composer at runtime, you can add security to your application in Chapter 4, "Adding Security to Your Application."