The Atmail mashup API allows developers to create applications to access email, contact and calendaring data from the Atmail engine.
The API returns data in JSON format, which can be easily parsed by Javascript apps, PHP, Java, or any language you care to use.
A whole new world of possibilities open with the Atmail API - Developers can easily integrate Atmail into a corporate Intranet, consumer portal for an ISP, web-mashup on an existing web-site or pull Atmail data into existing applications.
For this tutorial we are going to walkthrough a sample to pull calendar events, and pin-point the location of each event on a map.
View an online demo at: http://atmail.com/downloads/mashups/atmailmappa/index.html
Download the source-code at: http://atmail.com/downloads/mashups/atmailmappa.tgz
Step-1: Download and extract the atmailmappa.tgz into your existing web-site, e.g mydomain.com/atmailmappa/
Step-2: Signup for a Google Maps API key and replace the following in the index.html
http://maps.google.com/maps?file=api&v=2&sensor=true&key=MYAPIKEY
Step-3: Edit the index.html and define your URL to the Atmail Webmail instance
var url = ‘http://a6demo.atmail.com/’;
Step-4: Next, if you are using the mashup outside of your Atmail Webmail domain ( e.g http://portal.company.com ) you must query the server using JSON-P. This allows Javascript to load data outside of its local domain. To enable JSON-P make sure this is toggled on via the Atmail Webadmin > Services > API Access > JSON-P = On
If you will be querying the Atmail mashup API outside of your local domain, define the following below the URL call:
$(this).setjsoncallback(1); // Set to 1 for JSON-P, or 0 for regular JSON
Step-5: Login to your local Atmail Webmail instance with a valid username/password. Visit the Calendar tab and create various appointments with an address defined in the ‘Location’ field
Step6: Reload the URL you installed the atmailmappa.tgz and you will see a Google map with the location of events you created via the Webmail interface!
How does it work?
The above mashup is a simple example which uses the Atmail calendar API to download a list of events in JSON format and plunk the location and event name to insert onto a copy. A walk-through of the source-code is below:
var url = ‘http://a6demo.atmail.com/’;
$(this).setjsoncallback(1);
$(”A.login”).bind(’click’, function() {
location.href= url;
});
$(”BODY”).checkLogin({
url: url,
error: function() {
$(”DIV.login”).fadeIn(’fast’);
},
The first part of the Javascript loads an authentcation request as the specified domain. The checkLogin function will validate if an existing cookie/sessionId exists and will pre-authenticate the user. If no valid Atmail sessionId/cookie is found, the login DIV will fade to the display prompting the user to first login.
success: function() {
var calendarUrl = url + “index.php/api/calendar/list/” + $(this).jsoncallback();
var params = { format: ‘json’ };
var locations = new Array();
var i=0;
$.getJSON(calendarUrl, params, function(json) {
if ( json ) {
$.each( json, function(i, n) {
var item = json[i];
if(item.Location != ‘’) {
locations.push({address: item.Location, html: item.Title + ‘
‘ + item.DateStartCal + ‘ ‘ + item.DateStartTime + ‘
(’ + item.Location + ‘)’});
i++;
}
});
Next, on success of an authentication request, the function will request a list of calendar events from the Atmail API. The data is returned in a JSON packet, which is looped as an array. For each calendar event with a location field defined, the locations array will expand with the address location and title of the event. Interesting attributes for the calendar entry include item.Title, item.Location and item.DateStartCal and item.DateStartTime
$(”#map”).gMap({ markers: locations, zoom: 12});
Lastly, once a location in the calendar has been defined we map the result using the excellent jQuery plugin gMap.
Below are some ideas which could be incorporated for a real-world use of the calendar mashup:
- A logistics company could supply drivers with an iPhone with the native calendar-app communicating to the CalDAV server of Atmail. Each pickup/delivery would be a calendar event with an assigned location. Back at HQ the mashup could provide an overview map display of all active pickup/deliveries for the day for management to monitor and keep updated in the field.
- A musician may keep track of upcoming events using the Atmail calendar using Atmail Webmail and publish a mashup of the calendar map on their website sidebar. Visitors to the site will be able to see upcoming gigs on a map, based on their current location.
- Sales consultant in the field could keep track of events using the Atmail calendar (desktop CalDAV apps, mobile or WebUI) and map their upcoming meetings on a map.
The mashup API opens the gateways for possible extensions to Atmail - We welcome your feedback and mashup submissions to include on our site.
Atmail RSS Feed