BEA Logo BEA WebLogic Portal Release 4.0

  BEA Home  |  Events  |  Solutions  |  Partners  |  Products  |  Services  |  Download  |  Developer Center  |  WebSUPPORT

   http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |   Glossary

 

   WebLogic Portal Documentation   |   Portals and Portlets   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Customizing Portals and Portlets

 

This topic begins with some basic developer tasks, and then introduces some more advanced developer-orientated concepts specific to the WebLogic Portal platform.

This topic includes the following sections:

 

Creating a New Portal Web Application

This section explains using a copy of the sample portal web application as a template to create your own portal web application. This task requires working with the native file system, the WebLogic Server Console, and the E-Business Control Center.

Copy and Rename the Web Application Files

  1. Within the native file system, navigate to the following directory: \\bea\wlportal4.0\applications\portal\

  2. Make a copy of the stockportal directory, placing it in the current directory.

  3. Make a copy of the webflow and pipeline information from the existing portal directories.

  4. After performing a Datasync in the E-Business Control Center, copy the user_account.wf from this directory: 
    \\bea\wlportal4.0\applications\portal\sampleportal-project\application-sync\webapps\sampleportal

    to this directory:

     
    \\bea\wlportal4.0\applications\portal\sampleportal-project\application-sync\webapps\myportal

  5. Rename this new directory after the new portal web application you want to create. In this example, the new directory is called myportal.

    The new, renamed directory now contains all the J2EE application elements required of a web application, as shown in Figure 5-1.

    Figure 5-1 The myportal Directory


     

  6. Copy the metadata files in Listing 5-1 to the following directory: 
    \bea\ebcc4.0\applications\portal\application-sync\webapps\myPortal\

    Listing 5-1 Metadata Files

     
    <BEA_HOME>\ebcc4.o\applications\portal\application-sync\webapps\stockportal\
     
    portlet2.wf
     
    \portlet3.wf
     
    \worldnews.wf

Deploy the Application in the WLP Server

  1. Start the WebLogic Portal server.

  2. Navigate to the Console: http://<hostname>:7501/console 
    username: system
     
    password: <password you entered to boot server>

  3. From the Console, navigate to the following directory: 
    Deployments > Applications > Portal

Configure a new Web Module

  1. Right click on Portal and select "Edit Application Descriptor"

  2. From the Web Server Console popup window, select WebModules

  3. Right click WebModules and select "Configure a New WebModule"

  4. From the Create a New WebModule Screen, enter the following information: 
    Module URI: myportal
     
    Context URI: myportal

  5. Click Create, then Apply

  6. Navigate back to the Root node, StockPortal

  7. With StockPortal node selected, click the Persist button

  8. Close this editor window.

Deploy the New Web Application

  1. Within WebLogic Console, navigate to the following directory: 
    Deployments > Applications > Portal

  2. Select Portal

  3. De-select the Deployed checkbox and click on Apply

  4. Re-check the Deployed checkbox and click on Apply

  5. Deployment will take several minutes. Once it has completed, refresh the browser

  6. The myportal web application should now appear in the following directory: 
    Deployments > Applications > Portal > myportal

Target the Application to Your Server

  1. Within WebLogic Console, navigate to the following directory: 
    Deployments > Applications > portal > myportal > Targets tab

  2. From the Targets tab, move portalserver to the Chosen listbox and click Apply.

The J2EE web application deployment is complete.

Edit Portal Metadata Using the EBCC

This process uses the E-Business Control Center to edit metadata on the J2EE portions of your new portal web application.

Open Existing Portal Application

  1. Start the E-Business Control Center and select File > Open Application

  2. Navigate to the following directory: 
    //EBCC4.0/applications/portal

  3. Open the portal application

Define a New Portlet

  1. From the bottom left-hand corner of the E-Business Control Center, select the Presentation tab

  2. Select the Portlet editor. A list of portlets should appear to the right

  3. From the File menu at the top of the E-Business Control Center, select File > New > Presentation > Portlet

  4. When the Portlet Editor appears, follow the rest of these instructions to reuse existing JSPs and image files for the new portlet.

  5. Locate the portlet3.wf in the PORTAL_HOME/applications/portal-project/application-sync/webapps/stockportal directory.

  6. Copy this file to the PORTAL_HOME/applications/portal-project/application-sync/webapps/myportal directory.

  7. Sync the new data.

  8. Define the Portlet as follows:

  9. Click on the dropmenu in the Webflow field and set this field to Portal3.

  10. Disable the Login Required Checkbox. (If this checkbox is not disabled, the user will be required to log in order to view the portlet.)

  11. Close the Portlet Editor Screen and save changes. Save the portlet with the following file name:

    MyPortlet

  12. The new portlet should appear in the list of portlets as MyPortlet.

Define a New Web Application

This task creates new metadata for the new portal web application.

  1. From the bottom left-hand corner of the E-Business Control Center, select the Presentation tab.

  2. Select the Portal editor. A list of portals should appear to the right.

  3. From the File menu at the top of the E-Business Control Center, select File > New > Portal Web Application, as shown in Figure 5-2.

  4. Enter the name myportal and click OK.

    Figure 5-2 Create a New Portal Web Application


     

