Skip Headers
Oracle® Fusion Middleware Client-Side Developer's Guide for Oracle WebLogic Portal
10g Release 3 (10.3.4)
Part Number E14229-02
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

3 The WLP Disc Framework

This chapter discusses the Dynamic Interface SCripting (Disc) framework. Sometimes used in combination with the WLP REST API, Disc provides a client-side JavaScript API to assist with developing rich, interactive portlets and portal applications. Disc helps you write Ajax-enabled portlets that enable rich, interactive portal web application features.

This chapter includes these topics:

3.1 What is Disc?

Disc provides a client-side, JavaScript, object-oriented programming framework for handling events, making asynchronous portlet updates, and for accessing portal context objects. Like their Java-based WLP API counterparts, Disc context objects encapsulate descriptive portal information, such as portlet positions within placeholders, titles, labels, and so on. The information returned in context objects can be used as parameters to REST commands to modify the portal. For instance, the WLP feature called placeable movement (drag and drop portlets) is implemented using Disc and REST features (see "Enabling Placeable Movement" in Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal).

Tip:

For reference documentation see the Oracle Fusion Middleware REST API Reference for Oracle WebLogic Portal and Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

The Asynchronous Desktop Mode and DVT features both use Disc, as illustrated in Figure 3-1. If you enable either Asynchronous Desktop Mode or DVT for a portal desktop, Disc is implicitly enabled.

Figure 3-1 Features That Depend on Disc

Description of Figure 3-1 follows
Description of "Figure 3-1 Features That Depend on Disc"

The DVT flag enables the placeable movement (drag and drop portlets) feature for the portal desktop. Asynchronous desktop rendering and placeable movement are both discussed in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.

3.2 Enabling Disc

To use Disc in client-side portal code, you have to enable it first. You can enable Disc in Oracle Enterprise Pack for Eclipse (OEPE) or in the WebLogic Portal Administration Console. You can also use Disc outside the context of a portal.

This section includes these topics:

3.2.1 What Enabling Disc Means

When Disc is enabled, you have access to the following WLP client-side development features:

  • Portal-Aware XHR (XMLHttpRequest) objects – If you are familiar with Ajax, then you know that XMLHttpRequest (XHR) objects are used to make asynchronous requests to the server. Because the browser's native XHR object is designed to operate in the context of an entire web page, it does not work well in a portal environment where the page is composed of many separate portlets. Disc provides a portal-aware extension of XHR that makes requests that allow portlet markup to be updated asynchronously. The term portal-aware means that when the Ajax request is sent to the server from a portlet, the request can fire events, if required, and render its own view for further processing on the client. See Section 3.4, "Using Portal-Aware XMLHttpRequest to Update Portlets".

    The portal-aware XHR object, bea.wlp.disc.io.XMLHttpRequest is described in detail in Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

  • Context Objects – Disc lets you work with context objects that encapsulate information about a portal, such as the portlet placeholder information, titles, labels, and so on. Context objects are generally read-only, and let you obtain information that you can use to create client-side interactivity and to pass to REST commands to update the portal.

    The set of context objects in the bea.wlp.disc.context module are described in detail in the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

  • XIE – The XHR Interaction Engine (XIE) provides the infrastructure for handling asynchronous requests, interportlet communication, and event handling. For instance, when asynchronous rendering is enabled for a desktop, XIE enables interportlet communication (IPC) to work correctly. When a request is made from a portlet, markup is automatically returned for that portlet and any portlet that is affected by the request through IPC.

    The set of XIE objects in the bea.wlp.disc.xie module are described in detail in the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

  • Event Handling – Disc provides event handling mechanisms that work as callback functions and that can carry payloads. Events are tied to the "life cycle" of asynchronous portlet requests. This means you can use events to trap information before a request is sent or before a response is processed by the client.

    For detailed information on the Event object in the bea.wlp.disc.event module, see Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

3.2.2 Enabling Disc in Oracle Enterprise Pack for Eclipse

To enable Disc for a portal desktop in Oracle Enterprise Pack for Eclipse, set Disc Enabled to true in the desktop Properties view, as shown in Figure 3-2.

Figure 3-2 Enabling Disc in Oracle Enterprise Pack for Eclipse

Description of Figure 3-2 follows
Description of "Figure 3-2 Enabling Disc in Oracle Enterprise Pack for Eclipse"

3.2.3 Enabling Disc in the Administration Console

To enable Disc in the Administration Console:

  1. In the Portal Resources tree, select Portals and navigate to a desktop.

  2. Select the Details tab.

  3. Click Advanced Properties (Figure 3-3) and use the dialog to set Enable Disc to true.

