Enable custom widgets for Communities

Overview

We configure custom widgets for communities in the widget definition file, widgets-config.xml, which is used by both the Communities and the Profiles applications. We make changes in the Communities section of the file. Configure widgets by adding a <widgetDef> element, and setting appropriate attributes.

We can integrate a custom widget as part of Connections or and as an external application. To integrate the widget inside the Connections application, the widget must provide a full page mode. To integrate the widget externally, use a navBarLink attribute to register a navigation link along with the widget configuration information.

You should also include the community inline business card in the external application to allow community members to navigate back to the community. See Integrate the Communities business card.

Configure a custom widget for use in Communities

1. Check out widgets-config.xml:
   cd app_server_root/profiles/Dmgr01/bin
   ./wsadmin.sh -lang jython
   execfile("communitiesAdmin.py")
   CommunitiesConfigService.checkOutWidgetsConfig("/tmp", "cell_name")

2. Open the widgets_config.xml file and define the custom widget by specifying a resource type of community and adding a <widgetDef> element using the following attributes and parameters:

   Attribute	Description	Required
   defId	The widget name. The defId attribute is also used as a title or a resource bundle key.	Yes
   primaryWidget	Widget displays in the center column of the page. Default is true. The value of primaryWidget must be true for Library widgets in Communities.	No
   description	Description of the widget that displays in the widget palette. Uses the custom string framework.	No
   category	The category in which the widget is placed in the widget palette. Uses the custom string framework.	No
   requires	Which Connections applications are required for the widget to function. The XML attribute values must match the serviceReference values in LotusConnections-config.xml.	No
   url	Location of the widget descriptor. Can be parameterized with substitution variables.	Yes
   modes	view Display widget on the community overview page. search Integrate widget into a community's search results page. Each widget displays as a separate tab on the page. fullpage Integrate widget into the navigation bar. When users click the widget link in the navigation bar, the widget displays in a full page view in the community. edit Enable Edit menu option in the widget's action menu, allowing community owners to edit the preferences of the widget inline, directly from the community's Overview page. The widget is also integrated in to the Edit Community page as a separate tab.	No
   uniqueInstance	Whether the widget supports multiple instances on the same page. Default is false.	No
   resourceOwnerWidget	Whether the widget should be seen only by the community owners or profile owner. Set true or false.	No
   navBarLink	URL to an external application. A link to this URL is added to the navigation bar when the widget is part of the community. The URL can contain substitution variables.	No
   helpLink	URL to an HTML file containing help documentation for the widget. The help opens in a pop-up window. This parameter can contain subvariables. Can be parameterized with substitution variables.	No
   showInPalette	Specifies if the widget should be displayed in the content palette.	No
   loginRequired	Widget displays only when users are logged in.	No
   bundleRefId	The resource bundle reference ID defined in LotusConnections-config.xml. This ID is used to determine the bundle strings for the widget category, widget description, and widget title.	No
   pageId	Contains the pageId for the page that Communities uses to render the widget layout. This attribute takes a string value. Possible values include communityOverview, allCommunities, and myCommunities.
   uiLocation	Define the location of the widget on the page. We can set this to col1, col2, or col3. This attribute takes a string value.
   defIdRef	Define the widget definition to which the instance is bound. This attribute takes a string value.

   When adding custom strings using the resource bundle loader, the value of the category, description, and widgetDef attributes in the <widgetDef> element are used as the resource key for the custom bundle.

   For example:

   <config id="widgets">
   
       <resource type="profile">
       .....
       </resource>
   
       <resource type="community">
   
           <widgets>
             <definitions>
               <widgetDef defId="HelloWorld" 
                   primaryWidget="false" 
                   modes="view fullpage edit search"  
                   url="{contextRoot}/comm.widgets/helloWorld/HelloWorld.xml?version={version}"/> 
                   <!-- XML attribute with substitution variables -->
             </definitions>
   
             <layout resourceSubType="default">
                 <page pageId="communityOverview"> 
   
                 <!-- page definitions and the mandated widgets assigned to them-->
                   <widgetInstance uiLocation="col3" defIdRef="Members"/> 
                   <!-- mandated widget UI location: possible values: col1, col2, col3 -->
                 </page>
   
                 <!-- All Communities Page: only col1 is supported-->
                 <page pageId="allCommunities"/> 
   
   
             </layout>
           </widgets> 
       </resource>
       .....
   </config>

   The url, navBarLink, and item or @value XML attributes can be parameterized using substitution variables.

3. To specify that a widget is opened by default, add it to the <template> element.

   For example:

   <templates> <!-- default template will be used to display the default widgets --> 
    <template id="default">
     <widgetInstance instanceId="StatusUpdates1" defIdRef="StatusUpdates" uiLocation="col2statusposts"/>
     <widgetInstance instanceId="ForumInstance1" defIdRef="Forum" uiLocation="col2"/>
     <widgetInstance instanceId="BookmarksInstance1" defIdRef="Bookmarks" uiLocation="col2"/>
     <widgetInstance instanceId="FilesInstance1" defIdRef="Files" uiLocation="col2"/>
     </template>
   </templates>  

4. Apply the changes...
   CommunitiesConfigService.checkInWidgetsConfig("/tmp", "cell_name")
   exit

5. Restart the Communities application

What to do next

or widgets hosted on third-party servers, we may need to update the proxy configuration.

Parent topic:
Add custom widgets to Communities

Related:
Configure the AJAX proxy for a specific application
Integrate the Communities business card
Communities widget configuration variables