Merge pull request YahooArchive#50 from castle-it/master

Optional parameter to await completion in bandwidth plugin before sending beacon
Conflicts:
	doc/api/BW.html

doc/api/BW.html

@@ -75,6 +75,13 @@ <h2 id="config">Configuration</h2>
 set <code>test_https</code> to <code>true</code>, boomerang will run the test instead of skipping.
 </dd>
 
+<dt>block_beacon</dt>
+<dd>
+<strong>[optional]</strong>
+By default, the bandwidth plugin will not block boomerang from sending a beacon, so the results
+will not be included in the broadcast with default settings. If you set <code>block_beacon</code> to
+<code>true</code>, boomerang will wait for the results of the test before sending the beacon.
+</dd>
 
 </dl>
 

doc/howtos/howto-3.html

@@ -28,15 +28,19 @@ <h1>Boomerang Howto #3:<br>Measure a user's bandwidth/latency along with page lo
 
 <p>
 Simply adding boomerang to a page and calling the <code>init()</code> method is sufficient to start the bandwidth
-test and beacon its results back to the server.  This is the code you'd use:
+test. If you want the beacon results to include the results of the bandwidth test, setting <code>block_beacon</code>
+to <code>true</code> will force boomerang to wait for the test to complete before sending the beacon. If you do not
+turn on the <code>block_beacon</code> feature, you will only receive bandwidth results if they were cached in a
+cookie by a previous test run.
 </p>
 <pre>
 &lt;script src="boomerang.js" type="text/javascript"&gt;&lt;/script&gt;
 &lt;script type="text/javascript"&gt;
 BOOMR.init({
 	beacon_url: "http://yoursite.com/path/to/beacon.php",
 	BW: {
-		base_url: "http://base_url/to/bandwidth/images/"
+		base_url: "http://base_url/to/bandwidth/images/",
+		block_beacon: true
 	}
 });
 &lt;/script&gt;

doc/howtos/howto-6.html

@@ -210,6 +210,23 @@ <h2>Bandwidth plugin</h2>
 value along with the <code>timeout</code> value above.
 </dd>
 
+<dt>test_https</dt>
+<dd>
+<strong>[optional]</strong>
+By default, boomerang will skip the bandwidth test over an HTTPS connection. Establishing
+an SSL connection takes time, which could skew the bandwidth results. If all your traffic
+is sent over SSL, then running the test over SSL probably gets you what you want. If you
+set <code>test_https</code> to <code>true</code>, boomerang will run the test instead of skipping.
+</dd>
+
+<dt>block_beacon</dt>
+<dd>
+<strong>[optional]</strong>
+By default, the bandwidth plugin will not block boomerang from sending a beacon, so the results
+will not be included in the broadcast with default settings. If you set <code>block_beacon</code> to
+<code>true</code>, boomerang will wait for the results of the test before sending the beacon.
+</dd>
+
 </dl>
 
 <h2>All optional</h2>

plugins/bw.js

@@ -50,6 +50,7 @@ impl = {
 	nruns: 5,
 	latency_runs: 10,
 	user_ip: "",
+	block_beacon: false,
 	test_https: false,
 	cookie_exp: 7*86400,
 	cookie: "BA",
@@ -406,7 +407,10 @@ impl = {
 		}
 
 		this.complete = true;
-		//BOOMR.sendBeacon();
+
+		if (this.block_beacon === true)
+			BOOMR.sendBeacon();
+
 		this.running = false;
 	},
 
@@ -475,7 +479,7 @@ BOOMR.plugins.BW = {
 		}
 
 		BOOMR.utils.pluginConfig(impl, config, "BW",
-						["base_url", "timeout", "nruns", "cookie", "cookie_exp", "test_https"]);
+						["base_url", "timeout", "nruns", "cookie", "cookie_exp", "test_https", "block_beacon"]);
 
 		if(config && config.user_ip) {
 			impl.user_ip = config.user_ip;
@@ -522,7 +526,10 @@ BOOMR.plugins.BW = {
 
 			BOOMR.info("HTTPS detected, skipping bandwidth test", "bw");
 			impl.complete = true;
-			//BOOMR.sendBeacon();
+
+			if (impl.block_beacon === true)
+				BOOMR.sendBeacon();
+
 			return this;
 		}
 
@@ -545,7 +552,15 @@ BOOMR.plugins.BW = {
 		}
 	},
 
-	is_complete: function() { return true; }
+	is_complete: function() {
+		if (impl.block_beacon === true)
+		{
+			return impl.complete;
+		}
+		else {
+			return true;
+		}
+	}
 };
 
 }());