Newsagent/Syndicate

Newsagent
Author	Chris Page
Contact	Support
Repository	github
Issue tracker	github
OS	Neutral (web based) Will not work with IE8 or older
URL	Newsagent
Navigation
General Overview Feed List Feed Subscription Logging in Logout Articles Composing Articles (Quickstart) Image Library Files Notification Method Options Feeds and Visibility Multiple Feeds Listing Articles Editing Articles Template Articles Syndication Newsletters Newsletters Newsletter Editor Tell Us Tell Us Queues Tech docs Advanced/Upcoming features Installation Technical Autogenerated docs

As stated in the Feeds and Visibility documentation, all normal articles created in Newsagent must go into one or more feeds with at least one visibility level set. Feeds may then be requested by any client - website, feed reader or aggregator, and so on - that is interested in the articles, and each client may specify which level of article they are interested in seeing in the feed.

Feeds are exposed by the system in two formats:

• a 'HTML fragment' format suitable for directly embedding in pages, with css classes set on most elements to allow for styling to match the page the content is embedded in. This format is not recommended for general use, and should only be used when you are unable to use the RSS feeds.
• RSS 2.0 formatted feeds compatible with most feed readers and aggregator. This is the recommended format for fetching feeds from the system.

Available feeds

The list of feeds available in the Newsagent system is given on the Feeds List page. The Feeds List page is the default newsagent page, and can always be accessed by clicking on the "Newsagent front page" icon at the top left of the page. Please see the documentation for the Feed List page for more information.

Requesting feeds

The Newsagent feed generators are accessed just like any other Newsagent page, with different paths for the two feed types:

• The RSS feed generator is accessed through the /rss path, so an example URL would be https://newsagent.cs.manchester.ac.uk/rss
• The HTML fragment generator is accessed through the /html path, for example https://newsagent.cs.manchester.ac.uk/html. The default layout includes the title, summary, lead image, publication date, and user information. Additional layouts are available via the paths /html/compact and /html/full - the former produces an abridged version of the feed that omits the summary and lead image, while the latter includes the full article text and article image.

If invoked without any additional arguments, the two generators produce feeds that include the 10 most-recently published articles, taking articles from all of the Newsagent feeds at all visibility levels. Additional options can be passed to the feed generators through the query string.

Feed options

The generator scripts support a number of options that allow you to control the articles included in the generated feed. The most important option is the feed option:

feed=<comma separated list of feeds>

The feed option allows you to specify which Newsagent feed or feeds you are interested in fetching articles from. This can either be a single Newsagent feed name, as shown in the table above, or you can request articles in multiple Newsagent feeds by separating the names with commas, eg: feed=pgt,pgr,ugt will give you the articles published in the Study - PGT, Study - PGR, or Study - UGT Newsagent feeds. If you do not specify a feed at all, the system will give you articles published in all Newsagent feeds.

level=<comma separated list of visibility levels>

If you just ask for a Newsagent feed, you will get all published articles in that feed regardless of the visibility levels the author set on it. If you are only interested in a subset of articles with specific visibility levels, you should include the level option in the query. The level option allows you to select only articles that have been set to be published at the specified level(s). This can either be a single level, eg: level=home or it can be a comma separated list level=home,leader. Valid levels are currently home (Important (School Home Page)), leader (Medium (Section Leader Page)), and group (General (Group or Internal pages)). Omitting this option is equivalent to level=home,leader,group (ie: select all levels). https://newsagent.cs.manchester.ac.uk/rss?feed=pgt,pgr&level=leader,group will produce a feed containing articles published in the PGT or PGR feeds at the Medium or General levels.

id=<article id> or articleid=<article id>

Allows the selection of a specific article in the system by its internal id. In general, if you include the id or articleid parameter in the query string, you will want to avoid including any other parameters to ensure that the article you are trying to select is not filtered out by other parameters. If provided, the feed will only contain the article with the ID specified, no other articles will be included.

fulltext=<mode>

rss generator only

