Community widgets feed
Added by IBM contributorIBM | Edited by IBM contributorJonathan Hewitt on July 9, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

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

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>
Updates user visible title
If no title is provided, then this element will use a localized default 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
Ignored
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