Cosmopolite

Client/server publish/subscribe, presence and key/value storage for AppEngine

Cosmopolite Tutorial

AppEngine prerequisites

  1. Download and install the Python AppEngine SDK

Server-side setup

  1. Create an application in your SDK client
  2. Download cosmopolite via the links at left. Unpack it into your local application directory and rename the newly-created subdirectory to "cosmopolite"
  3. Create an app.yaml file for your application.
  4. Add a cosmopolite include to your app.yaml file: 
    includes:
- cosmopolite

inbound_services:
- channel_presence
  5. Start the application in your SDK client

Test cosmopolite

  1. Access your local cosmopolite debug page (replace port if necessary): http://localhost:8080/cosmopolite/static/debug.html
  2. Subscribe to a subject testsubject
  3. Send a message to that subject; it should appear in the message list below

Create a test page

  1. Create a test.html page at the top level of your application: 
    <html>
  <head>
    <script src="/cosmopolite/static/cosmopolite.js" charset="UTF-8"></script>
  </head>
  <body>
    <script>
// Subsequent script examples go here
    </script>
  </body>
</html>
  2. Add a mapping to app.yaml: 
    handlers:
- url: /test.html
  static_files: test.html
  upload: test.html
  3. Remove the mapping for main.app from app.yaml (if using the autogenerated file)
  4. Edit test.html. Replace "// Subsequent script examples go here" with: 
    var cosmo = new Cosmopolite();
cosmo.sendMessage('testsubject', 'test message');
  5. Keep the debug page up and subscribed (to testsubject) in one browser tab
  6. Load your test page
  7. The debug page should show the message from the test page
  8. You've written code that uses cosmopolite!

Subscribe to a subject

  1. Change test.html: 
    var callbacks = {
  onMessage: function(msg) {
    alert(msg['message']);
  },
};
var cosmo = new Cosmopolite(callbacks);
cosmo.subscribe('testsubject');
  2. Load (or re-load) the test page
  3. Use the debug interface to send a message to testsubject
  4. Your test page should generate an alert popup

Key/value store

  1. Cosmopolite can be used as a key/value store, with historical data and update notification
  2. When subscribing to a subject, you can request the most recent message for that subject
  3. Change test.html: 
    var cosmo = new Cosmopolite();
cosmo.subscribe('testsubject', 1).then(function() {
  var msg = cosmo.getLastMessage('testsubject');
  alert(msg['message']);
});
  4. Your test page should generate an alert popup showing the last message sent

Pin a value

  1. Pins publish a message temporarily, until the source conncetion disconnects. This can be used for presence information
  2. Open the debug interface and subscribe to testsubject
  3. Change test.html: 
    var cosmo = new Cosmopolite();
cosmo.pin('testsubject', 'browser is alive!');
  4. Load the test page and watch the debug page; you should see the pin.
  5. Close the test page, and the pin disappears.