# Oracle9iAS Portal Developer Kit (PDK)
How to Build a URL-Based Portlet

Last Updated: | April 15, 2003
Status: | Production
Version: | PDK Release 2, (9.0.2 and later)

## Introduction

Once you have successfully installed and deployed the PDK, you will probably want to begin building URL-based portlets of your own. With the PDK framework, building URL-based portlets is a simple process involving no coding at all.

Note: You can also clip portlets from existing web sites using the Web Clipping tool. Web Clipping is part of the PDK and is geared toward page designers who want to use a wizard-based format to clip web pages. For more information on Web Clipping, review the whitepaper called Web Clipping Portlet.

This article shows you how to create a simple URL-based portlet and display it on an Oracle9iAS Portal page.

## Assumptions

1. You have successfully installed the PDK framework by following the article Installing the PDK Framework and Samples.
2. You have gone over web provider architecture concepts for URL-based portlets by reading the articles: A Primer on URL-Based Portlets, Understanding the PDK Runtime for URL-Based Portlets, and Understanding the provider.xml for URL-Based Portlets.

## Creating an XML Provider Definition

This section explains how to create an XML provider definition for your URL-based portlet provider. You can configure provider-specific information like portlet title and portlet description in the XML file. This XML file is also where you specify the URL that gets displayed in your portlet.

Using a text editor, create an XML file for your portlet provider. Use the pageUrl tag to specify the URL that this portlet will display. You may use the sample xml file below (you must change the httpProxyHost and httpProxyPort values to point to your own proxy server and port). Please refer to the article Understanding provider.xml for URL-Based Portlets for an explanation of the required XML tags and their functions.

After you have created the file, save it somewhere on your file system and call it "provider.xml".

>     <?xml version="1.0" encoding="UTF-8"?>
>     <?providerDefinition version="3.1"?>
>     <provider class="oracle.portal.provider.v2.http.URLProviderDefinition">
>       <providerInstanceClass>oracle.portal.provider.v2.http.URLProviderInstance</providerInstanceClass>
>       <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
>         <httpProxyHost>www-proxy.us.oracle.com</httpProxyHost>
>         <httpProxyPort>80</httpProxyPort>
>       </proxyInfo>
>       <portlet class="oracle.portal.provider.v2.http.URLPortletDefinition">
>         <id>1</id>
>         <name>GooglePortlet</name>
>         <title>Google.com Portlet</title>
>         <description>Display Google.com as a portlet.</description>
>         <timeout>30</timeout>
>         <timeoutMessage>Google timed out</timeoutMessage>
>         <acceptContentType>text/html</acceptContentType>
>         <renderer class="oracle.portal.provider.v2.render.RenderManager">
>           <showPage class="oracle.portal.provider.v2.render.http.URLRenderer">
>             <contentType>text/html</contentType>
>             <pageUrl>http://www.google.com</pageUrl>
>             <filter class="oracle.portal.provider.v2.render.HtmlFilter">
>               <headerTrimTag>&lt;body</headerTrimTag>
>               <footerTrimTag>/BODY></footerTrimTag>
>             </filter>
>           </showPage>
>         </renderer>
>       </portlet>
>     </provider>

## Deploying Your Provider on OC4J

The following steps describe how to deploy your new portlet provider on OC4J. These steps assume you have already deployed the PDK sample provider according to the article Installing the PDK Framework and Samples. Instead of creating another OC4J application for the Google.com provider, you can just add your provider definition file to the OC4J application from the aforementioned article. Note: If your existing OC4J application is getting too large, you may want to create and deploy a new application for this provider by following the steps from the article Deploying Portlets in Release 2.

1. Go to the directory in which the PDK sample providers are located. It should be something like: $IAS_HOME/oc4j/j2ee/home/applications/jpdk/jpdk/WEB-INF/providers.

2. Create a new directory called google. Copy the provider.xml that you created above to this google directory.

3. Go to the directory in which the PDK sample deployment files are located. It should be something like: $IAS_HOME/oc4j/j2ee/home/applications/jpdk/jpdk/WEB-INF/deployment.

4. Create a copy of the sample.properties file and rename it, google.properties. Open the google.properties file.

5. Replace the line

   > `definition=providers/sample/provider.xml`

   with

   > `definition=providers/google/provider.xml`

6. Save and close the google.properties file.

7. If you have not already done so, start OC4J.

8. View the test page to verify that everything is working properly. Go to: http://<yourservername:port>/jpdk/providers/google.

## Registering Your Provider

At this point, you are ready to register your provider and then add the Google.com portlet to a page. These steps assume you are registering your provider on Portal 9.0.2.

1. Login to your Oracle9iAS Portal as an administrator.

2. Click on the Builder icon at the top right.

3. In the Provider portlet, click on Register a Portlet Provider.

4. In the first screen of the Add Provider wizard, enter the following:

   1. Name: GoogleProvider

   2. Display Name: Google Provider

   3. Timeout: 30

   4. Timeout Message: Google Provider Timed Out

   5. Implementation Style: Web

5. Click Next.

6. In the second screen of the Add Provider wizard, enter the following and leave the defaults for the rest of the fields:

   1. URL: http://<yourservername:port>/jpdk/providers

   2. Service Id: urn:google

7. Click Finish.

You are now ready to add the Google.com portlet to a page.

## HTML Clipping and Relative Links

The URL-based portlet you just built uses HTML clipping to filter the HTML to display within the portlet. HTML clipping is specified by the following tags in the provider.xml file:

- filter: The filter tag indicates that content will be filtered before being displayed in the portlet. To specify HTML filtering, set the class attribute of this tag to "oracle.portal.provider.v2.render.HtmlFilter"
- headerTrimTag: This is the tag from your specified page that will be used to filter header content. Any HTML on the page that is above this tag will be filtered.
- footerTrimTag: This is the tag from your specified page that will be used to filter footer content. Any HTML on the page that is below this tag will be filtered.

The URL-based portlet above also converts relative links on your behalf. This is a feature that is automatically enabled when you set the filter tag to "oracle.portal.provider.v2.render.HtmlFilter". When the HtmlFilter class is used, the filter parses the HTML of your specified URL for any relative links and then converts these links to absolute links before rendering the HTML in the portlet.

## Next Steps

The following articles show you how to enhance the user interface of a URL-based portlet:

- How to Build a URL-Based Portlet that Uses HTML Filtering
- How to Build a URL-Based Portlet with Inline Rendering of Portlet Links

The following articles show you how to enhance the security of a URL-based portlet:

- How to Build a URL-Based Portlet with Single Sign-On to an External Application
- How to Build a URL-Based Portlet with Single Sign-On to an Application Using Basic Authentication

Revision History: |
Revision No | Last Update
1.0 | June, 2002

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ | Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 | Copyright and Corporate Info