1 Developer's Quick Start Guide

As a developer, if you are preparing to build a WebCenter Portal application for the first time, you need a good roadmap that shows you where to start and helps guide your initial experience. This chapter provides guidance, best practices, and tips for WebCenter application developers setting up their development environment for the first time.

Tip:

If you are just getting started, we recommend that you look at Section 1.1, "WebCenter Portal Developer's FAQ" first.

This chapter includes the following sections:

1.1 WebCenter Portal Developer's FAQ

Table 1-1 addresses basic questions to help you get started with WebCenter Portal development.

Tip:

Before you begin to design and build a WebCenter Portal application, we recommend that you read Chapter 8, "Understanding WebCenter Portal Applications." This chapter presents an overview of the portal framework, and provides tips and links to more detailed information.

Table 1-1 WebCenter Portal Developer's FAQ

Question Answer

What software do I need to install before getting started?

At a minimum, you need JDeveloper and the WebCenter Extension bundle (a JDeveloper add-in that includes WebCenter functionality). Typical portal environments also include database, content repository, and search engine installations. See Section 1.2, "Installing Required Software."

How do I set up source control for my team?

JDeveloper can integrate with a variety of source control systems. See Section 1.3, "Preparing for Team Development."

What can I do to increase my team's productivity?

The best way to improve your team's productivity is by enabling iterative development. With iterative development enabled, you can see portal file changes updated in runtime by simply refreshing the browser. See Section 1.5, "Preparing for Iterative Development."

How do I create a new portal application?

WebCenter provides an out-of-the-box template that creates a pre-configured portal application for you. The basic portal application includes all of the features you need to get started including a default set of pages, out-of-the-box page templates, and navigation. See Section 1.4, "Creating a New WebCenter Portal Application."

The default portal application includes files and features I do not intend to use. Can I remove them?

Yes, you can add and remove portal application components. For more information, see Section 6.1, "Manually Configuring a WebCenter Application With Technology Scopes."

How do I make database and content repository connections?

JDeveloper provides a connection wizard that lets you create these kinds of connections. These connections seamlessly integrate with certain components that you may use in a portal, like the Content Presenter task flow. See Chapter 26, "Configuring Content Repository Connections."

I'd like to create a highly customized navigation UI for my portal. Is that possible?

Yes, you can control all aspects of how the navigation UI is rendered using the APIs provided by WebCenter. A popular technique is to use EL to customize how the navigation UI is rendered. For example, you can hide certain links based on the user's role or change the look and feel of a link based on specified criteria. For more information, see Chapter 13, "Visualizing Your Portal Navigation."

How is portal security configured by default?

By default, a WebCenter Portal application is configured with ADF security. A default username and password (weblogic/weblogic1) are created automatically for you, and you can use this username/password combination for testing purposes immediately. See also Chapter 67, "Securing Your WebCenter Portal Application."

How do I customize the way content is displayed in my portal?

One common technique is to use the Content Presenter task flow. Content Presenter lets you add content to a page and customize the way the content is displayed using templates. For more information, see Chapter 25, "Introduction to Integrating and Publishing Content."

How do I create a consistent layout for the pages in my portal?

The page template feature allows you to create a layout that any page in your portal can share. In addition to the basic page layout, you can also add features like navigation user interfaces to the template. See Section 1.7, "Planning the Portal Layout."

There are so many ADF components. How do I figure out which ones to use?

WebCenter provides the WebCenter Portal Catalog. This catalog includes a collection of components commonly used for building portals. For more information, see Chapter 15, "Creating and Managing Resource Catalogs."

I'd like to change the default skin. How do I do that?

A skin is a style sheet that defines the look of your portal. WebCenter provides a portal skin that you can conveniently edit in JDeveloper. For more information, see Section 1.8, "Working with Skins."

Can developers modify or add new portal features that have been deployed into production?

WebCenter provides a solution for round-trip development. See Section 1.9, "Preparing for Round-Trip Development."

What do I need to know about moving the portal from the development environment to the testing, staging, and production environments?

