ms.trinity

Previously in our adventures, we talked about using various google services for tasks common to sharepoint. While this was a fun little undertaking on my part, I realize that I’m doing you all a huge disservice. What I need to show you is what you CANNOT do with sharepoint, things that you didn’t even imagine you would be able to achieve, while having fun doing it.

Thank you google, for bringing the joy back to development.

Here is the completely free suite of tools you need to have set up and configured to do everything I’m about to do here.

Google App Engine
Aptana 3

Python is easy, don’t be scared. I hadn’t written python before last week, so there you go. The only thing you really need to know going into this is javascript.

Bi-Directional communication in a nutshell: html5 websockets that enable client <-> server communication. The client does not have to initiate the call to retrieve data, check for changes, etc. The server instead can “push” data to the client. Something happens on the server (workflow) and all clients are notified without having to ask if something happened.

So… what should we build? I want to meet a real business need. I want it to be mobile ready. I want it to be rad and fun to use (which should be a requirement in all applications, but i digress… )

Since I don’t have anyone clamoring for a solution to their specific problem, I’ll have to draw from my own life experience for a real world example. Specifically my non-technical experience. Have I ever mentioned I was once a hooters girl? only for a day. just to be able to say that. But I did bartend for quite a long time, before university… the service industry was very good to me.

In some Utopian world I have yet to find and intend to create, small businesses like pubs and clubs wouldn’t see eachother as competition… to the contrary! they would see eachother as co-conspirators with the common goal of providing the customer with a memorable and pleasant experience. They would collaborate on ways to ensure a good time was had, no matter the location, down to delivery of the blissful person and interested parties to their destination safely.

Here is what we will build.

An app engine powered application which will:

• allow for clubs to sign up to be part of the network. They provide their name and address and are provided with a dashboard page that will be their own view of the application.
• allow customers to “check in” at any of the locations, and send messages to the locations dashboard
• send messages using bi-directional communication channels to all users or to specific users, from the server or from other users.

a little video to see it in action. whats mind boggling is now ridiculously FAST this application is.

the full source for the project is available at https://github.com/nebulae/RoadRunner

more info about channels and bi-directional communication
the objects to be stored: more info about using the data store

#each establishment being added, to be displayed on the map
class Location(db.Model):
    name = db.StringProperty()
    address = db.PostalAddressProperty()
    latitude = db.FloatProperty()
    longitude = db.FloatProperty()
    person = db.UserProperty()
    placekey = db.StringProperty()

#each connection to the application
class Connection(db.Model):
    person = db.UserProperty()
    channelKey = db.StringProperty()
    latitude = db.FloatProperty()
    longitude = db.FloatProperty()

to store the locations and connections:

def addLocation(name, address, lat, lon):
    user = users.get_current_user()
    if(user):
        placekey = str(uuid1())
        location = Location(key_name = placekey)
        location.person = user
        location.name = name
        location.placekey = placekey
        location.address = address
        location.latitude = lat
        location.longitude = lon
        location.put()
        return placekey    

def addConnection():
    user = users.get_current_user()
    if user:
        userkey = user.user_id()
        connection = Connection(key_name = userkey);
        connection.person = user
        connection.channelKey = userkey;
        connection.put();
        return userkey;

when the page initializes, the channel is created so we can listen for server events and act upon them. the ‘onMessage’ function will be the entry point for all server messages. depending on the action supplied with the message, different things are done with the data sent through.

openChannel = function() {
  var token = '{{ token }}'; // this is a template variable defined in the app.py MainPage endpoint response
  var channel = new goog.appengine.Channel(token);
  var handler = {
    'onopen': onOpened,
    'onmessage': onMessage,
    'onerror': function() {},
    'onclose': onClose
  };
  var socket = channel.open(handler);
  socket.onopen = onOpened;
  socket.onmessage = onMessage;
}

when the user clicks “add me”, a little javascript is called –

  $('.addMe').unbind().click(function(){
    if($('input.name').val()!='' && $('input.address').val()!=''){
// this will add an address to the locations storage and send via socket the new location to draw on the map to ALL the connected users.
      sendMessage('/lookupaddress', "address=" +
        $('input.address').val() + "&name=" + $('input.name').val());
    }
  });

// calls back to the app engine listening for /addme
sendMessage = function(path, opt_param) {
  path += '?g=' + state.key;  // I'm setting this as the userid, but could be anything you want it to be.
  if (opt_param) {
    path += '&' + opt_param;
  }
  var xhr = new XMLHttpRequest();
  xhr.open('POST', path, true);
  xhr.send();
};

the app engine maps the endpoint (lookupaddress) to the receiver (AddAddress):