Specifying this argument turns on the inclusion of the full article text in each returned item. The full text appears in a <newsagent:fulltext> element in the RSS item unless the desc argument below is specified. Supported modes are:

• enabled: the full article HTML is included in each item.
• markdown: the full article text is converted to markdown text as much as possible.
• plain: the full article text is included, but all html is stripped from the text.
• embedimg: the full article HTML is templated to include the article image if one has been set for the article.

desc=fulltext

rss generator only

This argument changes the way in which the RSS generator produces the <decription> element in each item: normally it will use the article summary in the RSS <decription> element, but when this argument is specified the full article text is used instead. When specified, the <decription> element will contain the full article text as processed according to the current setting of the fulltext argument: if the feed is requested using the arguments desc=fulltext&fulltext=markdown then the <decription> will contain the full article text with markdown formatting, similarly if it requested using desc=fulltext&fulltext=embedimg then the <decription> will contain the full article html with the article image embedded if there is one. Note that, if desc=fulltext is specified, but no fulltext has been specified, the fulltext will default to embedimg.

viewer=<name>

Specify a article viewer to use rather than the default calculated one. If this is set to viewer=internal the URL of a Newsagent internal article viewer will be included for each article in a generated feed. Otherwise the name specified can either be the name of a Newsagent feed, in which case all the articles in the generated feed will use the default viewer URL associated with that Newsagent feed, or it can be the name of a viewer URL. Note that directly specifying a URL is not supported: this argument requires a feed or viewer name, not a URL.

count=<number>

Lets you control how many items are included in the feed. The default is 10, there is a 'hard' maximum of 100 enforced by the system, and if count is set to a value over 100 it will be capped at 100.

offset=<number>

Lets you change where the feed starts from. Normally the feed starts with the newest item first, and then older items after it up to the count. With this you can tell it to skip items, so if you do offset=5, the first 5 newest items are skipped.

maxage=<number><d|m|y>

Controls the maximum age of the articles included in the feed. If this is specified, only articles less than the specified age will be included. The number specified is, by default, the age in days but you can append m or y to indicate that the number is a number of months or years, eg: maxage=6m will mean that the feed will include articles that are up to 6 months old, maxage=2y will include articles up to two years old. The default for this is 1y, ie: articles up to one year old will be included in the feed.

RSS elements

When requesting RSS feeds from Newsagent, each <item> in the feed will contain the standard RSS elements

• title contains the Subject set by the user, or the publication date if a subject was not set.
• link contains a link to an article viewer for the item.
• description contains the article summary, unless desc=fulltext has been set, in which case it contains the full article text.
• pubDate contains the publication date as a RFC 822 date-time value.
• guid is a globally unique id for the item.
• author contains the email address and name of the article author.

A number of custom elements will appear with each item, contained within a newsagent namespace:

• newsagent:gravatar contains the URL of the author's gravatar
• newsagent:feeds will contain one or more newsagent:feed elements, one for each Newsagent feed the article was posted in. Each newsagent:feed element has a name attribute that stores the short name of the Newsagent feed, while the element contains the full Newsagent feed name.
• newsagent:fulltext only appears when the fulltext argument was been specified when generating the feed, and desc=fulltext was not been set. It contains the full text of the article, and the format the text is in depends on the value set for the fulltext argument.
• newsagent:sticky appears in the item when the article has been set as "Sticky". It has a single epoch attribute containing the unix timestamp of the time and date the article will be sticky until. The element contents is the time and date the article will be sticky until as a human-readable RFC 822 date-time value.
• newsagent:images appears in the item when the article has one or more images associated with it. It has one or more newsagent:image children containing information about the images.
• newsagent:image each image associated with an article has a newsagent:image element associated with it in the RSS feed. It contains three attributes: the src attribute gives the URL of the image, the alt attribute contains alternative text for the image, and type contains the type of image:
  • lead for the Lead Image, if present the image will always be 130px x 63px.
  • article for the Article Image, which will always be at most 450px x 450px.
  • thumb for the Article Image thumbnail, which will always be at most 350px wide, and at least 167px high. This will always be present if an Article Image has been selected.