Namespace: PortletInit

PortletInit

Returned by the portlet.register method to provide functions for use by the portlet client.
Source:

Members

<static> constants

The PortletConstants object that provides useful field definitions for portlet mode, window state, and resource URL cacheability settings.
Source:

<static> portletModes

A string array containing the portlet modes that are defined for the portlet.

Note that even if a portlet mode is defined, it may not be allowed, depending on access rights or other conditions.

Properties:
Name Type Description
portletModes string[] The defined portlet mode values
Source:

<static> windowStates

A string array containing the window states that are defined for the portlet.

Note that even if a window state is defined, it may not be allowed, depending on access rights or other conditions.

Properties:
Name Type Description
windowStates string[] The defined window state values
Source:

Methods

<static> action(actParams, element) → {Promise}

Initiates a portlet action using the specified action parameters and element arguments.

When the action has successfully completed, a copy of the render state will be provided to the portlet client through the onStateChange listener function. A portlet client can modify this state object and pass it to the setRenderState function to update the render state.

However, it is also possible for the portal to completely refresh the page as a response to the action. This may occur in order to support portlets on the page that do not participate in the Portlet 3.0 Ajax support or due to configuration settings, for example.

If the page is completely refreshed, it will be rendered according to render parameters set on the server.

Action parameters are optional parameters attached to a action URL in addition to any render state values that may be present. Action parameters do not influence the render state.

The action parameters must be an object containing properties representing parameter names whose values must be an array of string values, as described under PortletParameters. All of the action parameters will be attached to the URL. Use of action parameters is optional.

If the element argument is present, it must refer to an HTML form to be submitted. The portlet hub will use this form to execute the action.

If the form element is specified, the encoding type must be 'application/x-www-form-urlencoded' or 'multipart/form-data'. The encoding type 'text/plain' is not supported.

If the encoding type is 'multipart/form-data', the submission method must be 'POST'. Form 'INPUT' elements of type 'FILE' are supported.

If the encoding type is 'application/x-www-form-urlencoded', the submission method can be either 'GET' or 'POST'. However, form 'INPUT' elements of type 'FILE' are not supported.

Specification of element is optional. If the element is not specified, the portlet hub will submit the action to the server by executing a 'POST' with an action URL containing any action parameters provided.

The parameters may be specified in either order, individually, or not at all. Examples of valid calls:
action();
action(actParams, element);
action(actParams);
action(element);

A portlet action is a blocking operation. To allow for orderly state transitions, the portlet hub does not allow this function to be used while a blocking operation is in progress. A blocking operation is considered to be in progress from the initial call until the final onStateChange event for that operation has been fired. See portlet for further information.

Parameters:
Name Type Description
actParams PortletParameters Action parameters to be added to the URL (optional)
element HTMLFormElement DOM element of form to be submitted (optional)
Source:
Throws:
  • Thrown if the input parameters are invalid
    Type
    TypeError
  • Thrown if a blocking operation is already in progress.
    Type
    AccessDeniedException
  • Thrown if a portlet ID is provided, but no onStateChange listener has been registered.
    Type
    NotInitializedException
Returns:
A Promise object that is resolved with no argument when the action request has completed.
Type
Promise

<static> addEventListener(type, func) → {object}

Adds a listener function for specified event type.

The portlet hub defines two classes of events - System Events and Portlet Client events:

System Events
Events that are generated by the portlet hub. They are used to pass portlet-specific information to the registered portlet client. The parameters passed to the system event callback functions are defined by the portlet hub.

Event types prefixed with "portlet." are reserved for system events. System event types may not be specified with a regular expression or wildcard. However, the same event listener may be added for both types of system events.

Only one listener for each type of system event may be added.

The following system event types are defined:

portlet.onStateChange
Fired when the render state changes. In order to participate in the portlet Ajax support, a portlet client must register an onStateChange event listener for this event type.

After the portlet client adds an event listener for the onStateChange event, the portlet hub will call the onStateChange callback function to provide the portlet client with its initial state information. However, this will not occur before the call to addEventListener returns.

portlet.onError
Fired when an error occurs that cannot be communicated through an exception. In general, this will be some type of asynchronous communication error. In order to receive notification about errors, a portlet must register an onError event listener for this event type.
Portlet Client Events
Events initiated by the portlet client through the dispatch method.

When adding a listener for a portlet client event, the event type may be specified by a regular expression string. The listener will be called for every event type that the regular expression string matches.

Example:
myHub.addEventListener("^myCompany\..*", myListener); // registers myListener for all event types beginning with "myCompany."

