|OS||Neutral (web based)|
Will not work with IE8 or older
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.
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.
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
/rsspath, so an example URL would be https://newsagent.cs.manchester.ac.uk/rss
- The HTML fragment generator is accessed through the
/htmlpath, 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/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.
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=<comma separated list of feeds>
feedoption 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,ugtwill 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.
|Please note that the order of feeds specified via this option is important when no
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
leveloption in the query. The
leveloption 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=homeor 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,groupwill produce a feed containing articles published in the PGT or PGR feeds at the Medium or General levels.
- Allows the selection of a specific article in the system by its internal id. In general, if you include the
articleidparameter 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.
- 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
descargument 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.
- 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
fulltextargument: if the feed is requested using the arguments
<decription>will contain the full article text with markdown formatting, similarly if it requested using
<decription>will contain the full article html with the article image embedded if there is one. Note that, if
desc=fulltextis specified, but no
fulltexthas been specified, the
fulltextwill default to
- Specify a article viewer to use rather than the default calculated one. If this is set to
viewer=internalthe 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.
- 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
countis set to a value over 100 it will be capped at 100.
- 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.
- 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
yto indicate that the number is a number of months or years, eg:
maxage=6mwill mean that the feed will include articles that are up to 6 months old,
maxage=2ywill 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.
When requesting RSS feeds from Newsagent, each
<item> in the feed will contain the standard RSS elements
titlecontains the Subject set by the user, or the publication date if a subject was not set.
linkcontains a link to an article viewer for the item.
descriptioncontains the article summary, unless
desc=fulltexthas been set, in which case it contains the full article text.
pubDatecontains the publication date as a RFC 822 date-time value.
guidis a globally unique id for the item.
authorcontains the email address and name of the article author.
A number of custom elements will appear with each item, contained within a
newsagent:gravatarcontains the URL of the author's gravatar
newsagent:feedswill contain one or more
newsagent:feedelements, one for each Newsagent feed the article was posted in. Each
newsagent:feedelement has a
nameattribute that stores the short name of the Newsagent feed, while the element contains the full Newsagent feed name.
newsagent:fulltextonly appears when the
fulltextargument was been specified when generating the feed, and
desc=fulltextwas 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
newsagent:stickyappears in the item when the article has been set as "Sticky". It has a single
epochattribute 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:imagesappears in the item when the article has one or more images associated with it. It has one or more
newsagent:imagechildren containing information about the images.
newsagent:imageeach image associated with an article has a
newsagent:imageelement associated with it in the RSS feed. It contains three attributes: the
srcattribute gives the URL of the image, the
altattribute contains alternative text for the image, and
typecontains the type of image:
leadfor the Lead Image, if present the image will always be 130px x 63px.
articlefor the Article Image, which will always be at most 450px x 450px.
thumbfor 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.
- This argument is ignored by the HTML feed. The full article text and article image are always included when the `full` HTML feed is used, and it is never included for `compact` or `feed`.
- This argument is ignored by the HTML feed, as it makes no sense to that generator.