To make custom widgets available for use in Communities,
configure the widgets in the Communities section of the widget definition
file, widgets-config.xml.
Before you begin
To edit configuration files, you must
use the IBM® WebSphere® Application Server wsadmin client.
See Starting the wsadmin
client for details.
About this task
The widgets-config.xml file is used by the Communities and Profiles
applications and contains settings for both applications. Make your changes in the Communities
section of the file define by the <resource type="community"...> tag.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. However, as administrator, you need to configure the
widgets by adding a <widgetDef> that contains 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, you must use a navBarLink attribute to register a navigation link along with your widget
configuration information. 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 Communities business card.
Procedure
To configure a custom widget for use in Communities,
complete the following steps.
- Start the wsadmin client from the following
directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin
where app_server_root is the WebSphere Application Server
installation directory and dm_profile_root is the
Deployment Manager profile directory, typically dmgr01.You must
start the client from this directory or subsequent commands that you
enter will not execute correctly.
- Start the Communities Jython script interpreter
using the following command:
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,
you must pick the node where the file is stored.
- 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 WebSphere Application Server 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")
- Open the widgets_config.xml file and define the custom widget by
specifying a resource type of community and adding a <widgetDef> element by
using the following attributes and parameters:
Note: Do not use the following attributes, they are intended for IBM development only:
- showIfConfigSet
- showIfCookieSet
- showIfNothingSet
Table 1. Widget configuration attributes and parametersAttribute |
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. Note: The value of primaryWidget must be true for 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 that contains the widget
description, see Adding 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 Adding 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 the following:- 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 is seen only by the community owners or profile
owner. Set this attribute to true or false. |
No |
navBarLink |
Specifies the URL to an external application. A link to this URL is added to
the community overview sidebar menu - the menu by the community logo. The URL can contain
substitution variables, but cannot contain JavaScript. |
No |
helpLink |
Specifies the URL to an HTML file that contains help documentation for the
widget. The help opens in a window. This parameter can contain subvariables. It can also be
parameterized with substitution variables. |
No |
showInPalette |
Specifies whether the widget is 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 for widgets, see Adding custom strings for widgets and other specified
scenarios. |
No |
Table 3. The widget instance elementAttribute |
Description |
uiLocation |
Defines the location of the widget on the page. You can set this attribute 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 you add custom strings with 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 Adding 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 with substitution variables.
For more information about the substitution variables that you can use, see
Communities widget
configuration substitution variables.
- Optional: To specify that a widget is always on a page, add a
<widgetInstance> element to the appropriate <page>
elements under the <layout resourceSubType="default"> element. Table 2 shows
what you enter for the <widgetInstance>.
- Optional: If you want 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>
- Apply your changes by doing
the following:
- 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")
- To exit the wsadmin client, type exit at
the prompt.
- Restart the Communities application using the WebSphere Application Server Integrated
Solutions 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, see Configuring the AJAX proxy for a
specific application.