Specification
This document is intended for webmasters who use feeds from talks.cam on their pages. It provides a sense of what to expect from the service. This is more of a reference page - for more practical information, find out more about disseminating talks.
The document is currently being edited to create a first draft and should be treated as highly provisional.
Talks.cam public specification
- The level of service provided by talks.cam
- The structure and content of feeds provided by talks.cam
Filtering of user generated content
Any html entered into any field except the talk abstract and list description will be filtered to remove any html tags and therefore reduce the chance of cross-site script attacks. The talk abstract and list description allow html according to a white-list. The white-listed tags are: a, img, br, i, u, b, pre, kbd, code, cite, strong, em, ins, sub, sup, del, table, tr, td, th, ol, ul, li, p, h1, h2, h3, h4, h5, h6, blockquote. The only attributes permitted on tags are a: href, title; img: src, alt, title; code: lang; td: colspan, rowspan; blockquote: cite. Other tags can be created using the textile formatting language. All javascript and event triggers are stripped.
Structure and content of feeds
Feeds are used to take talks.cam content and use it on other websites. Some examples are at http://www.inference.phy.cam.ac.uk/talks/penguin/compatible.html
General structure of URL
The general structure of a url to get a feed from talks.cam is:
http://www.talks.cam.ac.uk/show/FORMAT/LISTID
LISTID is the number identifying the list
FORMAT may take these values:
| index | The default talks.cam look, with talk title, speaker, venue, date & time on separate lines. No logos. |
| old_talks | Compatible with the old version of talks.cam. Groups talks by day. Provides logo. |
| table | Talks laid out as a table, with columns for date, speaker, title and venue. One row per talk |
| minimalist | Talks laid out, one talk per paragraph, with just the title and speaker. |
| detailed | Talks laid out in blocks, including abstracts and all details |
| simplewithlogo | Talks grouped by day, with just the title, speaker and logo |
| oneday | Similar to the table view, but without the venue information and with the series details at the top |
| text | As plain text, no html. Series title and details at top. Talks grouped by day bellow. |
| xml | As xml, detail below |
| rss | As xml using the rss schema, details below |
| ics | As a series of VEVENTS in an icalendar spec, details below |
/show/archive/LISTID is a special case - it is simply a convenience shortcut to /show/index/LISTID?seconds_after_today=0&reverse_order=true
General structure of parameters
The url may be qualified with the following optional optional parameters:
| layout | Governs the way the feed is wrapped. Details below. |
| limit | The maximum number of talks to display, integer |
| seconds_before_today | Displays only talks with a start time no earlier than the given number of seconds before midnight this morning |
| seconds_after_today | Displays only talks with a start time no later than the given number of seconds after midnight this morning |
| start_time | Displays only talks with a start time no earlier than the given time |
| end_time | Displays only talks with a start time no later than the given time |
| term | Displays only talks that fall within the current term (if set to current) or to the relevant term at the given time. Please see the note on terms below. |
If several parameters are used that restrict the number of talks displayed, then the restrictions will be ANDed.
If no parameters are provided, then all talks in the list whose start_time is after midnight this morning will be displayed.
Time
Time is specified in seconds since the start of 1970.
Possible layouts
Possible values for the optional layout parameter are:
| with_related | The default look with header, footer and left and right sidebars |
| minimal | With the header and footer, but no sidebars |
| empty | Does not wrap the talks in anything |
| embed | Wraps the talks for use in a javascript tag. See below for detail. |
| embedcss | Wraps the talks for use in a javascript tag and embeds appropriate css. See bellow for detail. |
A note on term dates
Talks.cam assumes that there are four terms a year:
| Jan,Feb,Mar | is Lent term |
| Apr,May,Jun | is Easter term |
| Jul,Aug,Sep | is Summer "term" |
| Oct,Nov,Dec | is Michaelmas term |
Embedded (javascript) feeds
Lists of talks can be embedded in webpages by using code of the following form:
<script language="javascript" src="http://www.talks.cam.ac.uk/show/index/5606?layout=embed" type="text/javascript"></script>
If the person who views the webpage has javascript enabled, their browser will request javascript code from talks.cam and run it in the context of the webpage. The talks.cam code loaded is of the form:
document.write("html fragments that display the talks")
The html fragments will contain html created by the talks.cam system. If layout=embed is used, then the webpage must provide appropriate css to format the page. If layout=embedcss is used, then talks.cam will provide some basic css to format the talks.
To ensure proper (and safe) display of the feed, the webpage server MUST specify that the page is encoded in the UTF-8 character set.
Please be aware that if someone was able to tamper with the talks.cam system, they could add malicious javascript to the talks.cam feed. This would allow them to change the appearance of your webpage, and potentially clone the webpage user's identity.
To reduce the possibility of tampering with talks.cam it is hosted on a server where every attempt has been made to secure access. Remote login access is restricted to a small number of talks.cam managers. However, the server is shared with several other web sites, which means its potential for compromise has been increased.
Other formats
Changes to this document
From first draft stage up to migration to wiki.cam.ac.uk:
- 2007/02/12 First draft
- 2007/02/23 Updated to reflect comments from Helen Sargan. Outstanding question over scope of whitelisted tags in user generated content.
- 2009/03/21 Refactored to split some stuff out into separate pages: Syndicating talks, Rules and regulations, XML feeds, RSS feeds, iCalendar feeds
- 2010/06/11 Minor update to document /show/archive/ URL
- 2016/06/29 Migrated from talks.cam.ac.uk native wiki to wiki.cam.ac.uk.
Please see wiki page history for details of subsequent changes.
