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 | |
|
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.
Please note that the order of feeds specified via this option is important when no viewer argument has been specified. Please see the Multiple Feeds documentation for more information. |
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. Thelevel
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 listlevel=home,leader
. Valid levels are currentlyhome
(Important (School Home Page)),leader
(Medium (Section Leader Page)), andgroup
(General (Group or Internal pages)). Omitting this option is equivalent tolevel=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>
orarticleid=<article id>
- Allows the selection of a specific article in the system by its internal id. In general, if you include the
id
orarticleid
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[1]- 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 thedesc
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[2]- 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 thefulltext
argument: if the feed is requested using the argumentsdesc=fulltext&fulltext=markdown
then the<decription>
will contain the full article text with markdown formatting, similarly if it requested usingdesc=fulltext&fulltext=embedimg
then the<decription>
will contain the full article html with the article image embedded if there is one. Note that, ifdesc=fulltext
is specified, but nofulltext
has been specified, thefulltext
will default toembedimg
.
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 dooffset=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
ory
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 is1y
, 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, unlessdesc=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 gravatarnewsagent:feeds
will contain one or morenewsagent:feed
elements, one for each Newsagent feed the article was posted in. Eachnewsagent:feed
element has aname
attribute that stores the short name of the Newsagent feed, while the element contains the full Newsagent feed name.newsagent:fulltext
only appears when thefulltext
argument was been specified when generating the feed, anddesc=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 thefulltext
argument.newsagent:sticky
appears in the item when the article has been set as "Sticky". It has a singleepoch
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 morenewsagent:image
children containing information about the images.newsagent:image
each image associated with an article has anewsagent:image
element associated with it in the RSS feed. It contains three attributes: thesrc
attribute gives the URL of the image, thealt
attribute contains alternative text for the image, andtype
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.
|