Figure 3-3 Enable Disc

Description of Figure 3-3 follows
Description of "Figure 3-3 Enable Disc"

3.2.4 Using Disc Outside of a Portal

The WLP Portlet Publishing feature uses Disc outside of a portal. Portlet Publishing lets you render portlets in any HTML page. For more information on Portlet Publishing, see Chapter 5, "Portlet Publishing"

3.3 Using Portal-Aware XMLHttpRequest to Retrieve Data from a Non-Portal Source

The standard XMLHttpRequest object, familiar to Ajax developers, can be used to update discrete amounts of data within a portlet. The Disc API class, bea.wlp.disc.io.XMLHttpRequest, is an extension of the standard XMLHttpRequest class. WLP's XMLHttpRequest allows you to make asynchronous, incremental calls to the portal server, and supports portal features such as interportlet communication and WSRP. However, you can also use the portal-aware XHR in the same way you use a standard XHR. Like a standard XHR request, a portal-aware XHR request can be used from any JSP portlet page to retrieve any arbitrary data, which can then be inserted into the portlet.

3.3.1 Use Case

For an example use case, you could write a portlet that includes an auto-complete search form. When a user types text in the search field, the portlet sends portal-aware XHR requests to the server to retrieve suggestions for the user. In this process, the portlet UI does not refresh itself, except for the suggestions shown in the text field.

3.3.2 Example

In Example 3-1, a portal-aware XHR object is instantiated and used to asynchronously retrieve data from a non-portal source. This code is intended to be embedded in a JSP page.

Example 3-1 Using Portal-Aware XHR to Retrieve Data from a Non-Portal Source

<script type="text/javascript">
    var dataUrl = 'data.json';
    var xmlhttp = new bea.wlp.disc.io.XMLHttpRequest();
    xmlhttp.onreadystatechange = function() {
        if ((xmlhttp.readyState == 4) && (xmlhttp.status == 200)) {
            var data = eval('(' + xmlhttp.responseText + ')');
            var table = document.getElementById('data');
            for (var i = 0; i < data.length; i++) {
                // insert rows into "data" table by referencing properties of
                // data[i] objects.
            }
        }
    }
    xmlhttp.open('GET', dataUrl, true);
    xmlhttp.send();
</script>

3.4 Using Portal-Aware XMLHttpRequest to Update Portlets

Portal-aware XMLHttpRequest allows client-side JavaScript code to interact with the portal framework on the server on behalf of a portlet. When a portal-aware XHR call is made to the server, the request is processed by the portal, which decides what to do with the request. The portal may decide to invoke a given portlet and provide it with the appropriate context, such as user properties, portlet preferences, and request and response objects. Because the portal manages dependencies between portlets, interportlet communication is possible with portal-aware XHR.

3.4.1 Use Cases

Two use cases for using portal-aware XHR are:

  • A portlet wants to implement a multi-step wizard process, replacing the current form with a new form after each form submission and without completely re-rendering the portlet.

  • When a user interacting with a portlet selects a check box for a product ID, the portlet fires an event on the server side. Other portlets handle this event, fetch product related information from a back-end data source, and render that information.

As a developer, you have the option of using the WLP-specific XMLHttpRequest object (bea.wlp.disc.io.XMLHttpRequest) to update portal-specific content. When you make a request through this object, features such as IPC and WSRP are supported. For detailed information on the portal-aware XHR class, see the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

To enable portal-aware XHR in Oracle Enterprise Pack for Eclipse, follow the instructions in the section Section 3.2.2, "Enabling Disc in Oracle Enterprise Pack for Eclipse".

3.4.2 Example

Example 3-2 is basically the same as Example 3-1. The difference is that Example 3-2 refers to a portlet as the source of the data. This example code is expected to be embedded directly in a JSP page.

Example 3-2 Using Portal-Aware XHR to Update Portlets

<%@ taglib prefix="render" uri="http://www.bea.com/servers/portal/tags/netuix/render" %>
<render:jspContentUrl contentUri="/path/to/portlet/data.jsp" forcedAmpForm="false" var="dataUrl"/>

<script type="text/javascript">
    var dataUrl = '${dataUrl}';
    var xmlhttp = new bea.wlp.disc.io.XMLHttpRequest();
    xmlhttp.onreadystatechange = function() {
        if ((xmlhttp.readyState == 4) && (xmlhttp.status == 200)) {
            var data = eval('(' + xmlhttp.responseText + ')');
            var table = document.getElementById('data');
            for (var i = 0; i < data.length; i++) {
                // insert rows into "data" table by referencing properties 
                // of data[i] objects.
            }
        }
    }
    xmlhttp.open('GET', dataUrl, true);
    xmlhttp.send();