An event listener can be added for multiple event types. This function returns a handle to identify the unique listener for the event type and for the portlet client associated with the function.

Parameters:
Name Type Description
type string The type of listener
func function Function called when event occurs
Source:
Throws:
Thrown if the input parameters are invalid
Type
TypeError
Returns:
A handle that can be used to remove the event listener
Type
object

<static> createResourceUrl(resParams, cache, resid) → {Promise}

Returns a promise for a resource URL with parameters set appropriately for the page state according to the resource parameters, cacheability option, and resource ID provided.

The portlet client may use the resource URL with any appropriate javascript framework to retrieve content from the portlet through the server-side serveResource method.

Resource parameters are optional parameters attached to a resource URL in addition to any render state values that may be present. Resource parameters do not influence the render state.

The resource parameters must be an object containing properties representing parameter names whose values must be an array of string values, as described under PortletParameters. All of the resource parameters will be attached to the URL. Use of resource parameters is optional.

The cacheability option designates the degree to which the content to be served can be cached and influences the type of content that can be served. There are three possible values:

"full"
Most cacheable, because the URL contains no portlet-specific or page-specific information.
"portlet"
More cacheable, because the URL contains only portlet-specific but no page-specific information.
"page"
Least cacheable because the URL contains portlet-specific and page-specific information.

However, cacheability must be set to "page" if the content to be served contains portal URLs.

Specification of cacheability is optional. If the cacheability is not specified, cacheability for the URL will be set to "PAGE".

The resource ID is an additional identifying string that the resource serving method on the server can use to determine the information to be provided. The resource ID argument is optional.

The parameters must be provided in the defined order. However, if a preceding argument is not needed, it may be specified as null. Examples of valid calls:
createResourceUrl();
createResourceUrl(resParams, cache);
createResourceUrl(resParams, cache, resid);
createResourceUrl(resParams);
createResourceUrl(null, cache);
createResourceUrl(null, null, resid);

Parameters:
Name Type Description
resParams PortletParameters Resource parameters to be added to the URL
cache string Cacheability option. The strings defined under PortletConstants should be used to specifiy cacheability.
resid string Resource ID.
Source:
Throws:
Thrown if the input parameters are invalid
Type
TypeError
Returns:
A Promise object. Returns a string representing the resource URL on successful resolution. Returns an Error object containing a descriptive message on failure.
Type
Promise

<static> dispatchClientEvent(type, payload) → {number}

Dispatches a client event.

Client events of the specified type are queued for delivery to registered event listeners of that type.

The event type is matched against the type strings associated with registered event listeners. An event will be dispatched for each matching listener. The number of matching listeners will be returned.

The event payload is defined by the dispatcher of the event. It must be present, but may be of any type or value.

The portlet Client may not dispatch event types beginning with the reserved string "portlet.".

The client is responsible for preventing race conditions. For example, a race condition can occur if portlet A dispatches an event to portlet B, causing an event to portlet A, which dispatches again to portlet B, etc.

Event delivery cannot be guaranteed, and may vary according to the situation.

Take for example a scenario where a portlet issues an event to several other portlets, perhaps including itself. Due to the event, each portlet updates parameters through use of the setRenderState function.

The setRenderState function can cause a page refresh depending on the situation. If all portlets on the page participate in the JSR 362 Ajax support, the portlet hub might not cause a page refresh. However, if there are legacy portlets to be supported, the portal or portlet hub might choose to refresh the page.

In the latter case, this means that the first portlet receiving the event will be able to successfully update its parameters, but the remaining portlets will not. This can have unintentional consequences.

Parameters:
Name Type Description
type string The type of listener
payload any The payload to be delivered
Source:
Returns:
The number of events queued for delivery
Type
number

<static> isInProgress() → {boolean}

Tests whether a blocking operation is in progress.

The portlet client can use this function to test whether a state change is in progress before initiating a blocking operation.

Note that if the portlet client uses this function to implement a waiting function, the render state may be changed during the time that the portlet client waits. Also note that the portal may choose to refresh the page as a response to a blocking operation, in which case the waiting function would not complete.

The portlet hub provides for orderly state transitions by allowing only a single blocking operation (action, {@link setRenderState}, startPartialAction) to be active at any one time.

The state transition is considered to be active from the initial portlet client call to one of the blocking operations until the portlet hub has performed the requested state change and has informed all of the affected portlet clients by firing the corresponding onStateChange events.

See portlet for further information.

Source:
Returns:
true if a blocking operation is in progress
Type
boolean

<static> newParameters(p) → {PortletParameters}

Creates and returns a new PortletParameters object.