Create a New Portal

This task edits the metadata for the new portal web application.

  1. From the File menu at the top of the E-Business Control Center, select File > New > Presentation > Portal

  2. When the Select Web Application dialog box appears, select the myportal web application and click OK

  3. The Portal Editor will appear to the right

  4. Expand the General tab and enter MyPortal in the Description field

  5. Enter the following URLs:

  6. From the Portal Webflow dropmenu, select the Webflow called "portal"

  7. From the Skins tab, move all available skins to the Selected Skins column

  8. From the Layouts tab, move twocolumn to the Selected Layouts column

  9. From the Portlets tab, move MyPortlet to the Selected Portlets Column

  10. From the UserProfiles tab, move StockPortal to the Selected User Profiles column, and close the General tab

  11. Expand the Pages tab and click Add

  12. In the Portal Page Name Field, enter MyPortalPage

  13. In the Default Image field, enter home.gif.

  14. Move the layout and the portlets into their respective Selected listboxes.

  15. Click OK. The new portal page should now appear in the Portal pages listbox in the E-Business Control Center.

  16. Close the Pages tab.

Set Defaults on New Portal

  1. Expand the Defaults tab, and select the Futurism skin.

  2. From the Default portal pages listbox, highlight MyPortalPage.

  3. From the Portlets listbox, highlight MyPortlet.

  4. From the Default Layout dropmenu, select TwoColumn.

  5. Click the Place Portlets button.

  6. The Page Layout screen appears.

  7. Enable the radio button in the second segment of the layout.

  8. Highlight MyPortlet and click Add.

  9. MyPortlet should now appear in the fourth segment of the layout.

  10. Click OK.

  11. Close the Defaults tab.

  12. Click the Close(X) icon at the top right of the Portal editor.

  13. From the "Portal is modified. Save it?" dialog box, click Yes.

  14. In the Save As dialog box, enter the text MyPortal.

  15. MyPortal and StockPortal should appear side-by-side in the E-Business Control Center list of portals.

Synchronize the Metadata Using the EBCC

Now that the metadata is edited, it must be moved to the server using a special Synchronization process.

Configure Connection Settings

The E-Business Control Center allows you to save different synchronization profiles as Connection Settings. This procedure shows how to configure one set.

  1. From the Tools menu of the E-Business Control Center, select Connection Settings

  2. From the Connection Settings popup window, navigate to the Connections tab and click the New button

  3. Enter the following information:

  4. From the Details menu click OK

  5. From, the Settings menu click OK

Synchronize Data

  1. From the Tools menu of the E-Business Control Center, select Synchronize

  2. In the login window that appears, enter the following credential:

    username: system

    password: <password you entered to boot server>

  3. Click on Connect

  4. When the Task Bar reaches 100% complete, click on Close

Modify Cookie Parameters in Deployment Descriptor

To prevent the new portal from using the generic cookie for authentication, take the following steps:

  1. Open the weblogic.xml for the newly created portal. This file is in the ...\wlportal4.0\applications\portal\myportal\WEB-INF directory.

  2. Make the following edit to the deployment descriptor:

    Listing 5-2 Editing Cookie Parameters for Deployment Descriptor

     
    Replace this:
     
    <session-param>
     
       <param-name>CookieName</param-name>
     
       <param-value>JSESSIONID_STOCKPORTAL</param-value>
     
    </session-param>
     
    <session-param>
     
       <param-name>CookiePath</param-name>
     
       <param-value>/stockportal</param-value>
     
    </session-param>
     
    with this:
     
    <session-param>
     
       <param-name>CookieName</param-name>
     
       <param-value>JSESSIONID_webapp name</param-value>
     
    </session-param>
     
    <session-param>
     
       <param-name>CookiePath</param-name>
     
       <param-value>/webapp directory name</param-value>
     
    </session-param>

Providing a unique pathname to which the browser sends cookies prevents other portals deployed in the same domain from using the same autologin cookies. After making this edit and re-starting WebLogic Portal, the new portal should use its own authentication cookie.

Verify Your Deployment

WebLogic Portal includes two ways to verify the deployment was successful - one is the obvious method of navigating to the URL and viewing the portal web application from the point of view of a Visitor. The other is to use the Data Repository Browser, shown below.

Verify Application Using Browser

You should see your newly-deployed portal web application if you navigate to

 
http://<hostname>:7501/myportal

Verify Data Synchronization Using Data Repository Browser

  1. With the WebLogic Portal running, navigate to the following URL: 
    http://<hostname>:7501/portalDataSync/index.html

  2. Enter the following credential:

    username: system

    password: <password you entered to boot server>

  3. Click the Data Repository Browser link.

  4. Click the Master Data Repository View link.

  5. Verify that the myportal web application is visible within the Items list.

  6. Verify that the newly created Portlet is visible.

  7. Examine the XML file.

 

