Permalink
Browse files

add a cache reload plugin

includes documentation, and a sample boomerang reload html file
  • Loading branch information...
1 parent f689671 commit a0fd088a17cb42bf15c5d9fc78ada55c3b6821c2 @bluesmoon committed Jan 25, 2013
Showing with 189 additions and 4 deletions.
  1. +22 −0 boomerang-reload.html
  2. +110 −0 doc/api/cache_reload.html
  3. +5 −4 doc/api/index.html
  4. +52 −0 plugins/cache_reload.js
View
@@ -0,0 +1,22 @@
+<!doctype html>
+<html>
+<head>
+<script src="boomerang.js"></script>
+</head>
+<body>
+<script>
+var boom_ver = BOOMR.version.split('.'),
+ reqd_ver = [0, 9, 123456789]; // change this to required version
+if ( boom_ver[0] < reqd_ver[0] // javascript will do type coercion
+ || boom_ver[1] < reqd_ver[1]
+ || boom_ver[2] < reqd_ver[2])
+{
+ location.reload(true);
+}
+else
+{
+ location.replace("about:blank");
+}
+</script>
+</body>
+</html>
View
@@ -0,0 +1,110 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+<title>Cache Reload plugin API</title>
+<meta http-equiv="Content-type" content="text/html; charset=utf-8">
+<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
+</head>
+<body>
+<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
+<h1>Cache Reload plugin API</h1>
+<p>
+The cache reload plugin forces the browser to update its cached copy of boomerang. Details are on the lognormal
+blog <a href="http://www.lognormal.com/blog/2012/06/05/updating-cached-boomerang/" title="Updating Cached Boomerang">here</a>
+and <a href="http://www.lognormal.com/blog/2012/06/17/more-on-updating-boomerang/" title="More on updating cached boomerang">here</a>.
+</p>
+
+<h2 id="config">Configuration</h2>
+<p>
+The Cache Reload plugin's configuration is under the <code>CACHE_RELOAD</code> namespace.
+The full configuration object is described in <a href="../howtos/howto-6.html">Howto #6 &mdash; Configuring boomerang</a>.
+</p>
+<dl>
+<dt>url</dt>
+<dd>
+<strong>[required]</strong>
+By default, this is set to the empty string, which has the effect of disabling the Cache Reload plugin. Set the <code>url</code>
+parameter to the url that will do handle forcing the reload. See the example below for what this url's output should look like.
+</dd>
+
+</dl>
+
+
+<h2 id="methods">Methods</h2>
+
+<dl class="api">
+
+<dt>init(oConfig)</dt>
+<dd>
+<p>
+Called by the <a href="BOOMR.html#init">BOOMR.init()</a> method to configure the cache reload plugin.
+</p>
+<h3>Parameters</h3>
+<dl>
+<dt>oConfig</dt>
+<dd>The configuration object passed in via <code>BOOMR.init()</code>. See the <a href="#config">Configuration section</a> for details.
+</dl>
+<h3>Returns</h3>
+<p>
+a reference to the <code>BOOMR.plugins.CACHE_RELOAD</code> object, so you can chain methods.
+</p>
+</dd>
+
+<dt>is_complete()</dt>
+<dd>
+<p>
+Called by <a href="BOOMR.html#sendBeacon">BOOMR.sendBeacon()</a> to determine if the bandwidth plugin has
+finished what it's doing or not. This method always returns true.
+</p>
+<h3>Returns</h3>
+<ul>
+<li><code>true</code>.</li>
+</ul>
+</dd>
+
+</dl>
+
+<h2 id="beacon">Beacon Parameters</h2>
+<p>
+This plugin does not add any parameters to the beacon.
+</p>
+
+<h2 id="example">Example HTML document</h2>
+<p>
+The cache reloading HTML document should look something like this:
+</p>
+<pre>
+&lt;!doctype html&gt;
+&lt;html&gt;
+&lt;head&gt;
+&lt;script src="boomerang.js"&gt;&lt;/script&gt;
+&lt;/head&gt;
+&lt;body&gt;
+&lt;script&gt;
+var boom_ver = BOOMR.version.split('.'),
+ reqd_ver = [0, 9, 123456789]; // change this to required version
+if ( boom_ver[0] &lt; reqd_ver[0] // javascript will do type coercion
+ || boom_ver[1] &lt; reqd_ver[1]
+ || boom_ver[2] &lt; reqd_ver[2])
+{
+ location.reload(true);
+}
+else
+{
+ location.replace("about:blank");
+}
+&lt;/script&gt;
+&lt;/body&gt;
+&lt;/html&gt;
+</pre>
+
+<p class="perma-link">
+The latest code and docs is available on <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a>
+</p>
+
+</body>
+</html>
+<!--
+ Copyright (c) 2013, SOASTA, Inc. All rights reserved.
+ Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.
+-->
View
@@ -14,20 +14,21 @@ <h2>core</h2>
<li><a href="BOOMR.utils.html">BOOMR.utils</a> &mdash; Utility functions within the BOOMR object.</li>
</ul>
-<h2>core plugins</h2>
+<h2>plugins</h2>
<ul>
<li><a href="RT.html">BOOMR.plugins.RT</a> &mdash; The roundtrip plugin that measures page load time.</li>
+
<li><a href="BW.html">BOOMR.plugins.BW</a> &mdash; The bandwidth plugin that measures connection bandwidth and latency.</li>
-</ul>
-<h2>extra plugins</h2>
-<ul>
<li><a href="DNS.html">BOOMR.plugins.DNS</a> &mdash; The DNS latency plugin that measures latency of the user's DNS.</li>
<li><a href="ipv6.html">BOOMR.plugins.IPv6</a> &mdash; The IPv6 latency plugin that measures various IPv6 related metrics.</li>
<li><a href="navtiming.html">BOOMR.plugins.NavigationTiming</a> &mdash; A plugin that collects performance data from user
agents that implement the W3C Navigation Timing specification.</li>
+
+<li><a href="cache_reload.html">BOOMR.plugins.CACHE_RELOAD</a> &mdash; The Cache Reload plugin that forces a browser to update
+its cached version of boomerang.</li>
</ul>
<p class="perma-link">
View
@@ -0,0 +1,52 @@
+/**
+ * \file cache_reload.js
+ * Plugin that forces a cache reload of boomerang (assuming you have server side support)
+ * Copyright (c) 2013, SOASTA, Inc. All rights reserved.
+ */
+
+
+(function() {
+
+BOOMR = BOOMR || {};
+BOOMR.plugins = BOOMR.plugins || {};
+
+var impl = {
+ url: "",
+ initialized: false
+};
+
+BOOMR.plugins.CACHE_RELOAD = {
+ init: function(config) {
+ BOOMR.utils.pluginConfig(impl, config, "CACHE_RELOAD", ["url"]);
+
+ if(this.initalized)
+ return this;
+
+ BOOMR.subscribe(
+ "page_ready",
+ function() {
+ if(!impl.url)
+ return;
+ // we use document and not BOOMR.window.document since
+ // we can run inside the boomerang iframe if any
+ var i=document.createElement('iframe');
+ i.style.display="none";
+ i.src=impl.url;
+ document.body.appendChild(i);
+ },
+ null,
+ null
+ );
+ this.initialized = true;
+
+ return this;
+ },
+
+ is_complete: function() {
+ // we always return true since this plugin never adds anything to the beacon
+ return true;
+ }
+};
+
+}());
+

0 comments on commit a0fd088

Please sign in to comment.