Disc API

Class PortletSource

public class PortletSource

The PortletSource API is an Ajax-based front end to the Portlet Publishing feature of WLP. This feature provides a mechanism for dynamically injecting interactive, published portlet instance markup into arbitrary host HTML pages, though browser security restrictions and the XMLHttpRequest-based subsystem on which this API is based require that the host HTML and portal be served from the same domain, according to the browser-enforced same-origin policy.

This API handles communication with portlet publishing contexts to request and consume portlet instances. Use of this API begins by acquiring a PortletSource instance using the static get factory method as follows:

     var publishingContext = "/<webapp>/appmanager/<portal>/<desktop>";
     var source = bea.wlp.disc.publishing.PortletSource.get(publishingContext);

The value of the publishingContext variable in the above example can be obtained from the Portal Admin Tools, and may address either streaming- or file-mode portals. The factory method returns the same PortletSource instance for a given publishing context value each time it is called. The publishing context matches the publishingContext parameter passed to Portlet Publishing Service URLs, as described elsewhere (see references below).

Once a PortletSource instance has been obtained, that instance can be used to surface published portlets in the current document by calling its render method, as follows:

     source.render({ portlet: "myInstanceLabel", to: "myElementId" });

In this example, the portlet arg is the instance label of a portlet available in the specified publishing context, and the to arg is the id of an HTML element within the current document. Typically it works well for this element to be an HTML div tag, but other element types will work -- your mileage may vary when using other tag types, given the partculars of individual browsers, so it's recommended that div tags be used whenever possible.

The execution of the render call proceeds asynchronously, based on the Disc XIE subsystem. Because this API is implemented on the XIE backbone, XIE events are fired and can be used to monitor the progress of and/or respond to the loading of published portlet content.

Each invocation of the render method of a PortletSource instance results in an independent request to the server. Multiple portlets can be batched together in a single render operation so that the number of requests per page is minimized when multiple portlets are required on a single page. This behavior can also be used to tailor the behavior of the host page's published portlet loading to optimize page loading on a per-portlet/portlet-group basis.

The following is an example of loading multiple portlets in a single render operation:

     source.render([
         { portlet: "myInstanceLabel1", to: "myElementId1" },
         { portlet: "myInstanceLabel2", to: "myElementId2" },
         { portlet: "myInstanceLabel3", to: "myElementId3" }
     ]);

In this example, a single request is made to the server to load content from three published portlets. The consequence of this is that a single response is returned to the client containing all three portlets' contents, which means that, before the client can be fully updated, the server must have completed rendering all three portlets' markup. This strategy can be useful when trying to reduce the impact of the "1 + n" request problem when initializing the host page (where the "1" request loads the host page, and the "n" represents each portlet being loaded after the initial page load; in this example, 4 potential requests are reduced to a total of 2).

Multiple concurrent render calls can also be made, as needed. For example:

     source.render({ portlet: "slowPortlet1", to: "myElementId1" });
     source.render([
         { portlet: "fastPortlet2", to: "myElementId2" },
         { portlet: "fastPortlet3", to: "myElementId3" }
     ]);

This style may be useful when one or more of the portlets on the page (in this example, the portlet with label "slowPortlet1") takes a non-trivial amount of time to render on the server; the concurrent request style can mitigate this by loading the quickly responding portlets as soon as possible in a single batched request, while allocating the potentially slowly loading portlet its own request. Of course, browser XHR implementations may limit how many concurrent requests may be simultaneously active given their own, internal request queueing implementation details.

Multiple PortletSource instances can be simultaneously used to surface published portlets within the same document, as well. This can be useful to integrate or mashup available content from multiple portals within the host document. For example:

     var $PortletSource = bea.wlp.disc.publishing.PortletSource;
     var source1 = $PortletSource.get("/<webapp>/appmanager/<portal>/<desktop1>");
     var source2 = $PortletSource.get("/<webapp>/appmanager/<portal>/<desktop2>");
     source1.render({portlet: "portlet1", to: "myElementId1"});
     source2.render([
         { portlet: "portlet2", to: "myElementId2" },
         { portlet: "portlet3", to: "myElementId3" }
     ]);

Portlets aggregated in this manner should be especially well-behaved in aggregated contexts, and the developer surfacing portlets from multiple sources in the same document should be keenly aware of the target portlets' impact on the global document execution context. Best practices in namespacing should be rigorously observed for all aspects of the surfaced portlet including HTML element ids, script variable naming, and so on. Namespacing in a single portal context is complicated enough; when aggregating from multiple portals, however, the risk of naming collisions is amplified. In particular, while the uniqueness of portlet instance labels is enforced within the context of a single portal, this mechansim allows the co-mingling of portlets with identical instance labels from different sources; if this is attempted, due diligence should be applied in ensuring that multi-source aware namespacing is applied by all involved portlets.

Note that multiple attempts to render a single published portlet from a single source should be stable, so long as each attempt renders to the same target HTML element. Re-mapping the same instance to multiple target elements either across multiple render calls or during a single, aggregate render call is not supported, and may result in undefined behavior. Similarly, mapping multiple instances to a single target element may result in undefined behavior and is not supported.

Attempting to publish portlets through this API from publishing contexts with URL compression enabled is not supported.

Portlets published through this API will have their associated render dependencies applied to the host document, although, at this time, associated script dependencies are not propagated or supported. Integrated render dependencies are designed to only be integrated and executed a single time per document, no matter how many times the portlet defining them is explicitly rendered.

Lastly, PortletSource.render should only ever be invoked once the document is known to have completely loaded. As with all cross-browser DOM manipulation APIs, undefined/unsupported results may occur if invoked before the inital page load has completed and the base DOM has materialized in full. As such, any code invoking this API should only be executed from appropriate window or toolkit onload events (or in response to user actions at some later time).

For in-depth coverage of this API, see the WLP Client-Side Development Guide.

See Also:: bea.wlp.disc.xie.Events

Method Summary

public static bea.wlp.disc.publishing.PortletSource get(publishingContext)
This factory method returns a PortletSource instance for the specified publishing context.

public void render(spec)
Renders the specified portlet specification.

Method Detail


Method Summary
`public static bea.wlp.disc.publishing.PortletSource`	`get(publishingContext)` This factory method returns a `PortletSource` instance for the specified publishing context.
`public void`	`render(spec)` Renders the specified portlet specification.


Method Detail

get

public static bea.wlp.disc.publishing.PortletSource get(publishingContext)

This factory method returns a PortletSource instance for the specified publishing context. See class-level documentation for more information on this method's use.

Parameters:: string publishingContext - The publishing context for which a PortletSource instance is desired
Returns:: bea.wlp.disc.publishing.PortletSource - The PortletSource instance associated with the specified publishing context

render

public void render(spec)

Renders the specified portlet specification. See class-level documentation for examples and details.

Parameters:: object|Array spec - A portlet specification object or array of such specifiactions, where each specification object contains both portlet and to values, as described above