Who's There

Saving, please wait...
hover here for details

Help > Webmasters

 

Sign in forgot password? 

Register

It's Free to bring your
group to Who's There

Group Directory

Shared Stuff

Help and Support

 
 help pages 
 

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
What's On & Homepage
Who's There Page
Facebook App
iCalendar Feed
XML/JSON/JavaScript Data Feed
Embed HTML / Blog Code
Email Subscriptions
Public Files

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.

This page is also customisable. You can load in your own header and footer HTML and CSS - anything goes, see what you can create.

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.

Facebook App

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 Feed

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.

XML/JSON/JavaScript Data Feed

Who's There provides data feeds to the published events in XML and JSON formats as well as a complied JavaScript object that you can simply link to and use.

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

Parameter
Name
Value
Type
Description
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.

Example:

http://www.whosthere.co.uk/«group username»/json/?a=1&count=3&d=100

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

Root Child
Name
Value
Type
Description
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
generator String whosthere.co.uk
eventCount Integer Number of events included in this file

JSON Data Structure

Root Child
Name
Value
Type
Description
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)

JavaScript Variables

Variable Name Value
Type
Description
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

Object Name Value
Type
Description Availability
uid Integer Events unique identifier All
count Integer Event index. Starting at 0, increments by one for each event in the feed XML
name String Event Name All
date String Event date string in the format YYYY/MM/DD JSON
date String Event date in a JavaScript date object JavaScript
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.

Object Name Value
Type
Description Availability
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

Object Name Value
Type
Description Availability
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
name String Location Name All
address String Location Address 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
dateTime Date Event date and time in a JavaScript date object JavaScript
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.

Make sure the webpage you are pasting onto allows the use of external JavaScript in the HTML code, as Who's There won't work without it.

Grab the code from the Public Presence page in the group settings, or from your Webmaster Setting page, if you have one.

Example

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>
<script type="text/javascript">loadWhosThere('whosthere', '006600', '');</script>

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:

Argument
(braket section & name)
In the example
above
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.

Email Subscriptions

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" />
</form>

Public Files

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.

 

© 2006-2017 ben-robinson.com