application = webapp.WSGIApplication([('/', MainPage), #initial landing page
                                      ('/handshake', Handshake), #after connection is created, dispatch whatever updates need to be sent to users
                                      ('/lookupaddress', AddAddress), #adds a new establishment
                                      ('/onmyway', OnMyWay), #notified the establishment that a user is on the way
                                      ('/mylocations', MyLocations), #provides the user a view of all their establishments they added
                                      ('/closed', ConnectionClosed)],debug=True)

the receiver checks the address and gets the lat / long to display from googles geocoding. if it comes back correctly, the location is stored and an update is sent to all the locations.

class AddAddress(webapp.RequestHandler):
    def post(self):
        address = self.request.get('address');
        name = self.request.get('name');
        key = self.request.get('g');
        querystring = { 'address' : address, 'sensor' : 'false' }
        url = "http://maps.googleapis.com/maps/api/geocode/json?" + urllib.urlencode(querystring)

        result = urlfetch.fetch(url)
        res = simplejson.loads(result.content)
        if(res['results'][0] != None):
            lat = res['results'][0]['geometry']['location']['lat']
            lon = res['results'][0]['geometry']['location']['lng']
            address_formatted = res['results'][0]['formatted_address']
            logging.log(logging.INFO, name)
            placekey = addLocation(name, address_formatted, lat, lon)
            response = {
                    'action': "display_address_lookup", #action recieved in javascript onMessage
                    'results' : "congrats!  you have successfully added your location.",
                    'placekey' : placekey
                    }
            channel.send_message(key, simplejson.dumps(response))
#kick off an update to all the users
            update = LocationsUpdate()
            update.dispatch(placekey)
        else:
            response = {
                    'action': "display_address_lookup",  #action recieved in javascript onMessage
                    'results' : "The address could not be found.  please check the address and try again."
                    }
            channel.send_message(key, simplejson.dumps(response))

the new location is dispatched to all the connections:

class LocationsUpdate():
    action = "display_locations";
    def dispatch(self, placekey = None):
        locations = [];
        if(placekey != None):
            location_query = Location.gql("where placekey='" + placekey + "'");
        else:
            location_query = Location.all();

        for location in location_query:
            locations.append({
                              'name': location.name,
                              'address' : location.address,
                              'latitude' : location.latitude,
                              'longitude' : location.longitude,
                              'placekey' : location.placekey
                              }
            );
        people_query = Connection.all();
        response = { 'action': self.action, 'locations' : locations }
        for connection in people_query:
            logging.log(logging.INFO, "to " +
                        connection.channelKey + ": " +
                        simplejson.dumps(response))
            channel.send_message(connection.channelKey, simplejson.dumps(response));

which triggers some javascript to drop the new location marker onto the map, and offer functionality to “check in” at the location and send a message.

onMessage = function(m) {
  $m = eval("("+m.data+")");
    if(!!$m.action){
      switch($m.action){
//...
        case "display_locations":
          bindLocations($m.locations);
          break;
// ...
     }
   }
}

bindLocations = function(locations){
  $(locations).each(function(){
    var obj = $.grep( markers, function(n,i){
      return n.title == this.title;
    });
    if(obj.length < 1) {
      var placelatlon = new google.maps.LatLng(this.latitude,this.longitude);
      var marker = new google.maps.Marker({
        position: placelatlon,
        title : this.address,
        animation: google.maps.Animation.DROP
      });

      var infowindow = new google.maps.InfoWindow({
        content: createLocationForm(this)
      });
      google.maps.event.addListener(marker, 'click', function() {
        infowindow.open(map,marker);
// set up the form for the user to send the location / establishment a message and let them know they're coming.
// this will send a notification to the user who added the location, but noone else.
        $('.onMyWayButton').unbind().click(function(){
          sendMessage('/onmyway', 'message=' + $('div[placekey='+$(this).attr('placekey')+']').find('textarea').val() + '&placekey=' + $(this).attr('placekey'));
        });
      });
      markers.push(marker);
    }
  });
  $(markers).each(function(idx, marker){
    setTimeout(function() {marker.setMap(map);}, idx * 200);
  });
}

... and thats it. I'm not going to detail out all of the python / javascript, this should give you the low down about how simple this communication mechanism really is. Ajax but better with this example you were able to send a message from one user to another, and have that message show up instantaneously in the users browser, and you were also able to send a message from the server to all connected users, and have all connected users see that updated location drop into place immediately.

This is SERIOUSLY cool functionality. hope you enjoyed, and I'd love to take this to another level of usability so please comment if theres anything you would like to see. There is so much available in this, I left some other functionality in there as well like querying a folder of documents and displaying the titles.

FYI: all images, buttons, and other graphics were created by yours truly with the gimp (free), on ubuntu (free) with aptana (free) and the google app engine with python (free and free), the desktop recording was done with gtkRecordMyDesktop (free) and encoded with mencoder (free). source control is done via git on github (free and free). are you seeing a pattern yet? there are options people, wonderful, powerful, free, open source, reliable secure and just flat out RAD options. I encourage you to explore

peace,
trin