Note:
Before you can add a pagelet to any web application, you must deploy and configure the resource and pagelet in Pagelet Producer as described in Deploying Portals, Templates, Assets, and Extensions in Oracle Fusion Middleware Administering Oracle WebCenter Portal.
Topics:
Once you have deployed a pagelet, you can:
Insert pagelets into non-proxied pages using a simple JavaScript function.
Retrieve information about resources and pagelets from Pagelet Producer, and inject pagelets into proxied and non-proxied pages using Pagelet Producer’s REST APIs.
Automatically resize the IFrame that encapsulates pagelet content using the pagelet inject function.
This section includes the following topics:
You can insert pagelets into non-proxied pages using a simple JavaScript function.
To activate this feature, add the following HTML snippet in the <HEAD> section of the page.
<script type="text/javascript" src="http://proxy:port/pagelets/inject/v2/csapi"> </script>
This script injects all CSAPI and pagelet inject functions into the page to display the pagelet. One of the sections injected is the following function:
function injectpagelet(library, name, iframe_options, params, context_id, element_id, is_in_community, chrome, forward_params)
{
...
}
This function injects a pagelet as a widget into the parent page. The method interface uses the following parameters:
library: Required. A string representing the library name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.
name: Required. A string representing the name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.
iframe_options: Specifies whether to use IFRAME around the pagelet content. Sample IFRAME options: iframe width=100% height=auto frameborder=0. If omitted or left blank, the pagelet content is rendered inline.
params: The pagelet parameters in query string format. For example, 'param1=value1¶m2=value2¶m3=value3'.
context_id: The external identifier of the pagelet instance, used to scope preferences on the Pagelet Producer server. Must be an integer.
element_id: The HTML element ID in which the pagelet content is injected. If omitted or left blank, the pagelet content is injected using document.write() when the injectpagelet call is evaluated.
is_in_community: Specifies whether this pagelet is on a community or group page. If the value is set to true, it sends the context_id in the community ID header to the pagelet. Defaults to false.
chrome: Specifies the name of the chrome template to use for WSRP/JPDK pagelets. To suppress chrome, use a value of none.
forward_params: Specifies whether to forward query string arguments from the consuming page to the back-end server. To suppress this functionality, use a value of false.
Note:
These arguments are positional; they must be provided in the given order. If you do not want to specify a particular argument, but do want to specify an argument that follows it, you must pass in an empty value ('') for the former. All arguments are optional except for library and name.
The script also creates a new <div> with a unique name that includes a reference to the injectpagelet function. Several examples are shown below:
<div>
<script type="text/javascript">
injectpagelet('library', 'name');
</script>
</div>
<div>
<script type="text/javascript">
injectpagelet('library', 'name', 'iframe', 'payload', 'param1=value1¶m2=value2¶m3=value3');
</script>
</div>
<div>
<script type="text/javascript">
injectpagelet('library', 'name', 'iframe width=100% height=200', 'payload');
</script>
</div>
The injecteditor function lets you add preference editors that enable users to set personal and shared preferences for pagelets that support this capability. This functionality is analogous to personalization and customization functionality in WebCenter Portal.
injecteditor(library, name, type, iframe_options, context_id, element_id, is_in_community, chrome)
where:
library: Required. The library name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.
name: Required. The name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.
type: The editor type. This argument supports these values: 'admin', 'pagelet', 'community'. In case of the 'community' argument, context_id is sent to pagelet in the community ID CSP header.
iframe_options: Specifies whether to use IFRAME around the pagelet editor content. Sample IFRAME options: iframe width=100% height=auto frameborder=0. If omitted or left blank, the editor content is rendered inline.
context_id: The external identifier of the pagelet instance, used to scope preferences on the Pagelet Producer server. Must be an integer.
element_id: The HTML element ID in which the pagelet content is injected. If omitted or left blank, the pagelet content is injected using document.write() when the injecteditor call is evaluated.
is_in_community: Specifies whether this pagelet is on a community or group page. If the value is set to true, it sends the context_id in the community ID header to the pagelet. Defaults to false.
chrome: Specifies the name of the chrome template to use for WSRP/JPDK pagelets. To suppress chrome, use a value of none.
Note:
These arguments are positional; they must be provided in the given order. If you do not want to specify a particular argument, but do want to specify an argument that follows it, you must pass in an empty value ('') for the former. All arguments are optional except for library and name.
REST stands for Representational State Transfer and is a simple way of providing APIs over HTTP. The basic principles of REST are:
API URLs point to the resource rather than a generic method endpoint
Requests use standard HTTP verbs for simplified CRUD methods. This is a read-only API and allows GET requests only.
Every request returns a full representation of the object retrieved (pagelet or resource)
Pagelet Producer REST APIs let you:
Inject pagelets into non-proxied pages, allowing Pagelet Producer to act as a portlet provider for Oracle WebCenter Interaction, Oracle WebLogic Portal, or other third-party portals
Allow remote Web services to retrieve information about resources and pagelets from Pagelet Producer
This section contains the following topics:
The pagelet inject URL can be used in portals to specify the location of a remote portlet (this is how a pagelet can be used as a portlet). The inject URL can also be used as the source attribute of an IFrame tag in any HTML page.
The URL must use the following format:
http://host:port/pagelets/inject/v2/pagelet/libraryname/pageletname?content-type=html
where libraryname and pageletname refer to the library and pagelet configured in Pagelet Producer.
Note:
When using the pagelet inject API as the URL for a Portlet Web Service in Oracle WebCenter Interaction, you must switch "pagelet" to "portlet" in the URL. For example, the above URL would become:
http://host:port/pagelets/inject/v2/portlet/libraryname/pageletname?content-type=html
The query string arguments to the above call define how the pagelet is to be returned. The following parameters are defined:
instanceid: Optional. The instance ID of the pagelet, used to uniquely identify the pagelet on the page to facilitate inter-pagelet communication. Must be unique to the page.
context: Optional. The external identifier of the pagelet instance, used for scoping preferences on the Pagelet Producer server. Must be an integer.
content-type: The return type. Three types are supported:
javascript: Returns injectable code.
html: Returns the pagelet markup with its associated PTPortlet object.
iframe: Returns an IFrame that points back to the inject api, filling the IFrame with the pagelet content, instead of directly inline with the page. The IFrame can be styled by providing a set of query string parameters.
| Parameter | Description | Default |
|---|---|---|
|
ifwidth |
Sets the width of the IFrame; can be specified in percent '%' or pixels 'px', for example: ifwidth=500px. Can be set to 'auto' to automatically resize the IFrame to fit the content within. For details, see How to Use Automatic Resizing with IFrames. |
100% |
|
ifheight |
Sets the height of the IFrame; can be specified in percent '%' or pixels 'px', for example: ifheight=500px. Can be set to 'auto' to automatically resize the IFrame to fit the content within. For details, see How to Use Automatic Resizing with IFrames. |
No default |
|
ifborder |
Sets the border of the IFrame. |
'none' |
|
ifalign |
Sets the align rule within the IFrame, for example: ifalign=center. |
No default |
|
ifdesc |
Sets the description of the IFrame. |
No default |
|
ifmarginheight |
Sets the margin height; can be specified in percent '%' or pixels 'px', for example: ifmarginheight=500px. |
No default |
|
ifmarginwidth |
Sets the margin width; can be specified in percent '%' or pixels 'px', for example: ifmarginwidth=500px. |
No default |
|
ifscrolling |
Sets the scrollbars of the IFrame. Accepted values: yes/no/auto. |
auto |
|
ifstyle |
Sets the CSS style of the IFrame |
No default |
|
ifclass |
Sets the CSS class of the IFrame. |
No default |
csapi: Optional. Sets whether the CSAPI will be included with the pagelet response (true or false). Including the CSAPI is optional, but the pagelet included in the response relies on the CSAPI libraries being present on the page where the pagelet is to be rendered. If csapi=false, then the CSAPI libraries must be included with the parent page (usually in the HEAD section).
onhtttperror: Optional. When a pagelet request results in a 403, 404 or any other error code, Pagelet Producer can forward the error code and the error page itself to the browser for display to the user. The onhttperror parameter accepts the following values:
comment (default): Pagelet Producer will create an HTML comment in place of the failing pagelet (the failing pagelet will simply not be displayed).
inline: The pagelet error along with the server error page will be displayed inline where the pagelet would normally be shown on the page.
fullpage: The http error will consume the whole page. This mode is only available if Pagelet Producer controls the parent page.
inline-refresh: Optional. Valid values are true or false (default). If the inline-refresh option is set to true, Pagelet Producer does not use an iFrame to embed pagelet markup onto the page. When the user interacts with the pagelet, markup updates are done inline, hence the term 'inline-refresh'. To achieve this, Pagelet Producer re-writes the URLs in the pagelet markup to use a JavaScript method call instead. That is, when the user clicks on a link or submits a form request to the backend, it's done by JavaScript on the browser and then the response is dynamically injected.
The inline-refresh option works well for relatively simple HTML markup. If the pagelet exposes a very rich UI, such as an ADF task flow, inline-refresh may not work well or may simply break. Consequently, the inline-refresh option is set to false by default (that is, inject pagelet markup in an iFrame).
The following example URL points to the linkspagelet in the samples library:
http://host:port/pagelets/inject/v2/pagelet/samples/linkspagelet?content-type=iframe&csapi=true&ifheight=123px&ifclass=myclass
This URL should result in markup similar to the code below.
Note:
The IFrame source points back to the inject API, but this time the content-type parameter is set to html. This feature adds an additional step in the pagelet retrieval. The csapi parameter is set to true on the subsequent call to get the IFrame contents so that the required CSAPI content is included in the IFrame (if this was not the case, JavaScript resolve errors would be returned because the pagelet code cannot access any CSAPI script included outside the IFrame).
<html> <head> </head> <body> <iframe frameborder="none" class="myclass" width="100%" height="123px" scrolling="auto" src="http://proxy:port/inject/v2/pagelet/samples/linkspagelet?asdg=asdfgas¶m=true&content-type=html&jswrap=false&csapi=true"> <html> <head> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsutil/LATEST/PTUtil.js" type="text/javascript"> </script> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsutil/LATEST/PTDateFormats.js" type="text/javascript"></script> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsxml/LATEST/PTXML.js" type="text/javascript"></script> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsportlet/LATEST/PTPortletServices.js" type="text/javascript"></script> </head> <body> <div id="pt-pagelet-content-1" class="pagelet-container" style="display: inline;"> <span xmlns:pt="http://www.xmlns.oracle.com/xmlschemas/ptui/"> Pagelet links: <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/headpagelet1.html">The first pagelet</a> <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/headpagelet2.html">The second pagelet</a> <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/csapipagelet.html">The csapi pagelet</a> <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/linkspagelet.html">This pagelet</a> <br/> </span> </div> </body> </html> </iframe> </body> </html>
Two REST APIs are available to retrieve data from Pagelet Producer:
Pagelet API: Allows remote applications to retrieve pagelet data from Pagelet Producer. (See the example for "All Pagelets" and "Pagelets by Library Name.")
Resource API: Allows remote applications to retrieve resource data from Pagelet Producer. (See the example for "All Resources" and the example for "Resource By Name.")
The base URL for all requests is http://host:port/pagelets/restservice/pageletproducer/.
Example: All Pagelets
http://host:port/pagelets/restservice/pageletproducer/pagelets/ http://host:port/pagelets/restservice/pageletproducer/pagelets/?format=xml
Example: Pagelets By Library and Name
http://host:port/pagelets/restservice/pageletproducer/pagelet/libraryname/pageletname/ http://host:port/pagelets/restservice/pageletproducer/pagelet/libraryname/pageletname/?format=xml
Example: All Resources
http://host:port/pagelets/restservice/pageletproducer/resources/ http://host:port/pagelets/restservice/pageletproducer/resources/
Example: Resource By Name
http://host:port/pagelets/restservice/pageletproducer/resource/name http://host:port/pagelets/restservice/pageletproducer/resource/name/?format=xml
The Pagelet Producer pagelet inject API can automatically resize the IFrame that encapsulates pagelet content. The resizing is done so that the IFrame stretches to fit the content within. To use this feature, the ifwidth and ifheight parameters must be set to 'auto' as shown in the example below:
http://proxy:port/inject/v2/pagelet/samples/linkspagelet?content-type=iframe&csapi=true&ifheight=auto&ifwidth=auto&ifclass=myclass
In addition, this feature relies on an external page on the same domain as the consumer page. This page is included into the pagelet IFrame as an internal hidden IFrame. This page collects the sizing information and passes it on to the parent consumer page. This page must be deployed in the same directory as the consumer page.
The example below resizes the pagelet IFrame after it finishes loading. To add dynamic auto-resizing capabilities to user interaction activities after the initial load, simply add more event listeners for mouse and keyboard events.
<html>
<head>
<title>Resizing Page</title>
<script type="text/javascript">
function onLoad() {
var params =window.location.search.substring( 1 ).split( '&' );
var height;
var width;
var iframe;
for( var i =0, l =params.length; i < l; ++i ) {
var parts =params[i].split( '=' );
switch( parts[0] ) {
case 'height':
height =parseInt( parts[1] );
break;
case 'width':
width =parseInt( parts[1] );
break;
case 'iframe':
iframe =parts[1];
break;
}
}
window.top.updateIFrame( iframe, height, width );
}
if (window.addEventListener) {
window.addEventListener("load", onLoad, false)
}else if (window.attachEvent) {
window.detachEvent("onload", onLoad)
window.attachEvent("onload", onLoad)
}else {
window.onload=onLoad
}
</script>
</head>
<body>
</body>
</html>
Use the Page Editor to add a pagelet to a portal page. By default, pagelets appear in the Mash-Ups folder in the Default Portal Catalog. To add a pagelet to a page, navigate to the pagelet in the resource catalog and select it.
For detailed information about how to add resources to pages in a portal, see Adding and Editing Resource Catalog Components on a Page in Oracle Fusion Middleware Building Portals with Oracle WebCenter Portal
To configure a pagelet within a page, view the page in Edit mode and click the View Actions menu for the pagelet, then select Parameters.