150 lines
5.9 KiB
HTML
150 lines
5.9 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1">
|
|
<title>Cosmopolite Tutorial</title>
|
|
|
|
<link rel="stylesheet" href="stylesheets/styles.css">
|
|
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
|
|
</head>
|
|
<body>
|
|
<div class="wrapper">
|
|
<header>
|
|
<h1 class="header">Cosmopolite</h1>
|
|
<p class="header">Client/server publish/subscribe, presence and key/value storage for AppEngine</p>
|
|
|
|
<ul>
|
|
<li class="download"><a class="buttons" href="https://github.com/flamingcowtv/cosmopolite/zipball/master">Download ZIP</a></li>
|
|
<li class="download"><a class="buttons" href="https://github.com/flamingcowtv/cosmopolite/tarball/master">Download TAR</a></li>
|
|
<li><a class="buttons github" href="https://github.com/flamingcowtv/cosmopolite">View On GitHub</a></li>
|
|
</ul>
|
|
|
|
</header>
|
|
<section>
|
|
<h1>
|
|
<a name="cosmopolite" class="anchor" href="#cosmopolite"><span class="octicon octicon-link"></span></a>Cosmopolite Tutorial</h1>
|
|
|
|
<h3>AppEngine prerequisites</h3>
|
|
|
|
<ol>
|
|
<li>Download and install the <a href="https://developers.google.com/appengine/downloads">Python AppEngine SDK</a></li>
|
|
</ol>
|
|
|
|
<h3>Server-side setup</h3>
|
|
|
|
<ol>
|
|
<li>Create an application in your SDK client</li>
|
|
<li>Download cosmopolite via the links at left. Unpack it into your local application directory and rename the newly-created subdirectory to "cosmopolite"</li>
|
|
<li>Create an <a href="https://developers.google.com/appengine/docs/python/config/appconfig">app.yaml</a> file for your application.</li>
|
|
<li>Add a cosmopolite include to your app.yaml file:
|
|
<pre>includes:
|
|
- cosmopolite</pre></li>
|
|
<li>Start the application in your SDK client</li>
|
|
</ol>
|
|
|
|
<h3>Test cosmopolite</h3>
|
|
|
|
<ol>
|
|
<li>Access your local cosmopolite debug page (replace port if necessary): <a href="http://localhost:8080/cosmopolite/static/debug.html" target="_blank">http://localhost:8080/cosmopolite/static/debug.html</a></li>
|
|
<li>Subscribe to a subject <i>testsubject</i></li>
|
|
<li>Send a message to that subject; it should appear in the message list below</li>
|
|
</ol>
|
|
|
|
<h3>Create a test page</h3>
|
|
|
|
<ol>
|
|
<li>Create a test.html page at the top level of your application:
|
|
<pre><html>
|
|
<head>
|
|
<script src="/cosmopolite/static/cosmopolite.js" charset="UTF-8"></script>
|
|
</head>
|
|
<body>
|
|
<script>
|
|
// Subsequent script examples go here
|
|
</script>
|
|
</body>
|
|
</html></pre></li>
|
|
<li>Add a mapping to app.yaml:
|
|
<pre>handlers:
|
|
- url: /test.html
|
|
static_files: test.html
|
|
upload: test.html</pre></li>
|
|
<li>Remove the mapping for main.app from app.yaml (if using the autogenerated file)</li>
|
|
<li>Edit test.html. Replace "// Subsequent script examples go here" with:
|
|
<pre>var cosmo = new Cosmopolite();
|
|
cosmo.sendMessage('testsubject', 'test message');</pre></li>
|
|
<li>Keep the <a href="http://localhost:8080/cosmopolite/static/debug.html" target="_blank">debug page</a> up and subscribed (to <i>testsubject</i>) in one browser tab</li>
|
|
<li>Load <a href="http://localhost:8080/test.html" target="_blank">your test page</a></li>
|
|
<li>The debug page should show the message from the test page</li>
|
|
<li>You've written code that uses cosmopolite!</li>
|
|
</ol>
|
|
|
|
<h3>Time out for concepts</h3>
|
|
|
|
<ol>
|
|
<li><b>Subject</b>: a topic that clients that publish and subscribe to, e.g. "books"</li>
|
|
<li><b>Message</b>: a single chunk of data transmitted to a single subject, e.g. "I love books!"</li>
|
|
<li><b>Pin</b>: an ephemeral message that is deleted when the client that pinned it disconnects</li>
|
|
<li><b>Instance</b>: a single instantiation of Cosmopolite() in a browser (destroyed on page close)</li>
|
|
<li><b>Client</b>: a persistent identifier for a browser (consistent across browser restarts)</li>
|
|
<li><b>Profile</b>: a collection of clients that all speak as the same user (and so should appear the same to subscribers)</li>
|
|
</ol>
|
|
|
|
<h3>Subscribe to a subject</h3>
|
|
|
|
<ol>
|
|
<li>Change test.html:
|
|
<pre>var callbacks = {
|
|
onMessage: function(msg) {
|
|
alert(msg['message']);
|
|
},
|
|
};
|
|
var cosmo = new Cosmopolite(callbacks);
|
|
cosmo.subscribe('testsubject');</pre></li>
|
|
<li>Load (or re-load) the <a href="http://localhost:8080/test.html" target="_blank">test page</a></li>
|
|
<li>Use the debug interface to send a message to <i>testsubject</i></li>
|
|
<li>Your test page should generate an alert popup</li>
|
|
</ol>
|
|
|
|
<h3>Key/value store</h3>
|
|
|
|
<ol>
|
|
<li>Cosmopolite can be used as a key/value store, with historical data and update notification</li>
|
|
<li>When subscribing to a subject, you can request the most recent message for that subject</li>
|
|
<li>Change test.html:
|
|
<pre>var cosmo = new Cosmopolite();
|
|
cosmo.subscribe('testsubject', 1).then(function() {
|
|
var msg = cosmo.getLastMessage('testsubject');
|
|
alert(msg['message']);
|
|
});</pre></li>
|
|
<li>Your test page should generate an alert popup showing the last message sent</li>
|
|
</ol>
|
|
|
|
<h3>Pin a value</h3>
|
|
|
|
<ol>
|
|
<li>Pins publish a message temporarily, until the source conncetion disconnects. This can be used for presence information</li>
|
|
<li>Open the debug interface and subscribe to <i>testsubject</i></li>
|
|
<li>Change test.html:
|
|
<pre>var cosmo = new Cosmopolite();
|
|
cosmo.pin('testsubject', 'browser is alive!');</pre></li>
|
|
<li>Load the <a href="http://localhost:8080/test.html" target="_blank">test page</a> and watch the debug page; you should see the pin.</li>
|
|
<li>Close the test page, and the pin disappears.</li>
|
|
</ol>
|
|
|
|
</section>
|
|
</div>
|
|
<script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-37845853-2', 'auto');
|
|
ga('send', 'pageview');
|
|
|
|
</script>
|
|
</body>
|
|
</html>
|