Enable custom widgets for Communities 

To make custom widgets available for use in Communities, configure the widgets in the widget definition file, widgets-config.xml.


Before starting

To edit configuration files, use the IBM WAS wsadmin client. See Starting the wsadmin client for details.


About this task

The widgets-config.xml file contains information about widget definitions, widget attributes, widget location, default widget templates, and page definitions. Custom widget attributes are defined by the widget developer but, as administrator, configure the widgets by adding a <widgetDef> element containing the appropriate attributes for each widget in the widget configuration file.

You can integrate a custom widget as part of IBM Connections and you can also integrate the widget as an external application. To integrate the widget inside the IBM Connections application, your widget must provide a full page mode. To integrate the widget externally, use a navBarLink attribute to register a navigation link along with your 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. For more information, see Integrate the community card.


Procedure

To configure a custom widget for use in Communities...

  1. From the dmgr host:

      cd $DMGR_PROFILE/bin
      ./wsadmin.sh -jython
      execfile("communitiesAdmin.py")

      If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, pick the node where the file is stored.

  2. Check out the widgets-config.xml file using the following command:

      CommunitiesConfigService.checkOutWidgetsConfig(“<working_directory>", "<cell_name>")

      where:

      • <working_directory> is the temporary working directory to which the configuration XML and XSD files are copied. The files are kept in this working directory while you make changes to them. When specifying the path to a working directory or temporary directory where the checked out files are to be placed, use a forward slash as the path separator, even for Microsoft Windows systems.

      • <cell_name> is the name of the WAS cell hosting the Communities application. This argument is required. It is also case-sensitive, so type it with care.

      For example: 

      CommunitiesConfigService.checkOutWidgetsConfig("C:/tmp2","MyServerNode01Cell")

  3. 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:

      Table 1. Widget configuration 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 The widget displays in the center column of the page. The default value is true.

      Note: The value of primaryWidget must be true for Custom Library widgets in Communities.

      		No
      description Description of the widget that displays in the widget palette. This attribute uses the custom string framework. For information about how to add a string containing the widget description, see Add custom strings for widgets and other specified scenarios. No
      category The category in which the widget is placed in the widget palette. This attribute uses the custom string framework. For information about how to add a string that specifies the widget category, see Add custom strings for widgets and other specified scenarios. No
      requires Specifies which IBM Connections applications are required for the widget to function. The XML attribute values must match the serviceReference values in the LotusConnections-config.xml file. No
      url Specifies the location of the widget descriptor. This XML attribute can be parameterized with substitution variables. Yes
      modes Specifies the modes that are supported by the custom widget. Possible modes include:

      • view. This mode enables the widget to display on the community overview page page.

      • search. This mode integrates the widget into a community's search results page. Each widget displays as a separate tab on the page.

      • fullpage. This mode integrates the 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. This mode enables the 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 Specifies whether the widget supports multiple instances on the same page. The default value is false. No
      resourceOwnerWidget Specifies whether the widget should be seen only by the community owners or profile owner. Set this to true or false as required. No
      navBarLink Specifies the 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 Specifies the URL to an HTML file containing help documentation for the widget. The help opens in a pop-up window. This parameter can contain subvariables. It can also be parameterized with substitution variables. No
      showInPalette Specifies if the widget should be displayed in the content palette. No
      loginRequired The widget displays only when users are logged in. No
      bundleRefId The resource bundle reference ID that is defined in the LotusConnections-config.xml file. This ID is used to determine the bundle strings for the widget category, widget description, and widget title. For more information about adding custom strings for widgets, see Add custom strings for widgets and other specified scenarios. No

      Table 2. The page element

      Attribute Description
      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.

      Table 3. The widget instance element

      Attribute Description
      uiLocation Defines the location of the widget on the page. You can set this to col1, col2, or col3.

      This attribute takes a string value.

      defIdRef Defines 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 your custom bundle. For more information about adding custom strings for widgets, see Add custom strings for widgets and other specified scenarios.

      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>
              <page pageId="allCommunities"/> <!-- All Communities Page: only col1 is supported-->
          </layout>
        </widgets> 
    </resource>
    .....
</config>

      The url, navBarLink, and item or @value XML attributes can be parameterized using substitution variables. For more information about the substitution variables that you can use, see Communities widget configuration variables.

  4. Optional:  If you want to specify that a widget is opened by default, add it to the <template> element.

      For example: 

      <templates>
  <template id="default">  <!-- default template will be used to display widgets that are opened by default-->
     <widgetInstance uiLocation="col2" defIdRef="Forum" instanceId="ForumInstance1"/><!-- default widget location -->
     <widgetInstance uiLocation="col2" defIdRef="Feeds" instanceId="FeedsInstance1"/>
     <widgetInstance uiLocation="col2" defIdRef="Bookmarks" instanceId="BookmarksInstance1"/>
  </template>
</templates>

  5. Apply your changes...

    1. Check in the updated widgets-config.xml file using the following command:

        CommunitiesConfigService.checkInWidgetsConfig(“<working_directory>", "<cell_name>")
        For example: 

        CommunitiesConfigService.checkInWidgetsConfig("C:/tmp2","MyServerNode01Cell")

    2. To exit the wsadmin client, type exit at the prompt.

    3. Restart the Communities application using the WAS admin console.


What to do next

If you are adding widgets that are hosted on third-party servers, then you might need to update your proxy configuration. For more information on configuring the Ajax proxy for Communities, see Configure the AJAX proxy for a specific application.


Parent topic

Add custom widgets to Communities


Related tasks


Configure the AJAX proxy for a specific application
Add custom strings for widgets and other specified scenarios
Integrate the Communities business card
Install the non-English version of the SharePoint widget for Communities

Related reference
Communities widget configuration variables


   

 

});

+

Search Tips   |   Advanced Search