The portal life cycle describes the path a portal takes from development and testing environments to a staging environment and, ultimately, a production environment. For detailed information on managing the life cycle, see Chapter 9, "Understanding the Portal Life Cycle."

Where can I get more background information on developing WebCenter portals?

We recommend that you review Chapter 8, "Understanding WebCenter Portal Applications." This chapter presents an overview of the portal framework, and provides tips and links to more detailed information.


1.2 Installing Required Software

A typical development environment includes these components:

See also the Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

1.3 Preparing for Team Development

It's important to consider the overall team development environment. To be useful, a team development environment must be configured to allow developers to share common resources, like databases, content repositories, and source code. A well-planned team environment allows you to quickly and consistently develop, build, and update your WebCenter applications.

Tip:

Typically, one member of the development team creates a new WebCenter Portal application and checks it in to the source code repository. You can create any required database or content repository connections and check those in as well.

For more detailed information on team development topics like source control and file sharing, see Chapter 4, "Working Productively in Teams."

1.4 Creating a New WebCenter Portal Application

WebCenter provides a wizard for creating new portal applications. The wizard uses an out-of-the-box Portal Application template that ensures the appropriate application components are included.

After the portal application is created, you can then configure database and content repository connections and check those in to the source control system as well.

If you wish, you can manually configure the WebCenter Portal application. For example, you might decide to remove some components from the portal application if you know you will never need them.

For detailed information on creating, extending, and modifying portal applications, see Chapter 5, "Creating WebCenter Applications." For more information on managing connections, see Section 1.6, "Creating Application Resource Connections."

1.5 Preparing for Iterative Development

This section discusses WebCenter's iterative development feature.

1.5.1 What Is Iterative Development?

Iterative development lets you make changes to your WebCenter Portal application while it is running on the Integrated WebLogic Server and immediately see the effect of those changes simply by refreshing the current page in your browser. The iterative development feature works by disabling certain optimization features. Iterative development allows developers to work more quickly and efficiently when building a portal application.

For example, iterative development lets you see changes to these components almost instantly upon a browser refresh:

  • page definitions

  • navigation model

  • page hierarchy

  • existing JSPX files

  • page templates

  • resource catalog

  • addition of task flows to pages

  • addition of portlets to pages

The following kinds of operations are not supported by iterative development. These operations require you to re-run the application:

  • creating any new file explicitly (JSPX, page definition, page hierarchy, and so on)

  • creating a new file implicitly. For instance, when you add a sub-page to a node in the page hierarchy, a new *pages.xml file is created.

  • editing any configuration file, like web.xml or adfc-config.xml.

1.5.2 How Does Iterative Development Work?

Iterative development works by turning off certain MDS and runtime layer caches. Because these performance optimization features are disabled, you might notice some slower performance when running your application in a development environment.

Note:

When an application is deployed to the Integrated WebLogic Server, the org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION flag is automatically set to true in the web.xml file on the server. This setting causes the server to automatically check the modification time of your JSP and skinning CSS files, and discard saved state when they change. This configuration occurs whether or not the iterative development feature is enabled.

When iterative development is enabled, the following changes to application configuration occur:

  • The MDS Cache size is set to 0. This setting causes all metadata files to be re-loaded on each request.

  • The Navigation Model cache is invalidated on each request.

For skin development, you can set the application to use uncompressed skins. This setting is not the default and should only be used in a development environment. You can update web.xml to enable this functionality with the following context parameter:

<context-param>
    <param-name>org.apache.myfaces.trinidadinternal.DISABLE_CONTENT_COMPRESSION</param-name>
    <param-value>true</param-value>
</context-param>

Note:

When consuming Oracle JSF Portlet Bridge Portlets in your application, ADF attempts to share the skin between the consumer and producer. Therefore, if you are disabling compression on the consumer, you should also do that on the producer. Otherwise, the producer will not generate the correct code to match the uncompressed IDs generated by the consumer. See also Chapter 58, "Creating Portlets with the Oracle JSF Portlet Bridge."

