Clarify a few examples and add a new explicitly-incremental streaming example

Author: Seth Kinast

examples/basic-browser/README.md

@@ -1,6 +1,10 @@
-To run:
+To install:
 
-    bower install && ../../bin/dustc views/*.dust --output=lib/compiled.js
+    npm install && bower install
+
+To (re)compile templates:
+
+    ../../bin/dustc views/*.dust --output=lib/compiled.js
 
 Then load `index.html` in your browser.
 

examples/streaming-hoffman/README.md

@@ -8,4 +8,6 @@ The example proxies dustjs.com through your local server (after an artificial de
 
 Hoffman handles template loading and will reload and recompile templates each time they are loaded until you turn view caching on. For production, you'd want to turn caching on.
 
+Note that Hoffman doesn't always use the most up-to-date version of Dust, so you might need to manually upgrade it by editing its `package.json` file.
+
 More info on Hoffman: https://www.npmjs.com/package/hoffman

examples/streaming-hoffman/package.json

@@ -4,7 +4,6 @@
   "description": "Use Hoffman to enhance Dust streaming with Express",
   "main": "app.js",
   "dependencies": {
-    "dustjs-linkedin": "^2.6.1",
     "express": "^4.12.3",
     "hoffman": "^0.1.4",
     "request": "^2.53.0"

examples/streaming-incremental/README.md

@@ -0,0 +1,9 @@
+To run:
+
+    npm install && npm start
+
+This example explicitly shows how Dust streams and flushes chunks to the browser.
+
+If you use Dust's rendering interface, the callback is invoked once the entire template is done rendering. Therefore, your template will render as slowly as your slowest asynchronous call. Notice how the `/rendering` endpoint does not load for 10 seconds, even though you can see in the console that Dust is working on rendering the async blocks.
+
+If you use Dust's streaming interface, Dust flushes pieces of your template to the browser as soon as they are done. However, Dust can't stream out-of-order, because browsers don't know how to interpret responses that are not in-order. This means that even if a chunk is done early, it has to wait for all previous chunks to complete.

examples/streaming-incremental/app.js

@@ -0,0 +1,65 @@
+var fs = require('fs'),
+    path = require('path'),
+    express = require('express'),
+    dust = require('dustjs-linkedin'),
+    q = require('q');
+
+// Define a custom `onLoad` function to tell Dust how to load templates
+dust.onLoad = function(tmpl, cb) {
+  fs.readFile(path.join('./views', path.resolve('/', tmpl + '.dust')),
+              { encoding: 'utf8' }, cb);
+};
+
+var app = express();
+
+var position;
+
+app.get('/', function (req, res) {
+  dust.render('index', {}, function(err, out) {
+    res.send(out);
+  });
+});
+
+app.use(function(req, res, next) {
+  console.log('\n\nBeginning the render of', req.path);
+  next();
+});
+
+app.get('/streaming', function(req, res) {
+  position = 1;
+  dust.stream('hello', {
+    'wait': function(chunk, context, bodies, params) {
+      var delayMilliseconds = parseInt(params.delay, 10) * 1000;
+      // Returning a Promise-- Dust will wait for the promise to resolve
+      return q(position++).delay(delayMilliseconds)
+              .then(function(position) {
+                console.log('Rendering', params.name, 'which started in position', position);
+              });
+    }
+  }).pipe(res)
+    .on('end', function() {
+      console.log('Done!');
+    });
+});
+
+app.get('/rendering', function(req, res) {
+  position = 1;
+  dust.render('hello', {
+    'wait': function(chunk, context, bodies, params) {
+      var delayMilliseconds = parseInt(params.delay, 10) * 1000;
+      // Returning a Promise-- Dust will wait for the promise to resolve
+      return q(position++).delay(delayMilliseconds)
+              .then(function(position) {
+                console.log('Rendering', params.name, 'which started in position', position);
+              });
+    }
+  }, function(err, out) {
+    console.log('Done!');
+    res.send(out);
+  });
+});
+
+app.listen(3000, function () {
+  console.log('Using dust version', dust.version);
+  console.log('Visit http://localhost:3000');
+});

examples/streaming-incremental/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "dustjs-example-streaming-incremental",
+  "version": "1.0.0",
+  "description": "Explicitly show how Dust streams a page incrementally",
+  "main": "app.js",
+  "dependencies": {
+    "dustjs-linkedin": "^2.6.1",
+    "express": "^4.12.3",
+    "q": "^1.2.0"
+  },
+  "scripts": {
+    "start": "node app.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

examples/streaming-incremental/views/hello.dust

@@ -0,0 +1,25 @@
+{#wait name="one" delay=1}
+  <p>Hello world! I'm delayed one second.
+{/wait}
+
+{#wait name="two" delay=2}
+  <p>When Dust streams a template with many async blocks, it flushes them to the browser in-order, as fast as it can.</p>
+{/wait}
+
+{#wait name="three" delay=5}
+  <p>This block has a longer delay (5 seconds), so the blocks that finish below it will all be flushed as soon as it's ready.</p>
+{/wait}
+
+<p>
+  {#wait name="fourA" delay=1}1{/wait}
+  {#wait name="fourB" delay=1}2{/wait}
+  {#wait name="fourC" delay=1}3{/wait}
+</p>
+
+{#wait name="five" delay=10}
+  <p>This one takes a long time to render, but it's at the bottom of the page so you get the rest of the page first.</p>
+{/wait}
+
+{#wait name="six" delay=0}
+  <p>This block had no delay, but it couldn't be sent to the browser until everything above it completed.</p>
+{/wait}

examples/streaming-incremental/views/index.dust

@@ -0,0 +1 @@
+<a href="/streaming">Streaming</a> vs <a href="/rendering">Rendering</a> the same template

examples/streaming/app.js

@@ -6,6 +6,7 @@ var fs = require('fs'),
 
 dust.config.whitespace = true;
 
+// Define a custom `onLoad` function to tell Dust how to load templates
 dust.onLoad = function(tmpl, cb) {
   fs.readFile(path.join('./views', path.resolve('/', tmpl + '.dust')),
               { encoding: 'utf8' }, cb);