61 Creating Content-Based Portlets with Web Clipping

Web Clipping is a publishing portlet that enables you to integrate any web application with your WebCenter Portal application. Web Clipping is designed to give you quick integration by leveraging the existing user interface of a web application. With Web Clipping, you can collect web content into portlets in a single centralized web page. You can use Web Clipping to consolidate content from web sites scattered throughout a large organization.

This chapter includes the information you are required to know to use Web Clipping in your Oracle JDeveloper environment. For information about how to use Web Clipping at runtime, refer to the "Working with the Web Clipping Portlet" chapter in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

This chapter includes the following sections:

• Section 61.1, "Introduction to Web Clipping"

• Section 61.2, "Adding Web Clipping to Your Application"

• Section 61.3, "Integrating Authenticated Web Content Using Single Sign-On"

• Section 61.4, "Advanced Features of Web Clipping"

• Section 61.5, "Current Limitations of Web Clipping"

• Section 61.6, "Troubleshooting Web Clipping"

For information about additional Web Clipping portlet producer configuration such as repository and proxy settings and producer security, see Appendix E, "Additional Portlet Configuration."

You can find information about developing different types of portlets and information about producers and other portlet technologies in Chapter 53, "Overview of Portlets."

61.1 Introduction to Web Clipping

With Web Clipping you can clip an entire web page or a portion of it and reuse it as a portlet. You can clip basic and HTML-form-based sites. Use Web Clipping when you want to copy content from an existing web page and expose it in your WebCenter Portal application as a portlet.

Web Clipping supports the following features:

• Navigation through various styles of login mechanisms

  Web Clipping supports various login mechanisms including form- and JavaScript-based submission and HTTP Basic and Digest Authentication with cookie-based session management.

• Fuzzy matching of clippings

  Fuzzy matching enables the Web Clipping engine to correctly identify a web clipping and deliver it as portlet content even if the web clipping is reordered within the source page or if its character font, size, or style changes.

• Personalization

  Personalization enables you to expose input parameters that end users can modify when they personalize the portlet. Parameters can be exposed as public parameters that you can map as page parameters. This feature enables end users to obtain personalized clippings.

• Integrated authenticated web content through single sign-on

  You can use external applications and leverage Oracle Single Sign-On to clip content from authenticated external web sites.

• Inline rendering

  Inline rendering enables you to set up Web Clipping portlets to display links within the context of the portlet. When a user clicks a link in the Web Clipping portlet, the results display within the same portlet. You can use this feature with internal and external web sites.

• Proxy authentication

  Web Clipping supports proxy authentication, including global proxy authentication and authentication for each user. You can use this feature if proxy servers require authentication. You can specify proxy server authentication details, including type (Basic or Digest) and realm in the provider.xml file. In addition, you can specify a scheme for entering user credentials:

  • All users automatically log in using a user name and password that you provide.

  • All users are required to log in using a user name and password that they provide.

  • All public users (not authenticated into the WebCenter Portal application) automatically log in using a user name and password that you provide, while valid users (authenticated into the WebCenter Portal application) log in using a user name and password that they provide.

  For more information, see Section E.2.2, "HTTP or HTTPS Proxy Configuration."

• Support for HTTPS

  Web Clipping enables you to clip content from HTTPS-based external web sites if appropriate server certificates are acquired. For information about server certificates, see Section E.2.3.1, "Adding Certificates for Trusted Sites."

• Open Transport API

  By default, the Web Clipping provider supports only HTTP challenge-based authentication methods, such as Basic and Digest and form submission logins. To support custom authentication methods, such as Kerberos proxy authentication, you can use the Web Clipping Transport API. For more information, see Section 61.4.1, "Using the Web Clipping Transport API."