Note that if you edit the base definition (source) of a resource at runtime while the portal is running in the Integrated WebLogic Server, iterative development will not work as expected: if you edit the resource file in JDeveloper and save, you will not see the change when the running page is refreshed. The reason is because when a resource is edited at runtime at the base document level in the Integrated WebLogic Server, a copy of the resource's base document is created in the MDS write directory. From that point forward, this copied version will be used, and the version of the base document in JDeveloper will be ignored. If you run into this issue and want to pick up changes made to the file in JDeveloper, you will need to re-run the application after taking the following steps:

  1. In the Application Navigator, click the Application Menu icon next to your application's name and choose Application Properties.

  2. In the Application Properties dialog, expand the Run node in the left pane, then select MDS.

  3. In the right pane, select Delete customizations before each run. Doing so clears the MDS of any runtime customizations every time the application is run.

  4. Click OK.

1.5.3 Enabling Iterative Development

This section explains how to enable iterative development, if it has been disabled.

Note:

The iterative development feature is enabled by default when you create a new WebCenter Portal application.
  1. Select Application Properties from the Application menu.

  2. Along the left side of the Application Properties dialog, expand the Run node.

  3. Select WebCenter.

  4. Select Enable Iterative Development, as shown in Figure 1-1.

    Figure 1-1 Enabling Iterative Development

    Description of Figure 1-1 follows
    Description of "Figure 1-1 Enabling Iterative Development"

  5. Click OK.

1.5.4 Turning Off Iterative Development

This section explains how to turn off iterative development. Iterative development is enabled by default; however, it's a good practice to turn off iterative development for testing purposes before you deploy your application to a production server.

  1. Select Application Properties from the Application menu.

  2. Along the left side of the Application Properties dialog, expand the Run node.

  3. Select WebCenter.

  4. Unselect Enable Iterative Development.

  5. Click OK.

1.6 Creating Application Resource Connections

Connections allow the portal application to access external data and services. For example, if you wish to use the Content Presenter task flow to display content from an Oracle Content Server repository, you need to configure a connection to the repository. If you intend to consume portlets from a portlet producer, you need to configure the producer connection.

Tip:

A good practice is to create and test your connections once and check them into your source control system. Then, other developers on your team can check out the connections and use them. This technique also allows your team to keep in sync whenever a connection changes.

This section describes the different ways to access the wizards for creating new connections. See also Section 1.6.3, "Where Can I Learn More About Connections?."

1.6.1 Where Are Connections Located?

Depending on how you invoke a wizard to create a connection, connections are placed in one of the following locations:

  • Under Application Resources in the Application Navigator

    Connections created here can be used in the current application only. This is the most common way to create a repository connection.

    For certain services, you can drag and drop a connection from Application Resources onto a page to create different types of task flow regions. To learn more, refer to the individual WebCenter service chapters.

  • Under IDE Connections in the Resource Palette

    Connections created here can be reused across WebCenter applications. To use these connections in an application, you just have to drag and drop the connection from the Resource Palette onto the Connections node in that application.

1.6.2 How Do I Access the Connection Wizards?

To access a connection wizard from the New Gallery:

  1. From the File menu, choose New.

  2. In the New Gallery dialog, expand Connections, select the type of connection you want to create, and click OK.

    Depending on your selection, the Create <Connection_Type> Connection dialog opens.

  3. The Create Connection in option is set to Application Resources by default.

    You can select IDE Connections to create a connection in the Resource Palette.

To access a connection wizard from the Application Navigator:

  1. Right-click the Connections node under Application Resources and select New Connection, then select the connection type from the context menu.

  2. Depending on your selection, the Create <Connection_Type> Connection dialog or wizard opens.

    The Create Connection in option is set to Application Resources by default.

To access a connection wizard from the Resource Palette

  1. Click the New icon in the Resource Palette, select New Connection, then select the connection type from the context menu.

  2. Depending on your selection, the Create <Connection_Type> Connection dialog or wizard opens.

    The Create Connection in option is set to IDE Connections by default.

1.7 Planning the Portal Layout

You can use page templates to control the layout of your portal. A page template is a JSPX file that specifies the look and feel of your portal's pages. The template defines header, footer, content, and navigation regions within the page. You can apply the template to any number of pages, resulting in a consistent look and feel.