Creating Your Own Portlet

This section outlines how to create a new portlet and position it inside an existing portal.

Define a New Portlet

  1. Start E-Business Control Center and open the portal application, as shown in Figure 5-1. The Default location is BEA_HOME\wlportal4.0\applications\portal-project.

  2. Select the Presentation tab at the bottom right corner of the E-Business Control Center.

  3. Click on Portlets, and then click on the Create button, as shown inFigure 5-3.

    Figure 5-3 Create New Portlet Button


     

  4. When the Portlet Editor window appears on the right, enter the values listed in Table 5-1.

  5. Click the Save button, shown in Figure 5-4, using the name TestPortlet when prompted.

    Table 5-1 New Portlet Settings

    Field Name

    Purpose

    Example Value

    Description

    Description of Portlet

    Test Portlet

    Content URL

    Default body JSP

    /portlets/test/portlet.jsp

    Header URL

    Default header JSP

    /portlets/test/header.jsp

    Alternate Header URL

    Used for Maximized state

    /portlets/test/altheader.jsp

    Footer URL

    Default footer JSP

    /portlets/test/footer.jsp

    Alternate Footer URL

    Used for Maximized state

    /portlets/test/altfooter.jsp

    Titlebar URL

    Default titlebar JSP*

    /framework/titlebar.jsp

    Banner URL

    Banner JSP

    /portlets/test/banner.jsp

    Icon URL

    Image for titlebar icon

    /portlets/test/images/icon.gif

    Edit URL

    Portlet editor JSP

    /portlets/test/edit.jsp

    Help URL

    Portlet help JSP

    /portlets/test/help/help.jsp

    Maximize URL

    Maximized body JSP

    /portlets/test/max.jsp

    Webflow

    Portlet Webflow

    None

    Editable

    Editor is available

    True

    Helpable

    Help is available

    True

    Login Required

    Only displayed if user logs in

    False

    Mandatory

    Portlet must appear

    False

    Floatable

    May be opened in separate window

    True

    Minimizable

    Portlet may be minimized

    True

    Maximizable

    Portlet may be maximized

    True

    Defaults minimized

    Appears minimized by default

    False

Note: The following clarifications apply to Table 5-1:

Place New Portlet into Existing Portal Definition

In order to see the new portlet, references to it need to be placed in the following sections of the portal definition:

General Setting for the Portal

  1. Select the Presentation tab at the bottom right corner of the E-Business Control Center.

  2. Click on Portals, and then double-click on StockPortal to open the editor.

  3. Click on the General pane to expand it and click on the Portlets tab.

  4. Move TestPortlet from the Available to the Selected column using the Add >> button.

  5. Click on OK and then close the General pane by clicking on it.

Specific Pages in the Portal

  1. Click on the Pages pane.

  2. Select the Home page and click on Edit.

  3. Move TestPortlet from the Available to the Selected column using the Add >> button.

  4. Click on OK and then close the Pages pane by clicking on it.

Default Settings for the Portal

  1. Click on the Defaults pane.

  2. Select the Home page from the list and click on Place Portlets at the bottom of the window.

  3. In the Place Portlets dialog, select the middle column.

  4. Click on Add to move the TestPortlet from the list on the left to the middle column.

  5. Click on OK and then close the Pages pane by clicking on it.

Deploy the New Portlet

The metadata for the new portlet has now been edited. Next, deploy the metadata as well as the J2EE application files.

Synchronize the Metadata to the Server

Use the E-Business Control Center to synchronize this metadata to the server. This section outlines the basic steps to perform this task. For detailed instructions on operating the E-Business Control Center, consult the Guide to Using the E-Business Control Center.

Note: Make sure that in your Synchronization Settings, the realm is set to weblogic, and that the application is set to portal.

Install the J2EE Application Files for New Portlet

At this point in the procedure, there is metadata on the server that defines a portal called myportal. Since it mostly reuses existing J2EE files, most parts of this new portal web application should already be visible, with one exception: The portlet we have defined and named TestPortlet has no J2EE application files yet.

For this example, we'll copy an existing portlet directory and alter the existing files to construct the TestPortlet.

  1. Navigate to the following directory: 
    BEA_HOME\wlportal4.0\applications\portal\stockportal\portlets

  2. Make a copy of the portlet1 directory and paste it into the portlets directory.

  3. Rename the directory test.

  4. Open the new directory: the filenames should match those defined in the EBCC for the TestPortlet.

Verify the Portlet is Deployed

Navigate to the following directory:

 
http://<host>:7501/stockportal/

The new test portlet should appear below the E-Docs portlet in the center column of the Home page of the sample portal.

Note: To make this new portlet available for authenticated visitors, the Group Portal attributes must be set so the portlet is available and visible to the user. The simplest way to do this is to use static personalization by setting entitlements on the portal to be available to any member of the group to which the user belongs. For instructions on setting entitlements, consult the section called "Setting Entitlements" in the Portal Administration Tools chapter.

Edit the Copied Portlet Files

