Home

 

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.

To edit configuration files, use the IBM WebSphere Application Server wsadmin client. See Start the wsadmin client for details.

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, you need to configure the widgets by adding a <widgetDef> element containing the appropriate attributes for each widget in the widget configuration file. The file is stored in the following location:

WAS_HOME\profiles\AppSrv01\config\cells\cell\LotusConnections-config\widgets-config.xml

You can integrate a custom widget as part of IBM Lotus Connections and you can also integrate the widget as an external application. To integrate the widget inside the Lotus 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 Integrating the community card.

To configure a custom widget...

  1. Use the wsadmin client to access the Communities configuration files.

    1. Access the Communities configuration files:

      If you are asked to select a server, you can select any server.

  2. Check out the widgets-config.xml file...

    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 while you make changes to them. When specifying the path to a working 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 WebSphere Application Server cell hosting the Communities feature. This argument is required even in stand-alone deployments.

    For example: 

      CommunitiesConfigService.checkOutWidgetsConfig"C:/tmp2","Cell01")

  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:


    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 Specifies that the widget displays in the center column of the page. The default value is true. No
    description Description of the widget that displays in the widget palette. This attribute uses the custom string framework. For more information about adding custom strings, see Adding custom strings to Lotus Connections. No
    category The category in which the widget is placed in the widget palette. This attribute uses the custom string framework. For more information about adding custom strings, see Adding custom strings to Lotus Connections. No
    requires Specifies which IBM Lotus Connections features 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 Specifies that 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, see Adding custom strings to Lotus Connections. No


    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.


    The widget instance element
    Attribute Description
    uiLocation Defines the location of the widget on the page. You can set this to col1, col2, and 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 on adding custom strings, see Adding custom strings to Lotus Connections.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 the substitution variables. For more information about the substitution variables that you can use, see Widget configuration variables.

  4. Optional: 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 by doing the following:

    1. Check in the updated widgets-config.xml file...

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

      For example: 

        CommunitiesConfigService.checkInWidgetsConfig"C:/tmp2","Cell01")

    2. To exit the wsadmin client, type

      exit

      at the prompt.

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


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 Defining trusted and nontrusted Web sites for Communities.


Add custom widgets to Communities

 

Related tasks

Define trusted and nontrusted Web sites for Communities

Add custom strings to Communities and Profiles

Integrate the community card

 

Related reference


Widget configuration variables

+

Search Tips   |   Advanced Search