WebCenter provides several default page templates to help you get started. For more information, see Chapter 8, "Understanding Pages, Page Templates, and the Portal Page Hierarchy."

1.8 Working with Skins

A skin is a CSS file that defines the overall look of a portal, including color schemes, fonts, and the display characteristics of ADF Faces components. WebCenter also provides a portal skin file that you can conveniently edit in JDeveloper. This file lets you override settings in the default skin. Just open the file, uncomment any components you wish to modify, and save the file when you are finished making changes. For details, see Chapter 14, "Creating and Managing Skins."

1.9 Preparing for Round-Trip Development

Round-trip development refers to features and techniques that allow you to retrieve resources from a deployed, runtime portal back to JDeveloper for maintenance or enhancement. After modifying a resource in JDeveloper, you can use the Resource Manager to upload the resource back to the deployed portal. WebCenter's round-trip development features provide a simple, convenient way to modify portal resources without redeploying the entire application.

For more information on round-trip development, see Section 16.3, "Enabling Runtime Administration of Your Portal" and Section 16.4, "Enabling Round-Trip Development of Resources."

1.10 What Configuration Files Should I Know About?

A number of automatically generated configuration files are placed under the WEB-INF and Page Flows folders of a portal project when you create a WebCenter Portal application.

Tip:

For a complete listing of portal configuration files, see Appendix H, "Manually Migrating a WebCenter Portal Application."

This section briefly describes these file:

1.10.1 The WebCenter Portal Application Template Default web.xml File

Part of WebCenter Portal application configuration is determined by the content of its J2EE application deployment descriptor file: web.xml. The web.xml file defines many application settings that are required by the application server.

Note:

Rather than being specified in web.xml, the context root path is assigned when the application is deployed.

Typical runtime settings include initialization parameters, custom tag library location, and security settings. Depending on the technology you use, other settings may be added to web.xml as appropriate.

Note:

For standard Java EE files like web.xml, there is usually a counterpart Oracle-specific file with additional Oracle-specific options, for example, weblogic.xml.

The web.xml file is located in the /public_html/WEB-INF directory relative to the project in your WebCenter Portal application.

When you first create your WebCenter application, configuration settings for JSF servlet and mapping and for resource servlet and mapping are automatically added to the starter web.xml file.

The Faces Servlet entry inside <servlet></servlet> tags provides information about the JSF servlet, javax.faces.webapp.FacesServlet. This servlet manages the request processing life cycle for web applications that use JSF to construct the user interface. The configuration setting maps the JSF servlet to a symbolic name, Faces Servlet.

The resources entry inside <servlet></servlet> tags provides information about the ADF resource servlet used to serve up web application resources (images, style sheets, JavaScript libraries) by delegating to a ResourceLoader.

The <servlet-mapping></servlet-mapping> tags map the URL pattern to a servlet's symbolic name. You can use either a path prefix or an extension suffix pattern.