Now that the JSPs are installed, and the metadata has been edited and deployed so that the framework can see your portlet, changing the content is a matter of editing the files that make up your portlet. The JSPs in this example are very simple, so you can edit them with something like Notepad. Also, notice that we're editing JSPs from within the server's native file system.

Note: While performing these exercises, leave your browser open to the stockportal page between editing the JSPs. When you re-save the edited portlet files, you can simply re-load the page using the same session.

Edit Static HTML

The JSP files that make up your new portlet include some simple HTML. Importantly, portlets do not need to be complete HTML documents. Open the portlet.jsp file and replace the "Portlet1" text with "This is the Test Portlet". Save the file and reload the stockportal in the browser. The portlet should be re-rendered and appear as shown in Figure 5-5.

Figure 5-5 Edited Portlet


 

About Scriptlets and JSP Tags

A JSP may contain static HTML, as demonstrated in the preceding slides, and dynamic logic in the form of scriptlets and JSP tags. This section introduces some scriptlet and JSP fundamentals for those who may not be familiar with the servlet model.

A scriptlet is a section of valid Java code typically used to process input and generate output for the JSP. In most cases this is display logic, because business logic is best handled by components such as EJBs.

The Java code in a scriptlet is processed by the JSP compiler to create the body of a servlet that will be called when the URL for this JSP is requested. Servlets are based on a request-response architecture that is ideally suited for handling HTTP requests such as those from HTML browsers.

The generated servlet is Java source code that will in turn be compiled. The resulting Java class file will be stored in a location by the server and loaded when the servlet is accessed. Errors may occur in three stages, including JSP compilation, Java compilation, and execution of the resulting servlet class. These errors may be displayed in the browser as part of the portlet body, the console where the server is running, or the server log files.

For more information on servlets and JSPs, consult the J2EE specification at http://java.sun.com/.

Using Java Scriptlets Within a Portlet

This section outlines how to insert some simple code into the portlet.jsp file that handles a variable called username, and will display it in the body of the portlet.

Note: For this example, open a new browser and navigate to the following URL:

 
http://<hostname>:7501/stockportal/

  1. In the native file system, navigate to the /portlets/test directory and open the portlet.jsp file in Notepad.

  2. Append the following snippet to the end of the file: 
    <%
     
     String userName = "";
     
     %>
     
    The user name is: <%= userName %>
     
    <br>
     
    <p>

  3. Save the file and re-load the portal in your browser.

  4. Notice that the phrase "The user name is:" appears in the window, but the userName object returns nothing. (In order to make use of this variable, this object must be populated with the current portlet visitor. Of course, if the visitor has not authenticated, we cannot return a username.)

  5. In the native file system, navigate to the /portlets/test directory and open the portlet.jsp file in Notepad.

  6. Replace the contents of the file with the code in Listing 5-3:

    Listing 5-3 Displaying the User Name

     
    <center>
     
    This is Our Test Portlet
     
    </center>
     
    <br>
     
    <hr>
     
    Now try some simple Java scriptlets:
     
    <br>
     
    <br>
     
    <%
     
    // Create a new String variable and set the value to an empty string.
     
      String userName = "";
     
    /*
     
    To get the actual user name, first get the java.security.Principal object from the javax.servlet.http.HttpServletRequest object using the getUserPrincipal() method.  The request object is available to the JSP directly.  For the Principal object, use the full package name.
     
    */
     
    java.security.Principal principal = request.getUserPrincipal();
     
    /*
     
    If the principal object is null then the user has not logged in. For this example, ignore the not-logged in case by using an if statement to only process the value if it is not null.
     
    */
     
      if (principal != null)
     
      {
     
    /*
     
    Now get the user name as a String using the getName() method for the java.security.Principal object.
     
    */
     
        userName = principal.getName();
     
      }
     
    %>
     
    <%-- 
    Display the value of the userName variable using a scriptlet.  Note that the scriptlet is embedded in the HTML and is denoted by the <%= %> block. The "=" sign indicates that the scriptlet should be evaluated as string and output in the HTML.  It can be any valid Java expression, including a variable or method call.
     
    --%>
     
    The user name is : <%= userName %>
     
    <br>

  7. Save the file and re-load the portal in your browser.

    Figure 5-6 Scriptlet without Authenticated Visitor


     
     

  8. The portlet should appear as it does in Figure 5-6.

  9. Login as the following test user: acme/acme.

  10. Notice that the phrase "The user name is:" is now followed by the name of the new user, as shown in Figure 5-7.

    Figure 5-7 Scriptlet Showing Authenticated Username


     

Displaying User Profile Values

This section outlines how to use a simple tag to insert a value from a user profile into your portlet. Figure 5-8 shows that the property we're going to expose is already set in the stock portal sample data.

Figure 5-8 Viewing the PreferredLanguage Property


 

