Community articleCommunity widgets feed
Added by IBM contributorIBM on December 21, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.
Tags: commapi
The Community Widgets ATOM Feed provides a way to interact programmatically with Widgets in a Community.

Widgets Feed URL
  • The Widgets ATOM Feed URL can be found in the <link> entry of a Community's service document with rel="http://www.ibm.com/xmlns/prod/sn/widgets"
  • An optional URL parameter can be added to retrieve Widgets only of a given type. The syntax is ?widgetDefId=ID[&widgetDefId=ID...] where ID matches the widgetDefId parameter for the widget definition in widgets-config.xml. For example:
    • To get all Widgets, the Widgets feed URL syntax for a community with id will look like:
      http:///communities/service/atom/community/widgets?communityUuid=
    • To only retrieve CustomLibrary widgets:
      http:///communities/service/atom/community/widgets?communityUuid=&widgetDefId=CustomLibrary

      Note: Multiple widget types can be retrieved with multiple &widgetDefId URL params like this:
      http:///communities/service/atom/community/widgets?communityUuid=&widgetDefId=CustomLibrary&widgetDefId=Library
All elements are in the http://www.w3.org/2005/Atom namespace, except those that are prefixed as follows:

snx

In the http://www.ibm.com/xmlns/prod/sn namespace.

Table of widget entry elements

Element
How treated on input
Description
<id>
Ignored
ATOM id
<title>
Ignored
If no custom title is provided, then this element will use a localized default title.
<snx:customTitle>
Optional, updates user visible title
<category term="widget" scheme="http://www.ibm.com/xmlns/prod/sn/type" />
Required
Identifies the entry as a widget Atom entry.
<link href="..." rel="self" />
Ignored
URL to get this Widgets ATOM entry
<link href="..." rel="edit" />
Ignored
URL to use to edit Widget
<link href="..." rel="alternate" />
Ignored
URL that can be used in a Web browser to display the Widget.
<snx:widgetDefId>
Will be required for POSTs, Ignored for PUTs
Indicates the type of widget. Must match the widgetDefId of an enabled widget.
<snx:widgetInstanceId>ID</snx:widgetInstanceId>
required for PUT, ignored for POST, DELETE
Widget Instance ID
<snx:hidden>true or false</snx:hidden>
optional default false
Hidden/Visible state
<snx:location>col2 or col3 (or col2statusposts for Status Updates widget only)</snx:location>
required unless snx:hidden is true in which case it's ignored
Column location
<snx:previousWidgetInstanceId>ID or empty if first item in column<snx:previousWidgetInstanceId>
optional. ignored if snx:hidden is true
Position given by previous widget instance id
<snx:widgetProperty key="xxx"> value </snx:widgetProperty
Optional
Provides the widget instance data. There may be multiple instances of this element

Example Widget Entry

A general Widget entry in the atom widget feed looks like this:


<entry xmlns:snx="http://www.ibm.com/xmlns/prod/sn">
<id>https://brobertsvm1.swg.usma.ibm.com:9443/communities/service/atom/community/widgets?communityUuid=78214ce7-etc&amp;widgetInstanceId=W85cde7f5a97etc</id>

<title type="text">MyLibrary</title>


<category term="widget" scheme="http://www.ibm.com/xmlns/prod/sn/type"></category>


<link href="https://brobertsvm1.swg.usma.ibm.com:9443/communities/service/atom/community/widgets?communityUuid=78214ce7-etc&amp;widgetInstanceId=W85cde7f5a97etc" rel="self"></link>


<link href="https://brobertsvm1.swg.usma.ibm.com:9443/communities/service/html/communityview?communityUuid=78214ce7-etc" rel="alternate"></link>


<snx:widgetDefId>MyLibrary</snx:widgetDefId>

<snx:widgetInstanceId>W85cde7f5a97etc</snx:widgetInstanceId>

<snx:hidden>false</snx:hidden>
<snx:previousWidgetInstanceId><snx:previousWidgetInstanceId> <!-- No widget instance id => this is the first widget in the column -->
<snx:widgetProperty key="value1">value 11</snx:widgetProperty> <!-- Widget specific attribute values are here -->
<snx:widgetProperty key="value2">value 22</snx:widgetProperty>

</entry>

Widget Positioning

When widgets are added, the default is to add them as the last widget in their default column. You can control which column the widget is placed in with the <snx:location> attribute. To control the widget's location within a column, use <snx:previousWidgetInstanceId> and specify the widget instance id you want to place the widget after. To place a widget at the top of column 2, use the widget id of the StatusUpdates widget, which is a mandated widget at the top of the column, as the <snx:previousWidgetInstanceId>. To place a widget at the top of column3, set it's <snx:location> to col3, and use the id of the last widget in column2 as the <snx:previousWidgetInstanceId>.

NOTE: It is possible that the Status Updates widget has been removed from a community. If that's the case, and you want to add a widget to the top of column 2 - simply add the Status Update widget, add your widget after it, and remove the Status Update widget.

  • DELETE

    Deletes widget
    • URL parameter has widget instance ID
    • Example: DELETE http://server/communities/service/atom/community/widgets/communityUuid=cid&widgetInstanceId=wid
    • Possible Error Responses:
      • Can't delete files widget when have media gallery widget is in use (400)
      • Bad widget id (403)
  • PUT

    Puts state change values to widget - position within its column, hidden state, custom title
    • Payload: existing widget entry with new state values. Only the following entry items will be looked at (all others will be ignored):
      • - used to give widget alternative title. Optional.
      • - Hidden state of widget desired. Optional. Not an error to hide an existing hidden widget.
      • - optional - default is widget's default column or column 2 if no widget default.
      • - id of widget to place this widget after. Optional. Default is to place widget last in column.
    • Response: widget entry with applied state values.
    • Possible Error Responses:
      • previous widget id doesn't exist (403)

Parent with ATOM entry documentation: Working with community widgets