Integration Guide & Examples
Who's There publishes your event data out in many different formats, for lots of different purposes. This page helps you understand the options and gives examples where they might be used:
Click the options of the left for more information:
Basics: Public Presence and Public Events
1) Enable Public Presence
All of the features described on this page only work if your group has the "Public Presence" option switched on. If you don't want any of your information entering the outside world, just turn this option off.
The Public Presence option is found in the group settings section of Who's There. It can only be controlled by a group administrator, so if this isn't you, get them to turn it on.
2) Publish Events
Just having Public Presence turned on, doesn't mean that all your events will be seen. Only events that are "Published" will be available publicly.
This allows you to hide private events and make sure an event is fully complied before it can seen by the public.
Events can only be published by authorised members - if you cannot publish an event, ask your administrator
To publish an event, simply click the newspaper icon (shown here) in the bottom left corner of an events details
3) Make Locations Private
Every event can have multiple locations. Sometimes the details of those locations are private, if so, just tick the box (in the P column) and the location will be hidden from within your public event.
What's On & Homepage
The main homepage of at whosthere.co.uk, seen by users who aren't signed in, lists all the published events from all groups.
The events are shown with a map, allowing users to find events near where they live.
Members who are logged in can see the same information on the What's On page.
Who's There Page
Every group on Who's There gets their own webpage. It is essentially the same as the homepage (in the previous section) but only listing events for your group.
Customise your Who's There Page
Group administrators can configure the Who's There page on the Public Presence page in the Group settings.
Group administrators can also choose any other full member to be a webmaster. Webmasters have a "Webmaster Settings" link in the main menu on the left and can configure the public page in their own time - if you need this access, ask your administrator
The settings are relatively straight forward, follow the instructions that apear in the popup window
Who's There Page URLs:
Your groups page is at whosthere.co.uk/«group username» - This username was chosen when the group was created, but can be set to anything, at any time, provided it's not in use.
Who's There has a Facebook App. With it Who's There will automatically post your events onto Facebook. It will also keep the events up to date should any of the information change, and even delete the event if you cancel it or stop it from being published.
Who's There will post events to any "Facebook Page".
Who's There administrators will delegate a "facebooker" - a member of Who's There with Admin rights over the Facebook Page.
Members can install the Facebook App at anytime by visiting http://www.whosthere.co.uk/members/me/facebook
Once a facebooker has been chosen, and the App is installed, group administrators and facebookers can specify the Facebook Page ID (either on the Facebook page or the Public Presence page) - As soon as that is done, the event syncing will begin.
Detailed information on how this feature works can be found on http://www.whosthere.co.uk/members/me/facebook - more information is available on this page when the app is installed.
iCalendar is the standard format for sharing calendars of events. Most modern calendar applications support this format and have a Subscribe or New Calendar from URL feature. See the help for your calendar, but basically you just have to copy and paste an iCalendar web address into your calendar.
iCalendar feeds can also simply be downloaded and imported into calendar apps as a one-time export of events.
All groups will Public Presence turned on automatically have a iCalendar feed that the public can subscribe to - In fact, Who's There is a great iCalendar creation tool.
To find a groups iCalendar feed, look in the group directory. There are actually 2 URLs; whosthere.co.uk/«group username»/ical/ takes you to a page with links to the iCalendar feed for common calendar systems. whosthere.co.uk/«group username»/ical/feed/ is the actual feed, linked to from the first address.
The data structure for each of these formats is essentially the same; and is detailed below.
All the feeds also take a series of querystring parameters to control which events will be loaded.
The feeds are available at /xml/, /json/ and /js/ from your groups page - e.g. www.whosthere.co.uk/«group username»/xml/ for the xml feed. All the feed addresses are listed on the Public Presence page and the Webmaster settings page.
Example (PHP & XML)
The zip file below contains an exmaple of how you might use PHP to load and display an XML feed. Copy both files to your web server and try it out.
Query String Parameters
|a||1||Required: Tells the feed you will be suppling querystring values|
|count||Integer||The number of events to return. Omit to return all events.|
|confirm||1||Add this to only return confirmed events. Omit to return all events.|
|cancel||1||Add this to return all events, even if they have been cancelled. Omit to return only events that are not cancelled.|
|x||Float||Longitude center point for mapped results. Omit to use the groups default center location.|
|y||Float||Latitude center point for mapped results. Omit to use the groups default center location.|
|d||Float||Distance; specify a number in miles to limit the result to only those within d miles of the center point (x,y). Omit to return all events.|
This will return the next 3 (chronologically) events that are with 100 miles of the groups center point.
XML Data Structure
The root element is events
|event||Event||Occurs once for each event, see below for the description of an Event|
|title||String||Document title; group name followed by the word "Events"|
|link||String||The link back to the groups Who's There page|
|eventCount||Integer||Number of events included in this file|
JSON Data Structure
|events||Array of Event||Main event array, see below for the description of an Event|
|groupName||String||Groups Full Name|
|groupUserName||String||Groups username (used in the Who's There page address)|
|wtEvents||Array of Event||Main event array, see below for the description of an Event|
|wtGroupName||String||Groups Full Name|
|wtGroupUserName||String||Groups username (used in the Who's There page address)|
Event Data Type
|uid||Integer||Events unique identifier||All|
|count||Integer||Event index. Starting at 0, increments by one for each event in the feed||XML|
|date||String||Event date string in the format YYYY/MM/DD||JSON|
|formmatedDate||String||Fully formatted date, relative to the current date (i.e. Today, Tomorrow, Tuesday, etc)||All|
|year||Integer||Year of event (YYYY)||XML|
|month||Integer||Month number of event (1-12)||XML|
|day||Integer||Day of event in month (1-31)||XML|
|distance||Float||The distance the event is (average of location positions) from the provided x,y position, or the groups default location.||All|
|groupCount||Integer||Number of groups this event belongs to in this feed - always 1||XML|
|group||Group||Occurs once for each group (once), see below for the description of a Group||XML|
|groups||Array of Group||Main group array, see below for the description of a Group. groups.length always equals 1||JSON, JS|
|locationCount||Integer||Number of locations in this event||XML|
|location||Location||Occurs once for each location, see below for the description of a Location||XML|
|locations||Array of Location||Main location array, see below for the description of a Location.||JSON, JS|
|locationMarkers||Integer||Number of locations that have a mappable location (longitude and latitude)||All|
Group Data Type
The group object contains group specific data. When an event is shared between multiple groups these properties can differ from group to group. Because you are accessing just your groups data there will only ever be one group object.
|groupUid||Integer||Groups unique identifier||XML|
|uid||Integer||Groups unique identifier||JSON, JS|
|groupUserName||String||Groups username (used in the Who's There page address)||XML|
|userName||String||Groups username (used in the Who's There page address)||JSON, JS|
|groupName||String||Groups full name||XML|
|name||String||Groups full name||JSON, JS|
|notes||String||Public notes attached to an event||All|
|confirmed||Boolean||True is an event is confirmed, false if not (lowercase true or false string in XML)||All|
|cancelled||Boolean||True is an event is cancelled, false if not (lowercase true or false string in XML)||All|
|facebookId||String||Id of event on Facebook, or empty if there is no link to Facebook for this event. Event can be accessed at http://facebook.com/«facebookId»||All|
Location Data Type
|locationUid||Integer||Location unique identifier||XML|
|uid||Integer||Location unique identifier||JSON, JS|
|savedLocationUid||Integer||Unique identifier of saved location point - this ID is usable and reusable by all groups to refer to a single map location||All|
|count||Integer||Location index. Starting at 0, increments by one for each location in the event||XML|
|markerId||String||Name of map marker. If there is only one map location this is "marker", if there are multiple map markers each location will have an incrementing letter (markerA, markerB, markerC, etc...)||All|
|newDate||Boolean||True if this location has a different date to the previous location, false if the date is the same as the previous location. The first location will always be true. (lowercase true or false string in XML)||All|
|dateTime||String||Event date and time string in the format YYYY/MM/DD HH:MM:00||JSON|
|Year||Integer||Year of event (YYYY)||XML|
|Month||Integer||Month number of event (1-12)||XML|
|Day||Integer||Day of event in month (1-31)||XML|
|Hour||Integer||Hour of event in day (0-23)||XML|
|Minute||Integer||Minute of event in hour (0-59)||XML|
|allDay||Boolean||True if this event has no time (or the time should be ignored), otherwise false. (lowercase true or false string in XML)||All|
|formmatedDate||String||Fully formatted date, relative to the current date (i.e. Today, Tomorrow, Tuesday, etc)||All|
|formmatedTime||String||Fully formatted time||All|
|lng||Float||Longitude point on the map||All|
|lat||Float||Latitude point on the map||All|
Embed HTML / Blog Code
Who's There provides a snippet of HTML that can be copied and pasted onto any website that allows you to insert HTML code.
The code produces a live, updating list of the events current published on Who's There.
Grab the code from the Public Presence page in the group settings, or from your Webmaster Setting page, if you have one.
This is what the code snippet looks like - make sure you enter your groups username (twice!) if you copy the code below
<script src="http://www.whosthere.co.uk/«group username»/js/"></script>
<script src="http://www.whosthere.co.uk/«group username»/js/func.js"></script>
<div id="whosthere" style="height:350px; width:300px;"></div>
Changing the Colour and Font
You can change the colours and fonts used in the Who's There box that this code snippet produces
The secret is in the last line of the code, after the text "loadWhosThere". In the brakets that follow there are 3 sections that control where the box will load, what colour it will be and what font it will use, as follows:
(braket section & name)
|In the example
|What it means|
|1 - Node ID||'whosthere'||
Advanced users only!
This is the element name where the box will load - it must match the id on line 3.
|2 - Colour||'006600'||
This is the hexadecimal colour of the box - it must be a 6 digit hex number, don't use names!
Have a look at this colour pallet
If you leave it blank (just quote marks) the colour blue will be used (0000CC).
|3 - Font||''||
This is the font and size, enter in standard, single line, CSS
Have a look at the examples here
If you leave it blank (just quote marks, as above) the font 12px Verdana will be used.
Members of the public can subscribe to email notifications for any group with a public presence.
Email are sent out around one hour after you finish editing the event, unless the event is on the same day, then it will be sent within a few minutes.
Subscribers are only sent an email once for each event. They are requested to check the website for any changes to the event.
To find a groups email subscription feed, look in the group directory, your groups feed can be found at: whosthere.co.uk/«group username»/email/
Embed into your website
Copy the code below if you would like to add the subscribe form on your website (make sure you enter your groups username into the pasted code). All you need to do is POST a valid email address (with the name email) and the variable go=1 to your groups email subscription page.
<form method="post" action="http://www.whosthere.co.uk/«group username»/email/">
<input type="text" name="email" />
<input type="hidden" name="go" value="1" />
<input type="submit" value="Subscribe" />
Who's There can host files on your behalf on your public page.
When Public Presence is enabled, you will find a Public folder in the Files section of Who's There. Any files saved into this folder, or its subfolders will be visible on your public files page.
The files can be found at: whosthere.co.uk/«group username»/files/
A link to your public files will be shown in the group directory, if you have any.