Archived:Syndication service in WidSets
Archived: This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. If you think this article is still relevant, let us know by adding the template {{ReviewForRemovalFromArchive|user=~~~~|write your reason here}}.
The article is believed to be still valid for the original topic scope.
The article is believed to be still valid for the original topic scope.
Article Metadata
Contents |
The Service
The syndication service gives a common interface to RSS and ATOM type online feed content.
The syndication service supports polling. This means that if a syndication service is marked as pollable, the WidSets server can poll the external feed on behalf of the client and notify the client when new content is available.
A client uses the syndication service actions getItems and getPage to retrieve the actual content.
The feed content is returned to the client as a structured and tagged list format. The feed item description part is represented as a list of text and image url elements. The image url elements represent the images embedded in the feed item description text or in separate enclosures. The order of the text and image url elements represent their order in the original feed.
Service Parameters
The XML configuration file of a syndication service can define several service parameters that define and control the service. Normally only the feedurl and polltype service parameters are defined. Other parameters are optional and are used for specifying poll period limits and token authentication.
| Service parameter | Type | Meaning |
|---|---|---|
| feedurl | mandatory | The URL to the RSS or ATOM feed to be fetched. |
| polltype | optional | Marks the service as pollable. The value of this parameter defines how the server will poll the feed defined by the feedurl parameter. Currently the only valid value for this parameter is auto. |
| minpollperiod | optional | Defines the lower limit for the poll period value for a pollable service. Default value is "2m". |
| maxpollperiod | optional | Defines the upper limit for the poll period value for a pollable service. Default value is "3h". |
| authtoken | optional | TOKEN to be used in signing the URL when Token authentication is used. (See Archived:Token authentication in WidSets.) |
| userid | optional | UserID to be used when performing Token authentication. (See Archived:Token authentication in WidSets.) |
| partnerid | optional | Id of the partner in question when using Token authentication. |
| useapiurl | optional | If the value is true, the URL specified in the partner's information is used. Otherwise the URL specified by feedurl service parameter will be used. |
Service Actions
The service has four actions the client script can call:
| Action | Generic | Function |
|---|---|---|
| getItems | No | Retrive feed items list. |
| getPage | No | Retrieve the value of the content-field page by page. The value of the content field of a feed item can be rather long. Therefore the value is retrieved one page at the time. The default page length is 500 characters. |
| bookmark | No | Save the link associated with a feed item into the bookmarks. |
| senditem | No | Send the link associated with a feed item to a friend by email. |
Below are the specifications of the service actions:
Definitions
TitleField = (bind (const title) (choice (null noData)
(string titleVal)))
LinkField = (bind (const "link") (choice (null noData)
(string linkVal)))
CreatedField = (bind (const created) (choice (null noData)
(int createdTimestamp)))
AuthorField = (bind (const author) (choice (null noData)
(string authorVal)))
ContentField = (bind (const content) (choice (null noData)
(use PagedFieldVal)))
PagedFieldVal = (list (bag (bind (const type) (const page))
(bind (const pg) (int pageNum))
(bind (const left) (int pagesLeft))
(bind (const val) (use PageVal))))
PageVal = (choice (null noData)
(use ElemList))
ElemList = (list (repeat (use Elem)))
Elem = (choice (string stringElem)
(use ImageUrlElem))
ImageUrlElem = (list (bag (required (bind (const type) (const image)))
(required (bind (const url) (string imageUrl)))
(optional (bind (const width) (int imageWidth)))
(optional (bind (const height) (int imageHeight)))))
Action getItems
Retrive feed items list.
input = (list (bag (optional (bind (const ts) (int timestamp)))
(optional (bind (const refresh) (boolean refreshVal)))
(optional (bind (const max) (int maxCount)))
(optional (bind (const len) (choice (int pageLength)
(const all))))))
output = (choice (null noData)
(list (repeat (use Item))))
Item = (list (bag (bind (const iid) (string itemId))
(repeat (use Field))))
Field = (choice (use TitleField)
(use LinkField)
(use CreatedField)
(use AuthorField)
(use ContentField))
Arguments
| Name | Type | Description |
|---|---|---|
| ts | int | Return only items that are newer than the value of this argument. The timestamp value is in milliseconds since the 1st of January, 1970, and interpreted as UTF/GMT timestamp. |
| refresh | boolean | If true, return fresh content fetched from the feedurl. Otherwise, return content from server side cache, if available. |
| max | int | The maximum number of items to return. Default is 20. |
| len | int | all | The [first] page length (in characters) for the content field value. Default is 500. The special constant value all returns all content. |
Sample Output
((iid = "961e023e1a7652d59a1e50237325310d"
title = "California hopes for slowing winds\n(AP)"
link = "http://us.rd.yahoo.com/dailynews/rss/topstories/*http://news.yahoo.com/s/ap/20071024/
ap_on_re_us/california_wildfires"
created = 1193222693000
author = ""
content = (type = page
pg = 1
left = 0
val = ((type = image
url = "http://d.yimg.com/us.yimg.com/p/ap/20071024/capt.b42703c3b236406dbd6c704f7c78bf89
.california_wildfires_carie101.jpg?x=91&y=130&sig=C8HUxcstv4ibFxXoT9ZgEw--"
width = 91
height = 130)
"AP - After three days of a vicious firestorm, exhausted firefighters and weary residents
looked forward Wednesday to a break — an expected slackening of the gale force winds that
have ignited the state\'s largest complex of wildland blazes.")))
(iid = a971fe9d92d0dd6a5c2032b5bf4e66a9
title = "Turkey masses more troops, raids in Iraq confirmed\n(Reuters)"
link = "http://us.rd.yahoo.com/dailynews/rss/topstories/*http://news.yahoo.com/s/nm/20071024/ts_nm/turkey_iraq_dc"
created = 1193222613000
author = ""
content = (type = page
pg = 1
left = 0
val = ((type = image
url = "http://d.yimg.com/us.yimg.com/p/nm/20071024/2007_10_23t101515_450x235_us_turkey_
iraq.jpg?x=130&y=67&sig=8fnRtMRr6856ashQCH4kJA--"
width = 130
height = 67)
"Reuters - Turkish warplanes and troops have\nattacked Kurdish rebels inside Iraq and
forces were being built\nup on the border, but Ankara was holding back from any major\nstrike
for now, military sources said on Wednesday.")))
(iid = "635886e9387a951b294c6cb4cbe0fe89"
title = "China aims for moon with patriotic blast\n(Reuters)"
link = "http://us.rd.yahoo.com/dailynews/rss/topstories/*http://news.yahoo.com/s/nm/20071024/ts_nm/china_space_launch_dc"
created = 1193222529000
author = ""
content = (type = page
pg = 1
left = 0
val = ("Reuters - China launched its first moon\norbiter on Wednesday accompanied by a blaze of
live-to-air\npatriotic propaganda celebrating the country\'s space ambitions\nand
technological prowess.")))
...)
Action getPage
Retrieve the value of the content field page by page.
input = (list (bag (required (bind (const iid) (string itemId)))
(required (bind (const pg) (int pageNum)))
(optional (bind (const len) (choice (int pageLength)
(const all))))))
output = (list (bag (bind (const iid) (string itemId))
(use ContentField)))
Arguments
| Name | Type | Description |
|---|---|---|
| iid | string | The ID of the item. |
| pg | int | The number of the page to return. Page numbers start from 1. |
| len | int | all | The page length (in characters). Default is 500. The special constant value all returns all content. (If len is all then pg must be 1.) |
Action bookmark
Save the link associated with a feed item into the bookmarks.
input = (list (bag (required (bind (const type) (choice (const default)
(const custom))))
(optional (bind (const iid) (string itemId)))))
output = (const true)
Arguments
| Name | Type | Description |
|---|---|---|
| type | default | custom | Type of the bookmark, normally default. |
| iid | string | The ID of the item to bookmark. |
Action senditem
Send the link associated with a feed item to a friend by email.
input = (list (bag (required (bind (const iid) (string itemId)))
(required (bind (const to) (string to)))))
output = (const true)
Arguments
| Name | Type | Description |
|---|---|---|
| iid | string | The ID of the item to send. |
| to | string | The recipient's email address. |
Code Example
Retrieving the newest feed items from server (fetcher)
Archived:Example Syndication Service in WidSets
(no comments yet)