By default, JDeveloper uses the path prefix /faces/*. That is, when a URL, for example, http://localhost:8080/SRDemo/faces/index.jsp, is issued, the URL activates the JSF servlet, which strips off the faces prefix and loads the file /SRDemo/index.jsp.

Note:

If you prefer to use the extension jsf for web pages instead of jsp or jspx, then you must set the javax.faces.DEFAULT_SUFFIX context parameter to jsf, for example:
<context-param>
  <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
  <param-value>.jsf</param-value>
</context-param>

Then add a servlet mapping in web.xml that invokes the JSP servlet for files with the extension jsf.

To edit web.xml in Oracle JDeveloper, right-click web.xml in the Application Navigator and choose Open from the context menu. This opens web.xml in the Web Application Deployment Descriptor editor, in Overview mode. If you are familiar with configuration element names, then you can also use the XML editor to modify web.xml.

For information about the configuration elements you can use in the web.xml file, see "Oracle ADF XML Files" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

1.10.2 The WebCenter Portal Application Template Default faces-config.xml File

Use the faces-config.xml file to register a WebCenter Portal application's resources, such as custom validators and managed beans, and to define all page-to-page navigation rules. The default name of this file is faces-config.xml, though this naming convention is not required.

Depending on how resources are packaged, an application can have one or multiple faces-config.xml files. For example, you can create individual JSF configuration files for:

  • Different areas of your application

  • Each library containing custom components or renderers

For more information about creating multiple faces-config.xml files, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Example 1-1 illustrates the default faces-config.xml file provided through the WebCenter Portal Application template. This file is located in the /public_html/WEB-INF directory relative to the project in your WebCenter Portal application.

Example 1-1 Default faces-config.xml File Provided Through the WebCenter Portal Application Template

<?xml version="1.0" encoding="US-ASCII"?>
<faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee">
  <application>
    <default-render-kit-id>oracle.adf.rich</default-render-kit-id>
    <view-handler>oracle.webcenter.portalframework.sitestructure.handler.CustomViewHandler
    </view-handler>
  </application>
  <managed-bean>
    <managed-bean-name>preferenceBean</managed-bean-name>
    <managed-bean-class>oracle.webcenter.portalframework.sitestructure.PreferencesBean
    </managed-bean-class>
    <managed-bean-scope>application</managed-bean-scope>
  </managed-bean>
</faces-config>

To edit the faces-config.xml file, double-click it in the Application Navigator. By default, the file is opened in the Editor window in Diagram mode, as indicated by the active Diagram tab at the bottom of the Editor window. When creating or modifying JSF navigation rules, Diagram mode enables you to visually create and manage page flows. For more information, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

To create or modify configuration elements other than navigation rules, use the Editor's Overview mode. Enter this mode by clicking the Overview tab at the bottom of the Editor window.

JSF allows multiple <application> elements in a single faces-config.xml file. When you use the JSF Configuration Editor, you can edit only the first instance. For any other <application> elements, you must edit the file directly using the XML editor. To use the XML editor, open the faces-config.xml file and go to the Source tab in the Editor window.

For reference information about the configuration elements you can use in the faces-config.xml file, see "ADF Faces Configuration" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

1.10.3 The WebCenter Application Template Default trinidad-config.xml File

The default trinidad-config.xml file, available when you create an application, contains information about the application skin family. Additionally, it can contain information about the level of page accessibility support, page animation, time zone, enhanced debugging output, and the URL for Oracle Help for the Web (OHW). Like faces-config.xml, the trinidad-config.xml file has a simple XML structure that enables you to define element properties using JSF Expression Language (EL) or static values.

Example 1-2 illustrates the default trinidad-config.xml file provided through the WebCenter Portal Application template. This file is located in the /public_html/WEB-INF directory relative to the project in your WebCenter Portal application.

Example 1-2 Default trinidad-config.xml File Provided Through the WebCenter Application Template

<?xml version="1.0" encoding="US-ASCII"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
 
  <skin-family>fusion</skin-family>
 
</trinidad-config>

In addition to the skin family, you can define the following application values in the trinidad-config.xml file:

  • Page animation

  • Level of page accessibility support

  • Time zone

  • Enhanced debugging output

  • Oracle Help for the Web (OHW) URL

For reference information about the trinidad-config.xml file, see "ADF Faces Configuration" in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

1.10.4 The WebCenter Application Template Default adfc-config.xml File

The adfc-config.xml file is the configuration file for an ADF unbounded task flow. This file contains metadata about the activities and control flows contained in the unbounded task flow. The default name for this file is adfc-config.xml, though this naming convention is not required.

If ADF Page Flow is specified as a Selected Technology on the Technology Scope page of the Project Properties dialog, a new adfc-config.xml source file is automatically created within the project. The adfc-config.xml file is the main source file for an unbounded task flow.

The adfc-config.xml file is located in the /public_html/WEB-INF directory relative to the project in your WebCenter Portal application.

Note:

If you do not plan to use task flows in your application, you can delete the adfc-config.xml file.

For more information about task flows and the adfc-config.xml file, see "Oracle ADF XML Files" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

1.11 Installing Database Schemas

Certain Oracle WebCenter components require schemas that must be installed in a supported database. For details, see Section 3.5, "Installing Database Schemas."