Customizing sidebar zones

You can customize portal sidebar zones to suit your specific business needs.

Sidebar zones are sliding workspaces situated on the left or right side of a NexJ application. They contain one or more portlets. A single portlet can be shown or hidden at any time. Portlets contained in sidebars can interact with the active workspace by passing and receiving context variables. By default, sidebar zones contain the Conversations portlet.

Customize the sidebar's metadata to redefine its functionality. Use NexJ Studio to change the following sidebar zone properties:

• The portlets that are contained in the sidebar zone.
• The width of the sidebar zone area.
• The sidebar zone's layout mode.
• The icons that will be used as the buttons to toggle sidebar zone visibility.

Sidebar zones

Sidebar zones are unique NexJ CRM workspace containers.

Each sidebar zone contains one or more portlets that are active for the lifespan of the application. Sidebar zones are similar to broker portlets as they are always able to receive context variable updates from the active workspace. Although not always visible, portlets in the sidebar zone are constantly aware of user interactions in the main area of the NexJ application.
Sidebar zone visibility is controlled by two methods:

• Users clicking a control element.
• An API call.

When either method is invoked, the sidebar zone will slide out or retract. How sidebar visibility affects the NexJ CRM layout is determined by its layoutBehavior property.

Sidebar zone buttons are always visible in NexJ CRM. Clicking a sidebar button toggles the visibility of the sidebar zone. The sysShowPortlet UI Event is fired whenever the sidebar is opened.

Sidebar zones exchange context variables with the active workspace. When switching workspaces, sidebar zones unregister listeners from the previous workspace and begin listening to changes in the newly selected workspace. If context variables registered in the sidebar zone exist in the new workspace, an explicit SysContext event will be fired to the sidebar portlet to ensure it can refresh itself and prevent data loss.

Sidebar zones support event broadcasts. NexJ framework will shelve UI Events to the sidebar portlets if the sidebar zone is closed. It will then fire any shelved events when the sidebar is made visible again. This is the same behavior as portlets within workspaces when their visibility changes.

Sidebar zone layout modes

Sidebar zone layout modes control how the sidebar zone will affect the appearance of NexJ CRM. The layout mode of a sidebar zone is defined by editing its metadata properties.
There are two layout modes:

OVERLAY (always overlay)

Places the sidebar on top of the main NexJ CRM area when visible. Does not change the positioning or size of any active workspaces or toolbars. The sidebar zone appears on top of existing content.

BUMP (bump then overlay)

Changes the layout of NexJ CRM when visible. Existing content snaps to the edge of the sidebar and resizes itself to fit in the remaining space. There is no overlapping or missing content when the sidebar zone is visible.

Related links

Configuring side bar zones

Sidebar zone properties and attributes

Sidebar zones are configured using the SysUpgrade.meta file in your working model.

Modify the sideBarPortletsList property in the WORKSPACE_APPLICATIONS attribute to define how the sidebar zone will function in your NexJ application. A sidebar zone can contain multiple portlets. Only one portlet can be shown or hidden at a time.

The sideBarPortletsList property contains the following attributes:

sideBarPortletsList properties

The following is an example SysUpgrade.meta file which defines two sidebar zones:

(message
      (: application "Contact")
      …
      (: sideBarPortletsList 
         (list
            (message              
              (: name "leftScreenPortlet")
              (: referent "EntityDashboardPortlet")
              (: layoutBehavior (SideBarLayoutEnum'get 'OVERLAY))   
              (: side (SideBarSideEnum'get 'LEFT))               
              (: size "300px"))
            (message              
              (: name "rightScreenPortlet")
              (: referent "ConversationInboxPortlet")
              (: layoutBehavior (SideBarLayoutEnum'get 'BUMP))   
              (: side (SideBarSideEnum'get 'RIGHT))               
              (: size "300px"))
         )
      )
)

These attribute values are parsed during the seed event defined in the SEED_WORKSPACE.meta file.

In the SysApplication class, the sideBarPortlets attribute becomes a collection of a type SideBarPortletRef. If SysApplication has existing SideBarPortletRef attributes, they will be deleted and replaced with the revised entries.

There is no caption layout support. The portlet will be responsible for handling the workspace switch using the context bus.

Related links

Configuring side bar zones

Configuring sidebar zones

Customize how the sidebar zone will function in your NexJ application by editing its metadata attributes.

To configure the sidebar zone metadata:

1. In NexJ Studio, open the Business Model layer.
2. Click the Classes tab in the model view sidebar and locate SysUpgrade.meta.
3. [Optional] If it is not already customized, right-click SysUpgrade.meta and select Customize.
   SysUpgrade.meta is customized. It has a blue and orange icon.
4. Double-click SysUpgrade.meta.
   SysUpgrade.meta opens in the NexJ Studio editor.
5. Select the Attributes tab and double-click the WORKSPACE_APPLICATIONS attribute.
6. In the Value tab, edit or add to the Scheme code in the Value field to modify the functionality of your sidebar zone.
7. Click the Save button 

   

   to save your changes.

Your sidebar zone metadata has been updated and saved.

Validate your model and restart the application server for the changes to take effect.

Related links

Sidebar zone layout modes
Sidebar zone properties and attributes

Configuring sidebar zone icons

Customize the buttons used to toggle sidebar zone visibility by changing the icon files. Icon files must be 37x57 pixels. The following files are used as sidebar zone icons:

• sidebar_l_closed.png: Closes a sidebar zone on the left side of the screen.
• sidebar_l_open.png: Opens a sidebar zone on the left side of the screen.
• sidebar_r_closed.png: Closes a sidebar zone on the right side of the screen.
• sidebar_r_open.png: Opens a sidebar zone on the right side of the screen.

Info

To hide the sidebar zone icons, replace each of the icon files with a blank image sized at 1x1 pixels.

To change the sidebar zone icons:

1. Using Windows Explorer, open the following directory: <project>/src/nexj/core/meta/sys/icons.
2. Copy your customized icons into the directory overwriting the existing files.
3. In NexJ Studio, open the Presentation layer and click the Icons tab.
4. Right-click in the model view sidebar and select Refresh.
5. Open the files you have replaced to confirm they appear as intended.

Your sidebar zone icons have been revised.

Validate your model and restart the application server for the changes to take effect.

Sidebar zone API

NexJ CRM has Scheme and JavaScript APIs that toggle the visibility of sidebar zones. They are available for both flat and rich web applications.

For more information on the sidebar zone APIs, see:

• Scheme: PortalAPI.setSideBarVisibility
• JavaScript: PortalAPI.setSideBarVisibility