Exposing a property such as PreferredLanguage only requires placing a few of lines of code inside a portlet. This is an example of the efficiency of using JSP tag libraries to develop reusable components.

  1. First, use the E-Business Control Center to look at the user property:

    Select the Site Infrastructure tab at the bottom right corner of the E-Business Control Center.

    Click on User Profiles, then double-click on the StockPortal profile.

    Notice the default setting for the PreferredLanguage property, shown in Figure 5-8.

  2. Now, in the native file system, navigate to the /portlets/test directory and open the portlet.jsp file in Notepad.

  3. Replace the contents of the file with the code in Listing 5-4.

  4. Save the portlet.jsp and refresh the browser. (If not logged in, do so as the following test user: acme/acme.

  5. Notice the PreferredLanguage is Java.

    Listing 5-4 Getting a Property from User Profile

     
    <center>
     
    This is Our Test Portlet
     
    </center>
     
    <br>
     
    <hr>
     
    Now try some simple Java scriptlets:
     
    <br>
     
    <br>
     
    <%
     
    // The following code is from the earlier example minus the comments
     
      String userName = ""; 
      java.security.Principal principal = request.getUserPrincipal();
     
      if (principal != null)
     
      {
     
        userName = principal.getName();
     
      }
     
    %>
     
    The user name is : <%= userName %>
     
    <br>
     
    <hr>
     
    Now try some simple JSP tags:
     
    <br>
     
    <br>
     
    <%-- Import the User Management tag library. --%>
     
    <%@ taglib uri="um.tld" prefix="um" %>
     
    <%-- 
    Get the PreferredLanguage property as a String from the StockPortal user profile property set and store the value in the preferredLanguage variable.
     
     --%>
     
    <um:getPropertyAsString propertyName="PreferredLanguage"
     
     propertySet="StockPortal" id="preferredLanguage"/>
     
    <%-- Display the preferredLanguage variable in a scriptlet. --%>
     
    The preferred language is: <%= preferredLanguage %>
     
    <br>

Note: About the code in Listing 5-4:

Changing User Profile Values

Using the same scriptlet code in Listing 5-4, let's change the value of the property for the test user acme/acme.

  1. To change the property value for this user, navigate to the following URL: 
    http://<hostname>:7501/portalTools/index.jsp

  2. Login as Administrator/<password>

  3. Click on the User Management home page, and select Users.

  4. Search for acme, and click on the acme user from the list.

  5. From the dropmenu on the left, select the StockPortal property set and click the red Search button.

  6. On the right tab next to the PreferredLanguage property, click on Edit.

  7. From the Edit Property Values page, set the value to "C" and click Save.

  8. If a "Property set correctly" message appears, go back to the browser where the acme user is logged into stockportal.

  9. Refresh the browser. The value of the PreferredLanguage should now be "C".

For More Information on JSP Tags and User Profiles

WebLogic Portal 4.0 provides a number of other JSP tags you can use to bring rich functionality into your portlets quickly and easily. Most of the major functionality provided by the WebLogic Portal platform is available via JSP tags. For more a complete list of available portal-specific JSP tags, consult Portal Management JSP Tag Library Reference.

To learn more about how user profiles are created and managed in the WebLogic Portal platform, consult Chapter 7, "Creating and Managing Users," in the Guide to Building Personalized Applications.

Several examples that use personalization JSP tags are installed with the out of the box product. You can view these working examples by navigating to the following URL:

 
http://<hostname>:7501/p13n

Note: Login as acme/acme.

 

In What Ways Can Portal be Customized?

The out of the box installation of WebLogic Portal includes a sample portal Web application which is intended to be used as a building block for your custom portals. The most basic customization involves copying and modifying this sample portal. Even if you start from scratch, many of the supporting files are already created for you. This topic explains these simple tasks, as well as creating your own portlets, applying Webflows to individual portlets, and setting up a development environment where several Business Engineers can stage their work simultaneously on a single development instance of WebLogic Portal without overwriting each other's files.

How Portals Are Defined

Portals are constructed of JSPs, image files and whatever other HTML or Javascript is needed to achieve the desired functionality. Within the WebLogic Portal platform, a portal is defined using XML metadata files maintained by the Portal Module in the E-Business Control Center, as shown in Figure 5-9.

Figure 5-9 Portal.portal XML file


 

Comparing the entries in this portal definition file to those appearing in the E-Business Control Center Portal module, you can infer that the XML files are metadata, containing references to the J2EE application resources that make up the application itself.

The entries in this portal definition file tell the platform where to go for each of the following resources:

Entry

Definition

General Settings


Optional text string describing portal

Location of Content portion of portal

Location of optional portal header

Location of optional portal footer

Location of vertical navigation bar

Location of horizontal navigation bar

Name of portal Webflow

Add and Remove portlet elements

Move portlet elements from Available (cannot be used) to Selected (can be used)

These design components can be excluded (marked as Available) from the current portal deployment or included in the current portal deployment (Selected)

These optional personalization mechanisms can be applied to individual portlets or to entire portals

Pages

Manage Pages within a Portal

A new Portal page (sometimes called a page view) is designated by specifying a unique name and at least one layout and at least one portlet. Optionally, default, rollover and selected images can be designated here as well

The parameters of an existing page can be changed, and existing existing Portal pages can be deleted

Defaults

These portal parameters are set for each portal visitor, but are overwritten by any customization performed by the visitor.

The name displayed in the browser's title bar - for example, "BEA Basic Portal"

The default look and feel template associated with this portal

The default portal page associated with this portal

Subset of all existing portal pages can be made available

Horizontal or Vertical

Clicking Up or Down button re-orders selected page view

Set Rendering Parameters for selected Page View

Designate an existing layout as the default

Use Page Layout tool to position portlets within selected layouts

Enter default values for the following settings:

Note: Default settings are used to initialize the setup for a visitor. They are overwritten when the visitor chooses "customize my portal."

How Portlets Are Defined

Portlets can include some combination of the following presentation elements:

Using the E-Business Control Center, you can view a portlet definition by selecting Portlets in the Presentation tab, as shown in Figure 5-11.

Figure 5-11 Editing a Portlet


 

When the portlet is selected, the definition editor appears, exposing the parameters that make up a portlet in WebLogic Portal. Figure 5-12 shows the definition settings for Portlet2 in the sample portal.

Figure 5-12 Portlet definition


 

Portlets, not unlike portals, are made up of JSPs, images and other resources, and are defined by XML metadata files. Where portal definitions determine which resources (skins and portlets) can be included, portlet definitions are more self-referential: They determine the components that make up the portlet, as well as certain presentation and navigation behaviors. Many of these definition elements are optional, and several can be determined within the portlet definition or within a Webflow specific to that portlet namespace.

Entry

Definition

Optional text string describing portlet

Location of content portion of portlet (can be declared within Webflow)

Location of optional portal header

Optional URL for Maximization

Location of optional portal footer

Optional URL for Maximization

Location of titlebar URL

Location of optional banner URL

Location of optional Icon URL

Name of optional portlet Webflow

If checked, requires Edit URL (or declaration within Webflow)

If checked, requires Help URL

Optional

Optional URL for separate maximize layout (can be declared within Webflow)

Enter default values for the following settings:

How Portal Resources Are Defined

The JSPs, HTML pages, image files and directory structures for the portal web application may also be accompanied by CSS files and other sets of images used to provide skins for the new application. After these objects are installed on the server, the Business User can use the E-Business Control Center Portal Module to create references to these resources for the WebLogic Portal server.

The E-Business Control Center Portal module provides a graphical interface for specifying key parameters about a portal, and defining which resources are available to the portal, such as pages, layouts, skins and portlets. These resources can be edited offline, then synchronized later.

Define a Portal

Steps to define a portal resources are covered in Using the E-Business Control Center Portal Tool.

 

Look and Feel Customization

The appearance of HTML pages can be customized in many ways. WebLogic Portal provides a number of access points to replace the out-of-the-box layouts, images and HTML page styles.

The workflow is similar to other tasks you perform using the portal framework: As with portlets and other portal Web application objects, the application files (in this case, layout JSPs, cascading style sheet files and images) are created and migrated into the server's native file system using your choice of tools. The metadata is then edited and migrated using the E-Business Control Center. Finally, the application resources you have created and made available on the portal server are administrated and managed using the WebLogic Portal Administration Tools.

This section explains the implementation of layouts and skins in the out-of-the-box installation, and outlines the basic procedures for creating custom layouts and skins. After reading this section, an HTML developer familiar with cascading style sheets should be able to customize the appearance, layout and navigation buttons for portals and portlets, and be able to manage the inheritance of these look and feel objects within portal web applications.

How Layouts Are Implemented

Out of the box, WebLogic Portal provides the following five default layouts:

These layouts consist of two elements: a simple template.jsp file and a thumbnail image. The JSPs declare a set of placeholders and then insert these placeholders within the HTML fragment. The JSP resides within a layout folder, and its corresponding thumbnail image is displayed by the EBCC while the metadata is being edited. The layout folders are located in the following directory:

 
<portal_home>\applications\portal-project\library\portal\layouts

Create a Custom Layout

Creating a custom layout is fairly straightforward. This example uses a copy of an existing layout, shown in Listing 5-5.

Listing 5-5 template.jsp for fourcolumn layout

 
<%@ taglib uri='ren.tld' prefix='layout' %>
 
<layout:placePortletsinPlaceholder placeholders="left,leftcenter,rightcenter,right" />
 
<table width="100%" border="0" cellspacing="0" cellpadding="0">
 
  <TR>
 
    <TD WIDTH="25%" VALIGN="TOP">
 
      <layout:render section='left'/>
 
    </TD>
 
    <TD WIDTH="25%" VALIGN="TOP">
 
      <layout:render section='leftcenter'/>
 
    </TD>
 
    <TD WIDTH="25%" VALIGN="TOP">
 
      <layout:render section='rightcenter'/>
 
    </TD>
 
    <TD WIDTH="25%" VALIGN="TOP">
 
      <layout:render section='right'/>
 
    </TD>
 
  </TR>
 
</TABLE>

  1. Make a copy of the fourcolumn layout folder and its contents.

  2. Replace the contents of template.jsp with the code in Listing 5-6.

  3. Rename the folder "fivecolumn", and rename the image inside fivecolumn.gif. Use a simple graphic editor to alter the four-column thumbnail to it has five columns.

  4. Open the template.jsp in notepad. Notice the reference to a JSP tag library called "ren.tld". This tag library encapsulates portal rendering code, and takes the following parameters: 
    layout:placePortletsinPlaceholder
     
    placeholders=''<placeholder names>

    With the layout tag called and its placeholders declared, all that remains is to place calls to the layout tag within the HTML table. Notice that placeholders are referred to as "section" when they are used inside the HTML.

  5. Place the directory, including the GIF and the JSP file, into the following location: 
    <portal_home>applications\portal\stockportal\framework\layouts

    Notice that a new placeholder has been declared called center. For more detail on how these placeholders are used by the framework, consult The Auto Placer and "Homeless" Portlets.

Note: Make sure the thumbnail is named the same as the layout directory.

Listing 5-6 template.jsp for fivecolumn layout

 
<%@ taglib uri='ren.tld' prefix='layout' %>
 
<layout:placePortletsinPlaceholder placeholders="left,leftcenter,center,rightcenter,right" />
 
<table width="100%" border="0" cellspacing="0" cellpadding="0">
 
  <TR>
 
    <TD WIDTH="20%" VALIGN="TOP">
 
      <layout:render section='left'/>
 
    </TD>
 
    <TD WIDTH="20%" VALIGN="TOP">
 
      <layout:render section='leftcenter'/>
 
    </TD>
 
    <TD WIDTH="20%" VALIGN="TOP">
 
      <layout:render section='center'/>
 
    </TD>
 
    <TD WIDTH="20%" VALIGN="TOP">
 
      <layout:render section='rightcenter'/>
 
    </TD>
 
    <TD WIDTH="20%" VALIGN="TOP">
 
      <layout:render section='right'/>
 
    </TD>
 
  </TR>
 
</TABLE>

How Skins Are Implemented

Out of the box, WebLogic Portal provides the following five default skins:

Skins are made up of .css files and some images. The thumbnail images for the EBCC reside in the following directory:

 
<portal_home>applications\portal-project\library\portal\skins

The folders containing images and css files reside in the following directory:

 
<portal_home>applications\portal\stockportal\framework\skins

For stockportal, the location of these resources is stipulated in the following file:

 
<portal_home>\applications\portal\stockportal\framework\resourceURL.inc

Making Custom Skins Available to the Portal Framework

To create custom skins, have an HTML designer create cascading style sheet files and HTML image files, and package them according to the skins directories in the following folder:

<portal_home>applications\portal\<yourportal>\framework\skins

  1. From the <portal_home>applications\portal\<yourportal>\framework\skins directory, copy an existing skin directory to use as a template. For example, copy skins\coologic to skins\newskin.

  2. Modify main.css and the images, or copy in the images and css files created by a designer.

  3. Run the portal.

  4. Take a screenshot of the portal and update the thumbnail gif in the following directory: 
    portal-project\library\portal\skins

  5. From the <portal_home>applications\portal-project\application-sync\webapps\<yourportal>, edit <yourportal>.portal file. Add the following reference to your skin in the <skin-pool> node: 
    <skin-pool>
     
         <skin-name>coologic</skin-name>
     
         <skin-name>futurism</skin-name>
     
         <skin-name>newskin</skin-name>
     
    ...
     
    </skin-pool>

  6. In the EBCC, open the portal, go to General > Skins. Notice that the new skin is visible in the Available skins list. Add the skin to the selected skin list. You can make it the default skin.

Note: These resources also exist within <ebcc_home>\applications\ portal\application-sync\webapps\<yourportal>

When designing skins, note that CSS attributes take precedence over non-CSS attributes. For example, if the content heading color attribute is set within the JSP:

<span class="contentheading" color="green">Test</span>

But the contentheading style is set this way:

.contentheading{

color: blue;

}

The text will be displayed blue instead of green.

 

Webflow and the Portal Platform

To customize the behavior of your portal Web applications, whether that means creating special navigation logic for a simple portlet, or developing complex business and presentation framework customizations that change the portal platform to suit your business case, an understanding of Webflow is required.

Figure 5-13 outlines the architecture of the portal platform, and gives insight into the way Webflow functionality is implemented.

Figure 5-13 Portal High Level Architecture


 

The Portal Framework as a Webflow Application

With a few exceptions, Webflow works the same way in portal web applications as it does within the rest of the platform. That is, you can use Webflow to coordinate different parts of your portal web application, enabling code reuse and maintainability.

Because its main function is to serve as a structure of reusable presentation and navigation modules, the Portal framework itself can be though of primarily as one large Webflow application. For this reason, the default Webflow underlying the sample portal included with WebLogic Portal, although it can be edited, should be thought of as a fundamental part of the Portal framework. As such, the portal.wf file included with the installation of the stockportal should not be edited. Unless you or your developers possess intimate knowledge of BEA Webflow functionality, the Portal Webflow should be reused as is. That said, a developer well versed in Webflow can customize the Webflow for a portal. For more information on Webflow, consult the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline.

For the most part, Webflow functionality is invoked the same way within the Portal framework as it is within the rest of the WebLogic Server platform, with the Webflow servlet (in this case the PortalWebflowServlet) performing most of the routing between validation, session logic and custom processor nodes. For an exhaustive discussion of Webflow, consult the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline. This section covers those aspects of Webflow functionality that are specific to the Portal framework.

Portal Presentation Logic and Webflow

Webflow and WebLogic Portal could also be thought of as two complementary navigation mechanisms. The portal platform provides an array of content placeholders, each able to function as a virtual browser that controls its own state without influencing the state of its neighbor portlets. The Webflow mechanism is designed to enable the navigation logic of a web application to be controlled by a multitude of factors, meaning that Personalization, Commerce and Campaign Services can all be coordinated to influence what is presented to the visitor at runtime. While portal Webflow is largely a part of the platform you are not expected to customize, each individual portlet can be assigned its own particular Webflow. The following section explains the basic requirements in using Webflows with portlets.

Note: For the most part, Webflow customization is to be performed using the Webflow Editor with the E-Business Control Center. This means you will not be editing the XML files in a text editor. This section exposes some fragments of these files for illustration only.

Portlets and Webflow

The Webflow associated with portals are generally not to be edited because it is fundamental to the application logic that makes up the portal platform. Individual portlets, however, can have individual Webflow files assigned to them, allowing practically all Webflow functionality to be applied to a portlet.

Portlet Webflow Parameters

Portal Webflow is always invoked with the following three parameters:

What Events Are Called on Portlet Webflow?

The out-of-the-box framework uses the following portlet events, all of which must be handled when Webflow is invoked:

These events are called when the corresponding actions are performed, and handled by the out-of-the-box framework. You can use these events within your own portlets, and you can also define your own events. Your custom events can be triggered from within your custom portlets, or they can be triggered by portlet framework events.

The Refresh Event

Understanding Webflow in portals requires a grasp of the Refresh event. To illustrate the way this event is used, consider the following page view of the sample portal shown in Figure 5-14.

Figure 5-14 Three Portlets


 

If a visitor minimized portlet2, a refresh event would be sent to both the other portlets via the PortalWebflowServlet, illustrated in Figure 5-13. It is this refresh event which would be used to make one portlet communicate with or respond to another portlet. (Remember that this refresh event is accompanied by the portlet namespace as well as the origin.)

The Origin Parameter

Portlet Webflows do not use Origin differently than other web applications. Consider what happens when a user clicks on the Next Page link in Portlet2 as shown in Figure 5-14. As you can see from looking at the Webflow fragment show in Figure 5-15, the presentation node defined as the origin is "portlet," and the destination node declared for that origin is portletB.

Figure 5-15 Portlet2 Webflow Origin for Page 1


 
 

Sure enough, clicking on the "Next Page" link in page 1 of Portlet2 takes you to Page 2, as shown in Figure 5-16.

Figure 5-16 Portlet Origins and Webflow


 

To understand how the "Previous Page" link on Page2 is made to point to the initial presentation node designated for Portlet2, look at the Webflow fragment show in Figure 5-17.

Figure 5-17 Portlet2 Webflow Origin for Page 2


 

Considering this simple example illustrating the Origin parameter and the way Refresh events are handled in the portal framework, you can begin to see how much customization can be accomplished without writing any Java code. Keep in mind, however, that you will not need to edit the Webflow file directly - these fragments are shown for illustration only. The actual Webflow configuration is done using the Webflow Editor.

Figure 5-18 is an image from the Webflow editor, showing a very simple portlet Webflow which navigates from one JSP to another and back. You can see an example of a Webflow this simple in portlet 2 in the stock portal.

Figure 5-18 Simple Portlet Webflow Image


 
 

Using Webflow Within a Portlet

A few general reminders could save you some time:

When to Use Portlet Webflow

Webflow is not mandatory - it is an advanced feature of the WebLogic Portal platform. For more information on Webflow, consult the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline. Briefly, here are some reasons to use Webflow in individual portlets:

What Portlet Webflows Can Specify

In order for them to use Webflows, portlets must observe the following contract: the Edit, Maximize and Content URLs described in the table above can either be declared within the portlet definition, or they can be handled within the Webflow for that individual portlet.

Note: By design, presentation nodes for a portlet must exist in the same namespace. Non-presentation nodes can exist in separate namespaces, but the portlet webflow must return to the originating namespace for all presentation nodes. This means that portlets may not have multiple namespaces.

 

back to top previous page next page

 

Copyright © 2002 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.77 or higher, or Microsoft Internet Explorer 5.01 or higher.
Contact us (documentation feedback only)