• Reuse of a wide range of web content

  Web Clipping provides basic support of pages written with JavaScript, applets, and plug-in enabled content, retrieved through HTTP GET and POST methods of form submission.

  Web Clipping also supports clipping of content from pages written with HTML 4.01, including:

  • Clipping of <applet>, <body>, <div>, <embed>, <img>, <object>, <ol>, <span>, <table>, and <ul> tagged content

  • Preservation of <head> styles and fonts, and CSS

  • Support for UTF-8 compliant character sets

  • Navigation through hyperlinks (HTTP GET), form submissions (HTTP POST), frames, and URL redirection

• Globalization support

  Web Clipping provides globalization support in URLs and URL parameters. For information about how Web Clipping determines the character set of clipped content, see Section 61.5, "Current Limitations of Web Clipping."

• Persistent storage of Web Clipping definitions

  Web Clipping definitions are stored persistently in a repository. By default, in JDeveloper, the Web Clipping producer is configured to use the file-based Oracle Metadata Service (MDS) as a repository. If you prefer, you can use a database schema for your Web Clipping repository. For information about configuring a Web Clipping repository, see Section E.2.1, "Web Clipping Repository Configuration."

• Encryption of secure information

  Any secure information, such as passwords, is stored in an encrypted form, according to the Data Encryption Standard (DES), using Oracle encryption technology.

61.2 Adding Web Clipping to Your Application

You can add a Web Clipping portlet to a JSP document created through JDeveloper. For more information, see Chapter 59, "Consuming Portlets." The Web Clipping portlet producer is included in:

• Integrated WebLogic Server (WLS), the default server installed with JDeveloper

• The WLS_Portlets managed server in the default domain in a full Oracle Fusion Middleware installation

To add a Web Clipping portlet to your application:

1. In JDeveloper, start Integrated WLS. For information, see Section 3.4, "Working with the Integrated WebLogic Server."

2. In JDeveloper, register the Web Clipping producer. For more information, see Section 59.2.3, "How to Register an Oracle PDK-Java Portlet Producer."

   During this step, you must provide the endpoint URL, for example:

   http://localhost:7101/portalTools/webClipping/providers/webClipping
   

   You can choose to register the Web Clipping portlet producer from the WLS_Portlets managed server or Integrated WLS.

   When the producer is registered, portlets become available either in the Application Resources panel or the Resource Palette.

3. From the Application Resources panel or the Resource Palette, drag the Web Clipping portlet onto your .jspx page. For more information, see Section 59.3, "Adding Portlets to a Page."

   If you are using a PanelCustomizable or ShowDetailFrame component, then drag the portlet on top of that component instead of af:form. In the Structure pane, the Web Clipping portlet must display under the PanelCustomizable or ShowDetailFrame component. In the Page Editor, the portlet must display inside the PanelCustomizable or ShowDetailFrame component.

   
   

   Note: When you add an instance of Web Clipping to your page in JDeveloper, open the Property Inspector for the portlet and ensure that the AllModesSharedScreen and RenderPortletInIFrame properties are set as follows: AllModesSharedScreen is set to false to display the Customize and Personalize in full page size. If you do not set this property to false, then when you edit the Web Clipping portlet at runtime, the text displayed on the page may be distorted. RenderPortletInIFrame is set to true to display the Web Clipping in its own inline frame (IFRAME) in the View mode.

   
   

4. Right-click the .jspx page and choose Run.

   The Web Clipping portlet displays in your default browser.

5. Customize the Web Clipping portlet to define its contents. For information, see the "Working with the Web Clipping Portlet" chapter in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

   
   

   Note: To clip SSL-enabled web sites, you must add certificates of those sites to the certificate store. You are not required to add certificates of SSL-enabled web sites that use Equifax, VeriSign, or Cybertrust certificates because these certificates are included in the default certificate store. For information about adding certificates, see Section E.2.3.1, "Adding Certificates for Trusted Sites."

   
   

61.3 Integrating Authenticated Web Content Using Single Sign-On

You can leverage Oracle Single Sign-On to integrate content from external web sites that require authentication, into a Web Clipping portlet.

To integrate an external application that requires authentication:

1. Open your WebCenter Portal application in JDeveloper.

