Creating portlets outside NexJ Studio

NexJ CRM enables you to include portlets that have been developed outside of NexJ Studio.

These portlets can be served up from any location as long as they make their function available through a browser-accessible URL. Interactions between these portlets and NexJ CRM are managed through POST and GET interactions.

Enabling portlet interaction

If a portlet is intended to interact in any way with the other portlets in a workspace, then ensure that the portlet's markup contains an include statement pointing to the portal-api-1.0.js file, which is hosted on the NexJ CRM application server.

This enables the use of the portal API. Inclusion enables the use of the portal APIs, which are used to share information between portlets.

When developing a portlet, you must know the names of the context variables that the portlet is intended to interact with. This is particularly important for inter-portlet interaction. For example, if a portlet needs to receive the value of a context variable set by another portlet, then both portlets must refer to that context variable by the same name. This is true for portlets developed inside NexJ Studio, as well as outside NexJ Studio.

If you want the portlet to respond to events, which are broadcast through the event bus, you must use the PortalAPI.registerEventHandler method to register an event handler with the portal. The event handler should be a standard JavaScript function that accepts a single parameter: an array of JavaScript maps in which each map contains a name and parameter entry. If multiple events are passed at the same time due to the shelving behavior of the event bus, then the order of the maps in the array will reflect the order in which the events occurred.

Communicating events

When events are broadcast, the event bus passes a notification of the event to the portlets within the active workspace and shelves the notification of the event so that inactive workspaces can receive notification when they become active.

The bus communicates the event information slightly differently depending on whether the receiving portlet was developed as a NexJ Studio screen, or developed outside NexJ Studio. For portlets developed inside NexJ Studio, the event information is passed as an array of messages, one for each event. Each message contains two parts: a name entry and parameter entry. Portlets developed outside NexJ Studio receive the same information, but as an array of JavaScript maps.

In most cases, portlets must be configured to be able to receive event notification:

For portlets that are developed inside NexJ Studio, each fired event corresponds to a UIEvent. Therefore, for each event that you want a portlet to handle, you must configure a UIEvent handler in the screen that defines that portlet.
For portlets developed outside of NexJ Studio, the event property of the portlet's definition in the Enterprise Component Registry must be populated with the event names to which the portlet responds.

System events

The following events are fired by NexJ CRM in response to other portlet-initiated events. Each event contains only one parameter, even though that parameter may contain complex data types.

If you are developing your portlets in NexJ Studio, you do not need to list these events explicitly in the Events field. They will always be listened for. If you are developing your portlets outside of NexJ Studio, you will still have to register an event handler in order to receive the notification.

System event	Description
sysClosePortlet	Fired on a portlet to trigger its removal from the UI.
sysContext	Fired on a portlet when the value of at least one of the variables for which it has been subscribed to has been changed.

sysClosePortlet

Fired on a portlet to trigger its removal from the UI.

Parameter
There is currently no parameter provided for this event.

sysContext

Fired on a portlet when the value of at least one of the variables for which it has been subscribed to has been changed. This event is the mechanism through which portlets that have subscribed to a context variable receive notification of its update.

Parameter
The parameter that is sent with this event is a 2-element array:

Element 1
An array of context variable names that the portlet listens for changes to.

Element 2
A Javascript map with a key value pair for each changed variable:

Key
The name of the changed variable.

Value
An additional JavaScript map with the following two key value pairs:

oldValue, <the old variable value>

newValue, <the new variable value>

Configuring portlets to be served externally

If your model and its portlets are going to be deployed using the distributed portal configuration, then you should ensure your business model meets the following additional requirements.

The business model must include the system registry model as one of its mix-ins.
The system registry channel in the business model must be configured to point to the Enterprise Component Registry.

Once the solution is deployed, the system administrator must ensure that the model server URL is added as a trusted host. For more information, see NexJ CRM Deployment.

Designing portlets that make extensive use of a context variable

Context variables provide portlets with a mechanism to exchange variable values within a workspace.

For example, a RestaurantList portlet and RestaurantDetails portlet might share a context variable so that the details portlet can display information about the restaurant selected in the list.

If, within the details portlet, the same context variable information is required by multiple forms, then the context bus will attempt to deliver the updated information to each form in turn, resulting in increased network traffic. As well, if the context variable name ever needs to change, there is higher maintenance required as multiple forms will require updates to their variable names.
You can minimize the amount of network traffic and potential maintenance cost by using the following design pattern to share a single context variable across multiple forms in a single portlet:

Create an invisible form, a form with 0 width and 0 height, within the screen. This form will be used to store the context variables used within the portlet.
Define the context variables that you need only within this invisible form.
Associate the fields that require the context information with the value stored in the invisible form.

Using this pattern, the context value will only be delivered to the portlet once. The value will then be internally propagated within the portlet, reducing network traffic and increasing overall performance.

Assigning broker portlets to applications

Broker portlets are invisible portlets that allow functionality to be made available at the application, rather than workspace, level. Broker portlets group together functionality that will be present in the application regardless of what workspace is currently in use.

They do not contribute to specific workspaces like other portlets. Instead, they add permanent buttons to the application toolbar. If you have created a portlet that you want to use as a broker portlet, you must add a reference to this portlet from within the application model in NexJ Studio.

Before you can assign a broker portlet to an application, that application must already have at least one of the following elements defined in its outline:

TableLayout
SplitterLayout
GroupLayout
ScreenRefs

To assign a broker portlet to an application:

In NexJ Studio, open the application with which you want to associate the broker portlet.
In the Outline view, right-click the application node and select Insert Child > BrokerPortletRef end.
Select the new broker portlet reference.
In the Properties view, replace the default value of the name property with something meaningful to your model. A suggested convention is to name the reference ref<BrokerPortletName> where <BrokerPortletName> is the name of the portlet you are referencing.
Set the value of the screen property to the name of the portlet that you want to use as a broker portlet. Remember, portlets are defined as screens that have their portlet property set to true.
Save your changes and validate your model.

Making portlets available for use

Before a portlet can be accessed by NexJ CRM, a system administrator must create an entry for that portlet in the Enterprise Component Registry. This entry consists of the following information:

The URL from which the NexJ CRM application server can load the portlet.
The list of context variables that the portlet will subscribe to.
The list of events to which the portlet will respond.

To register the portlet:

In NexJ Studio, switch to the environment corresponding to the Enterprise Component Registry that you want to register the portlet with. In the case of a consolidated installation, this is the server on which you deployed the NexJ CRM application server.
Run the Scheme Server Console.
Use the following Scheme commands to grant the privilege:
SCHEME
```
(Portlet'new
   (: name "<PortletName>")
   (: url "<http://PortletURL>")
   (: event "<event1,event2,event3>")
   (: context "<contextvar1, contextvar2>")
)
(commit)
```
where
- <PortletName> is the name of the portlet that you want to register.
- <http://PortletURL> is the URL at which the NexJ CRM application server can access the portlet.
- <event1,event2,event3> are the names of any events that the portlet will either listen for or raise.
- <contextvar1, contextvar2> are the names of any context variables that the portlet either sets or receives.
Repeat step 3 for each portlet that you want to register.

Upon completion of these steps, the portlets are available to be included in any portal workspace.

Related links