If no argument is provided, an empty PortletParameters object will be returned. If an existing PortletParameters object is provided as argument, a clone of the input object will be returned.

Parameters:
Name Type Description
p PortletParameters An optional PortletParameters object to be copied
Source:
Returns:
The new parameters object
Type
PortletParameters

<static> newState(s) → {RenderState}

Creates and returns a new RenderState object.

If no argument is provided, an empty RenderState object will be returned. If an existing RenderState object is provided as argument, a clone of the input object will be returned.

Parameters:
Name Type Description
s RenderState An optional RenderState object to be copied
Source:
Returns:
The new RenderState object
Type
RenderState

<static> removeEventListener(handle)

Removes a previously added listener function designated by the handle. The handle must be the same object previously returned by the addEventListener function.
Parameters:
Name Type Description
handle object The handle of the listener to be removed
Source:
Throws:
  • Thrown if the input parameters are invalid
    Type
    TypeError
  • Thrown if the event listener associated with this handle was registered by a different portlet
    Type
    AccessDeniedException

<static> setRenderState(state)

Sets the render state, which consists of the public and private render parameters, the portlet mode, and the window state.

When the render state has been successfully set, a copy of the render state will be provided to the portlet client through the onStateChange listener function. A portlet client can modify this state object and pass it to the setRenderState function to update the render state.

However, it is also possible for the portal to completely refresh the page as a response to setting the render state. This may occur in order to support portlets on the page that do not participate in the Portlet 3.0 Ajax support or due to configuration settings, for example.

If the page is completely refreshed, it will be rendered according to render parameters set on the server.

Setting the render state is a blocking operation. To allow for orderly state transitions, the portlet hub does not allow this function to be used while a blocking operation is in progress. A blocking operation is considered to be in progress from the initial call until the final onStateChange event for that operation has been fired. See portlet for further information.

Parameters:
Name Type Description
state RenderState The new state to be set
Source:
Throws:
  • Thrown if the input parameters are invalid
    Type
    TypeError
  • Thrown if a blocking operation is already in progress.
    Type
    AccessDeniedException
  • Thrown if a portlet ID is provided, but no onStateChange listener has been registered.
    Type
    NotInitializedException

<static> startPartialAction(actParams) → {Promise}

Starts partial action processing and returns a PartialActionInit object to the caller. The PartialActionInit object contains a partial action URL and a {@setPageState} callback function. The partial action URL can be used to initiate an action request. The {@setPageState} callback function allows the portlet client to complete the partial action operation by updating the state of all portlet clients on the page that are affected by action and event processing on the server resulting from the partial action.

After the setPageState function has been called, a copy of the render state will be provided to each affected portlet client through the onStateChange listener function.

In addition, the onStateChange listener function for the initiating portlet will be provided with a RenderData object, which contains the same data as would be available through a portlet resource request using the current render state with no additional resource parameters and with the resource URL cacheability option set to "PAGE".

Note that HTTP header information for the partial action response is set by the action processing method on the server. Any header information set by the resource method called to obtain the RenderData will be lost. If the portlet client needs access to the header data set by the resource method, it should create a resource URL and fetch the resource data on its own when the onStateChange listener function is called after the partial action has been performed.

However, it is also possible for the portal to completely refresh the page as a response to the action. This may occur in order to support portlets on the page that do not participate in the Portlet 3.0 Ajax support or due to configuration settings, for example.

If the page is completely refreshed, it will be rendered according to render parameters set on the server.

Action parameters are optional parameters attached to a action URL in addition to any render state values that may be present. Action parameters do not influence the render state.

The action parameters must be an object containing properties representing parameter names whose values must be an array of string values, as described under PortletParameters. All of the action parameters will be attached to the URL. Use of action parameters is optional.

A partial action is a blocking operation. To allow for orderly state transitions, the portlet hub does not allow this function to be used while a blocking operation is in progress. A blocking operation is considered to be in progress from the initial call until the final onStateChange event for that operation has been fired. See portlet for further information.

Parameters:
Name Type Description
actParams PortletParameters Action parameters to be added to the URL (optional)
Source:
Throws:
  • Thrown if the input parameters are invalid
    Type
    TypeError
  • Thrown if a blocking operation is already in progress.
    Type
    AccessDeniedException
  • Thrown if a portlet ID is provided, but no onStateChange listener has been registered.
    Type
    NotInitializedException
Returns:
A Promise object. Returns a {PortletActionInit} object containing a partial action URL and the setPageState callback function on successful resolution. Returns an Error object containing a descriptive message on failure.
Type
Promise