2. Register the external application, specifying the authentication information. For more information, see Section 63.13.3.2.1, "Registering an External Application in Oracle JDeveloper."

3. Register the Web Clipping producer. For information, see Section 59.2.3, "How to Register an Oracle PDK-Java Portlet Producer."

   While registering the producer by using the Register Oracle PDK-Java Portlet Producer wizard, on the Specify Connection Details page, select the Associate Producer with External Application checkbox, and from the list of values, select the external application that you just registered. The Enable Producer Sessions checkbox gets selected automatically.

   Figure 61-1 shows the external application named MyOracleSupport associated with a Web Clipping producer.

   Figure 61-1 Associating a Web Clipping Producer with an External Application

   
   Description of "Figure 61-1 Associating a Web Clipping Producer with an External Application"
   
   

4. Add the Web Clipping portlet from the producer that you just registered to a .jspx page.

5. Right-click the .jspx page and choose Run.

6. If you did not specify shared or public credentials for the external application, then the portlet contains an Update login information link. Click this link.

7. Enter your credentials, and then click OK to log in to the external web site.

   Figure 61-2 shows the login screen of an external application named MyOracleSupport.

   Figure 61-2 Logging into the Integrated External Application

   
   Description of "Figure 61-2 Logging into the Integrated External Application"
   
   

8. Click the Actions icon on the header of the Web Clipping portlet, and select Customize.

   The Find a Web Clipping page displays, with the default URL for the external application displayed in the URL Location field (Figure 61-3).

   Figure 61-3 Finding a Web Clipping

   
   Description of "Figure 61-3 Finding a Web Clipping"
   
   

   You can now select any section of a web page that you intend to display in your Web Clipping portlet. For information about how to customize a Web Clipping portlet, see the "Working with the Web Clipping Portlet" chapter in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

   After you clip the required page of the external application, the web clipping, even though it is from a page requiring authentication, is available in your portlet.

61.4 Advanced Features of Web Clipping

Web Clipping supports certain advanced features. You can configure custom authentication methods by using the Web Clipping Transport API and rewrite image links to use a resource proxy.

This section includes the following subsections:

• Section 61.4.1, "Using the Web Clipping Transport API"

• Section 61.4.2, "Rewriting Image Links to Use a Resource Proxy"

61.4.1 Using the Web Clipping Transport API

To support custom authentication methods, you can use the Web Clipping Transport API. To extend the Web Clipping transport layer to support custom authentication methods, you must perform several implementation and deployment procedures.

This section includes the following subsections:

• Section 61.4.1.1, "Implementing the Web Clipping Transport API"

• Section 61.4.1.2, "Deploying the Web Clipping Transport API"

61.4.1.1 Implementing the Web Clipping Transport API

If you want to support a custom authentication method, such as Kerberos, you must first implement your own transport classes.

To implement custom transport classes:

1. Override two use cases of the oracle.portal.wcs.transport.http.HttpTransportLiaison interface.

   In Web Clipping, this interface is used to abstract the HTTP transport layer. By default, the two use cases of this interface are manifested by the following implementations:

   • HttpClientStudioTransportLiaison, which handles HTTP transport in Web Clipping Studio mode

   • HttpClientProviderTransportLiaison, which handles HTTP transport in Web Clipping Producer show mode

   To support more authentication methods, you must override the addRequestHeaders methods for both the Studio and Provider HttpClientTransportLiaison implementations to add your own authentication-specific headers. For information, see Oracle WebLogic Server Web Clipping Transport API Reference.

2. Compile the new subclasses and package them into a JAR file.

   For example, to compile the new subclasses, use the following command:

   javac -classpath path_to_wcejar -d classes/

   Where, path_to_wcejar refers to the path to the wce.jar file.

   To create the JAR file, for example, run the following command from the classes directory:

   jar cvf ../mytransport.jar

   Where, mytransport.jar refers to the JAR file users want to create.

61.4.1.2 Deploying the Web Clipping Transport API