</script>

3.5 Using Context Objects

Disc lets you work with portal context objects on the client, using JavaScript. Context objects encapsulate certain information about portal components. Context objects contain information about the following portal components:

Disc content classes are loosely representative of the server-side PresentationContext classes and serve a similar function in client-side programming. The set of context objects in the bea.wlp.disc.context module are described in detail in the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

Note:

Only context objects for visible components are available; context objects for non-visible components such as books peer to the current book or hidden portlets are not available through the Disc APIs.

Disc context objects are generally available only after the entire HTML page has loaded. As a best practice, do not attempt to use context objects from inline script blocks. Instead, register an on-load handler that specifies interaction with context objects. For example, the code in Example 3-3, when placed inline in a portlet JSP, results in an error:

Example 3-3 Wrong Way to Access a Context Object

//portlet will be null
var portlet = bea.wlp.disc.context.Portlet.findByLabel("myPortletLabel"); 
var title = portlet.getTitle(); // error

However, if you add the same code in a Dojo (for example) on-load function, the code works as expected:

Example 3-4 Recommended Way to Access a Context Object

dojo.addOnLoad(function() {
    var portlet = bea.wlp.disc.context.Portlet.findByLabel("myPortletLabel");
    var title = portlet.getTitle();
});

Example 3-5 illustrates a simple debugging example. The best practice is to place this code in a render dependencies file. See Section 4.3, "Creating a Render Dependencies File" for more information.

Example 3-5 Simple Debugging Example

dojo.addOnLoad(function() {
     var portlets = bea.wlp.disc.context.Portlet.getAll();
     for (var i = 0; i < portlets.length; i++) {
         bea.wlp.disc.Console.debug(portlets[i]);
     }
});

Example 3-6 presents another example that uses context objects.

Resources from render dependencies files are always included for a portlet regardless of mode or state (except for minimized, which is a special case). If a portlet has a general function that tries to inject content into a portlet that always runs when loaded from a render dependencies file (attached to an onload handler for example), the function should probably only try to do the content injection when the portlet is in "normal view" mode. Example 3-6 is intended to be loaded from a render dependencies file.

Example 3-6 Using Disc to Determine Portlet State

function createDataTables(label) {
    var portlet = bea.wlp.disc.context.Portlet.findByLabel(label);
    if (portlet.getWindowMode() == "view") {
        // retrieve data and create corresponding tables...
        if (portlet.getWindowState() == "maximized") {
            // create table with extended details
        }
        else {
            // create table with common details 
        }
    }
}

Tip:

The bea.wlp.disc.context.Portlet object has a refresh() method that you can use to refresh the contents of a portlet through client-side code. For details, see the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

3.6 The XMLHttpRequest Interaction Engine

The Disc module bea.wlp.disc.xie defines public APIs for Disc's XMLHttpRequest Interaction Engine (XIE). XIE is the client-side foundation for Ajax-driven interactions with WebLogic Portal. XIE is also the platform on which various other Ajax-based, public Disc APIs are implemented, including:

The XIE API is divided into two main areas:

For more information on this classes described in this section, see the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

3.7 Event Handling

The bea.wlp.disc.xie.Events object contains the set of public, global events that are fired during XIE's WLP interaction lifecycle. The interaction lifecycle involves setting up and executing an Ajax request to the WLP server, receiving a response, and subsequently processing the response. WLP Ajax responses are encoded in an internal JSON format (the form of which is reserved and subject to change), and XIE manages the evaluation and handling of the body of these responses. The suite of public XIE events provides public access to key moments of interest during this lifecycle; listening code can use these event hooks to respond to or even influence the outcome of the interaction. For more information on this class, see the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

  1. OnPrepareUpdate – Fired when an interaction has been initiated, but before the request is made. This event can be cancelled; cancellation terminates the interaction without making the underlying request.

  2. OnHandleUpdate – Fired immediately after XIE receives the response, but before processing has begun.

  3. OnRedirectUpdate – Fired if the server is forcing the client to perform a redirect; processing will complete as soon as possible and then a client-side redirect is performed.

  4. Then, for each piece of response markup returned by the server, the following events are fired:

    1. OnPrepareMarkup – Fired before converting a response markup fragment into a DOM subtree; this event fires once for each markup fragment that was returned in the response.

    2. OnPrepareContent – Fired immediately after converting a markup fragment into a DOM subtree, but before doing additional processing (such as rewriting anchor hrefs and form actions); this event fires once for each markup fragment that was returned in the response.

    3. OnInjectContent – Fired immediately after injecting the fully processed (for example, rewritten) DOM subtree into the document, but before executing any scripts associated with that content; this event fires once for each markup fragment that was returned in the response.

  5. OnCompleteUpdate – Fired after XIE has completed all response processing for the interaction, including the execution of any scripts defined by the markup updated during the interaction

  6. OnError – Fired any time an error occurs during interaction processing; processing may or may not continue once an OnError event has fired.

