NexJ Logo

Creating portlets in NexJ Studio

First-party portlets built using NexJ technology are created in NexJ Studio. These portlets benefit from the ability to automatically fire and receive system events, access a diverse library of Scheme APIs, and communicate using the context and event buses without additional portal API integration.

To configure a portlet in NexJ Studio:
1. Create a portlet screen
2. Configure context passing
3. Configure portal event passing
4. Configure user interface refresh events

Creating portlet screens in NexJ Studio

The user interface and content of a portlet is defined in a screen. For a screen to be used as portlet, its portlet attribute must be set to true.

To create a portlet using a screen:
1. In the NexJ Studio Presentation layer, open or create the portlet's screen.
2. In the Outline view, click the Screen node.
3. In the Properties view, set the portlet attribute to true.
4. Click the Save button to save your changes.
5. Update the database to reload the portlet definitions.
Your screen can now be used as a portlet once the portlet definitions have been updated in NexJ CRM.

Form and portlet references

Configuring context passing in NexJ Studio

Portlets creating using NexJ Studio should communicate using the context bus when situated in the same workspace. NexJ Framework provides portlets with the ability to automatically set and get context using the sysContext system event if they have subscribed to the context variable.

To configure a portlet to set and get the value of context variables:

  1. In the NexJ Studio Presentation layer, in the Forms tab, find and open the portlet's form.
  2. In the Outline view, click the Form node.

  3. In the context attribute, list the context variables this portlet will subscribe to.

    Info

    Portlets can subscribe to more than one context variable. Use a comma delimited list to include multiple variables.

  4. Click the Save button to save your changes.
  5. Update the database to reload the portlet definitions.

Your portlet is now subscribed to the specified context variables.

Configuring portal event passing in NexJ Studio

Portal events are broadcast and received using the event bus. Portlets created using NexJ technology can broadcast notification of event occurrences using UI Events. Event notifications are handled by UI Actions. Unlike the context bus, the event bus is global. All portlets can receive and react to event notifications regardless of what workplace they belong to.

Related links

Developing effective portlets
Communicating events
Events and the event bus
Shelving
Controls

Broadcasting events

 UI Events are notification objects used to inform elements of the application that the user has performed a particular action. Portlets automatically broadcast the occurrence of a UI Event to all other portlets in NexJ CRM through the
event bus using the event-broadcast API.

Info

Portlets must subscribe to the UI Event in their event attribute to broadcast event notifications.

To add a UI Event to your portlet:

  1. Open the portlet's form.
  2. In the Layout tab of the form editor, right-click in the area where you want to add the element.
  3. Select one of the Insert commands from the menu that displays. For example, select Insert Button.
  4. In the Outline view, select the command object.
  5. In the Properties view, set its event attribute to the name of the UI Event.
  6. Click the Save button to save your changes.
  7. Update the database to reload the portlet definitions.

Your portlet now has a command object linked to a UI Event that will be broadcast through the event bus when it is used.

Receiving events

When UI Events are performed in NexJ CRM, all other portlets subscribed to that specific event will be notified of its occurrence. Portlets require a UI Action to trigger a data synchronizing event once the notification has been received.

Info

Portlets must subscribe to the UI Event in their event attribute to receive event notifications.

To add a UI Action to your portlet:

  1. Open the portlet's form.
  2. Create a new script from the UI Action tab. Set the event attribute to the name of the UI Event you are creating a handler for.
  3. In the Script field, add a script defining the action that will occur when the event notification is received.
  4. Click the Save button to save your changes. Update the database to reload the portlet definitions.

Your portlet now has a UI Action to handle incoming portal event notifications.

Configuring inter-portlet refresh events in NexJ Studio

Inter-portlet refresh events are required to synchronize data in NexJ CRM. NexJ Framework automatically fires the sysNotifyCommitSuccess system event on all portlets whenever an event has been performed. After a portlet receives notification of a save and refreshes its activeNode, it will display the most up-to-date information.

Refreshing the portlet user interface

Portlets that contain information which can be modified from elsewhere in the application must subscribe to sysNotifyCommitSuccess and trigger the add-to-batch-requests API when a notification is received.

To configure inter-portlet refresh events:

  1. Open the portlet's form.
  2. In the Outline view, select the Form node. Using the Properties view, set the event attribute of the form to sysNotifyCommitSuccess.
  3. Create a new script from the UI Actions tab and set its event property name to sysNotifyCommitSuccess.
  4. Enter the add-to-batch-requests API in the Script field:
    (add-to-batch-requests this (@ view activeNode) "refresh)
  5. Click the Save button to save your changes.
  6. Update the database to reload the portlet definitions.

Filtering unnecessary portlet user interface refresh events

When a portlet fires the sysNotifyCommitSuccess system event, it should not refresh its own user interface. Additionally, you may only want to refresh particular classes or objects when a save has been committed. These commands improve application performance by reducing stress on the network.

To filter portlet refresh events:

  1. Open the portlet's form.
  2. Add the client-refresh-not-source-portlet API to the UI Action script to filter out unnecessary notifications.
  3. Add the following conditions to the UI Action script to filter out unnecessary refresh notifications:
    client-refresh-not-source-portlet
    This API enables the portlet to exclude the sysCommitNotifySuccess notifications that are fired from within itself. This can be invoked with the following script, added to the condition field on the UI Action configuration:
    (client-refresh-not-source-portlet parameter)
  4. Add the client-refresh-on-class-update API to the UI Action script to only refresh specific classes or objects:
    client-refresh-on-class-update
    This API enables the portlet to subscribe only to changes to particular classes or objects within the NexJ Framework. This can be invoked with the following line of code, added to the condition field on the UI Action configuration. In this example, Person and Household denote the object the portlet will refresh for:
    (client-refresh-on-class-update this parameter (list Person Household))
  5. Click the Save button to save your changes.
  6. Update the database to reload the portlet definitions

Your portlet will now ignore refresh commands on itself or for the specified classes and objects.

Your portlet will now be notified when the sysNotifyCommitSuccess system event has been fired and refresh its interface accordingly.