After implementing the new transport classes, you must deploy the JAR file to support the custom authentication method.

To deploy the JAR file:

1. Place the JAR file into the class path or shared library that is used by the Web Clipping producer at runtime.

2. Register the transport class in the web.xml file for the Web Clipping producer by making the following modifications to the context parameters defined for HttpClientProviderTransportLiaison and HttpClientStudioTransportLiaison:

   • Change the parameter value for oracle.webclipping.provider.TransportLiaisonClass to the name of the new class extended from the HttpClientProviderTransportLiaison class.

   • Change the parameter value for oracle.webclipping.studio.TransportLiaisonClass to the name of the new class extended from the HttpClientStudioTransportLiaison class.

3. Restart the producer server for the changes to take effect.

61.4.2 Rewriting Image Links to Use a Resource Proxy

Web Clipping enables you to rewrite image links to use a resource proxy. To enable this feature, you must add the following entry to the web.xml file of the Web Clipping producer:

<env-entry>
    <env-entry-name>oracle/webclipping/rewriteImageLink</env-entry-name>
    <env-entry-type>java.lang.Boolean</env-entry-type>
    <env-entry-value>false</env-entry-value>
</env-entry>

61.5 Current Limitations of Web Clipping

When you use Web Clipping, you should be aware of the following limitations.

• If the site that you intend to clip uses a large amount of JavaScript to manipulate cookies or uses the document.write JavaScript method to modify the HTML document being written, then you may not be able to clip content from the site.

• When you integrate with partner applications (by using mod_osso), you cannot clip directly through those partner applications in an authenticated manner. However, you can use partner applications through the external application framework.

• You cannot use the Web Clipping portlet to clip Oracle Portal pages and ADF pages. As a workaround, reregister the same producer in the destination portal and edit the portal manually.

• You cannot use the Web Clipping portlet to clip a web page that contains multiple frames, that is, a frameset.

• Note the following about Web Clipping and the use of a CSS:

  • If a web page contains multiple portlets that use a CSS, then they should not conflict if the CSS uses distinct style names, such as OraRef, to specify a style within an HTML tag, rather than using an HTML tag name, such as <A>, as the name of the style.

  • If one portlet uses a CSS, and that CSS overwrites the behavior of HTML tags by using the name of the tag, such as <A>, as the name of the style, and a second portlet on the same page does not use a CSS, the second portlet is affected by the style instructions of the CSS of the first portlet.

  • If two portlets on the same page use a different CSS and each CSS overwrites the behavior of HTML tags by using the name of an HTML tag, such as <A>, as the name of the style, then the style that is displayed depends on the browser.

• Web Clipping checks for globalization support settings in the following way:

  1. Web Clipping checks the Content-Type in the HTTP header for the charset attribute. If this is present, then it assumes that this is the character encoding of the HTML page.

  2. If the charset attribute is not present, then Web Clipping checks the HTML META tag on the page to determine the character encoding.

  3. If the HTML META tag is not found, then Web Clipping uses the charset in the previous browsed page. If this is the first page, then it defaults to the ISO-8859-1 character encoding.

  4. If the value of the charset for Content-Type or META tag is not supported (for example, if the charset was specified as NONE), then Web Clipping uses the default character set, ISO-8859-1, not the charset in the previously browsed page.

• To use the Web Clipping portlet, you must use Netscape 7.0 or later, Microsoft Internet Explorer 5.5 or later for Windows 2000, or Microsoft Internet Explorer 6.0 or later for Windows XP. If you use browser versions older than these, then you may encounter JavaScript errors.

61.6 Troubleshooting Web Clipping

This section provides information to help you troubleshoot problems you may encounter while using Web Clipping.

Encountered "x" at line n, column n. Was expecting one of : "x", "y" ...

Parser error message written to the log file.

Problem

The web content displayed in the Web Clipping portlet contains invalid HTML or JavaScript.

Solution

This is a site-specific issue, not a Web Clipping error. Contact the site's administrator for assistance.