Each event delivers a payload object to its listeners when the event is fired. The type and capabilities of each payload object differ from event to event. See the documentation for each individual event for more information about specific event payloads in the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

3.8 Manipulating URIs On the Client

Disc provides an API for manipulating URIs on the client. This feature lets you manipulate URIs that have been rewritten for XmlHttpRequests (XHR) and Web Services for Remote Portlets (WSRP). URI manipulation consists of parsing the URI, optionally replacing template keys with values, and performing CRUD (create, read, update, delete) operations on the components of the URI.

3.8.1 Background

The use of XHR in portal applications results in URI strings that have been rewritten to become JavaScript pseudo-protocol links. These links are the result of client-side URL rewriting performed by the Disc framework to support Ajax enabled portlets and desktops. For example, an HREF attribute value such as:

http://localhost:7001/myApp?portletID=1001

could be present in the markup of a web page in a rewritten form, such as:

javascript:com.mystuff.update(http://localhost:7001/myApp?portletID=1001);
return false;

The URI manipulation API lets you write URI manipulation JavaScript code to parse a URI string in both its original form and in a form that has been rewritten into a JavaScript pseudo-protocol link.

In the case of WSRP portlets, you might need to write code that is reusable for either the local or remote case. The URI manipulation API identifies remote-proxied URIs and provides access to the target URI of the remote URI so that either or both URIs can be manipulated. When the URI is not remote, the URI manipulation framework recognizes that and handles the URI string with the default behavior for non-proxied URIs.

3.8.2 Using the URI API

The bea.wlp.disc.UriRewriter class and its subclasses provide mechanisms for manipulating target URIs. These URIs could be JavaScript pseudo-protocol links or proxy URIs for remote portlets. UriRewriter instantiates a bea.wlp.disc.Uri object, which includes all of the methods necessary to manipulate the components of a URI, including template replacement for templatized URIs. In the case of template replacement, you pass a map of template keys/values to the Uri constructor. For more information on templates, see the bea.wlp.disc.Uri package documentation in the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

The URI API provides a bea.wlp.disc.UriRewriterFactory class that you can use to select a UriRewriter class that recognizes the URI string of interest. If the URI passed to the constructor of this class is a recognized URI form, the class selects an appropriate UriRewriter. This pattern lets you write code to transparently manipulate a target URI whether or not the URI has been rewritten.

Note that a bea.wlp.disc.PageUrl class lets you create a portal page URL on the client, given the page label that you want to create a link to.

For additional details on the URI manipulation API and individual methods of the API, refer to the bea.wlp.disc.uri package in the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

3.9 Logging

One way to implement logging is to use the Firebug logging model. For information on this model, see http://getfirebug.com/logging.html. Both Firebug and Firebug Lite provide a global Console object that you can use to monitor logging output.

Disc provides a Console object (bea.wlp.disc.Console) that replicates the API found in the Firebug Console object. You can use this object anytime Disc is available. For information on the Disc Console object, refer to bea.wlp.disc.Console in the Oracle Fusion Middleware Disc API Reference for Oracle WebLogic Portal for FreeBSD - x86.

3.9.1 Example

Example 3-7 shows a simple example of how to set up a listener and send messages through the Console object. All messages logged to the Console are passed to each listener on the object. The listener function can be passed the following arguments when the debug call is made:

  • op – "debug"

  • args – ["label=", "myPortlet"]

This configuration will output the following line of HTML text into a div named myConsoleOutput, which needs to have been previously defined somewhere on the page:

DEBUG: label=myPortlet

Example 3-7 Simple Example: Setting Up a Console Listener

bea.wlp.disc.Console.addListener(function(op, args) {
    var output = document.getElementById("myConsoleOutput");
    output.appendChild(document.createElement("br"));
    output.appendChild(document.createTextNode(op.toUpperCase() + ": " +     args.join(",")));
});
// Sometime later...  Assume myPortlet.getLabel() returns "myPortlet"
bea.wlp.disc.Console.debug("label=", myPortlet.getLabel());
Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us