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

1. The level of service provided by talks.cam
2. 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

• iCalendar feeds
• XML feeds
• RSS feeds

Changes to this document

1. 2007/02/12 First draft
2. 2007/02/23 Updated to reflect comments from Helen Sargan. Outstanding question over scope of whitelisted tags in user generated content.