doc/api/BOOMR.html

<!DOCTYPE HTML>
<html>
<head>
<title>The BOOMR 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>The BOOMR object</h1>
<p>
Everything in boomerang is accessed through the <code>BOOMR</code> object.  Each plugin has its
own API, but is reachable through <code>BOOMR.plugins</code>.  This document describes the main
<code>BOOMR</code> object.
</p>

<p>
To access any of the following, dereference the BOOMR object.  eg: use <code>BOOMR.version</code> 
to get the <code>version</code> string.
</p>

<h2 id="properties">Properties</h2>

<dl class="api">

<dt>version</dt>
<dd>
<p>
The version number of the boomerang library.  This is a string, formatted as major.minor.patchlevel.
Standard version numbering rules apply
</p>
</dd>

<dt>plugins</dt>
<dd>
<p>
An object containing all plugins that have been added to boomerang.  If you build your own plugin,
it should be added to this object:
</p>
<pre>
BOOMR.plugins.MyPlugin = {
	...
};</pre>
</dd>

</dl>

<h2 id="config">Configuration</h2>
<p>
Configuring boomerang is described in <a href="../howtos/howto-6.html">Howto #6 &mdash; Configuring boomerang</a>.
Parameters relevant to the <code>BOOMR</code> object are:
</p>
<dl>
<dt>beacon_url</dt>
<dd>
<strong>[highly recommended]</strong>
The URL to beacon results back to.  All parameters will be added to this URL's
query string.  This URL should not already have a query string component.
There is no default value for this parameter.  If not set, no beacon will be sent.
</dd>

<dt>site_domain</dt>
<dd>
<strong>[recommended]</strong>
The domain that all cookies should be set on.  Boomerang will try to auto-detect this,
but unless your site is of the <code>foo.com</code> format, it will probably get it
wrong.  It's a good idea to set this to whatever part of your domain you'd like to
share bandwidth and performance measurements across.<br>
If you have multiple domains, then you're out of luck.  You'll just have to get 
separate measurements across them.
</dd>

<dt>user_ip</dt>
<dd>
<strong>[recommended]</strong>
Despite its name, this is really a free-form string used to uniquely identify the user's
current internet connection.  It's used primarily by the bandwidth test to determine
whether it should re-measure the user's bandwidth or just use the value stored in the
cookie.  You may use IPv4, IPv6 or anything else that you think can be used to identify
the user's network connection.
</dd>

<dt>log</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang will attempt to use the logger component from YUI if it finds it
or firebug if it finds that instead.  If it finds neither, it will default to not
logging anything.  You can define your own logger by setting the <code>log</code>
parameter to a function that logs messages.<br>
The signature of this function is:
<pre>
function log(oMessage, sLevel, sSource);
</pre>
Where:<dl>
<dt>oMessage</dt> <dd>is the object/message to be logged.  It is up to you to decide how to log objects.<dd>
<dt>sLevel</dt> <dd>is the log level, with values of "error", "warn", "info" and "debug"</dd>
<dt>sSource</dt> <dd>is the source of the log message.  This will typically be the string "boomerang" followed by the name of a plugin</dd>
</dl>
Note that you can completely disable logging by setting <code>log</code> to <code>null</code>.
</dd>

<dt>autorun</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang runs automatically and attaches its <code>page_ready</code> handler to
the <code>window.onload</code> event.  If you set <code>autorun</code> to <code>false</code>,
this will not happen and you will need to call <code>BOOMR.page_ready()</code> yourself.
</dd>

<dt>&lt;plugin_name&gt;<dt>
<dd>
Each plugin is configured through a sub-object of the config object.  The key is the name
of the plugin.  Each plugin's documentation will have details on its configuration object.
</dd>

</dl>

<h2 id="methods">Methods</h2>

<dl class="api">

<dt>init(oConfig)</dt>
<dd>
<p>
The init method that you to call to initialise boomerang.  Call this method once after you've
loaded the boomerang javascript.  It accepts a single configuration object as a parameter.  See
the <a href="#config">Configuration section</a> for details.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>page_ready()</dt>
<dd>
<p>
Method that fires the <code>page_ready</code> event.  Call this only if you've set <code>autorun</code> to
false when calling the <code>init()</code> method.  You should call this method when you determine that
your page is ready to be used by your user.  This will be the end-time used in the page load time measurement.
</p>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-1b-page%231.html">Howto #1b</a> for an example of how to use this method.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>subscribe(sEvent, fCallbackFn, oCallbackData, oCallbackScope)</dt>
<dd>
<p>
The subscribe method is used to subscribe an event handler to one of boomerang's <a href="#events">events</a>.
It accepts four parameters:
</p>
<h3>Parameters:</h3>
  <dl>
  <dt>sEvent</dt>
  <dd>The event name.  This may be one of <em>page_ready</em>, <em>page_unload</em>, <em>before_beacon</em></dd>

  <dt>fCallbackFn</dt>
  <dd>A reference to the callback function that will be called when this event fires.  The function's signature should be:
  <pre>function(oEventData, oCallbackData);</pre>
  </dd>

  <dt>oCallbackData</dt>
  <dd><strong>[optional]</strong> object passed as the second parameter to the callback function</dd>

  <dt>oCallbackScope</dt>
  <dd><strong>[optional]</strong> If set to an object, then the callback function is called as a method of this object, and all references to <code>this</code>
  within the callback function will refer to oCallbackScope</dd>
  </dl>
<p>
The <code>page_ready</code> and <code>page_unload</code> events are most useful to plugins while the
<code>before_beacon</code> event is useful to code that wants to do something with the beacon parameters
before the beacon is fired.  See the <a href="#events">events</a> section for more details.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>addVar(sName, sValue) OR addVar(oVars)</dt>
<dd>
<p>
Add one or more parameters to the beacon.  This method is used by plugins to add parameters to the beacon,
but may also be used by the page developer to tag the current request.
</p>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-5.html">Howto #5</a> for an example of using <code>addVar()</code>.
</p>
<p>
This method may either be called with a single object containing key/value pairs, or with two parameters,
the first is the variable name and the second is its value.  All names should be strings usable in a URL's
query string.  We recommend only using alphanumeric characters and underscores, but you can use anything you
like.  Values should be strings (or numbers), and have the same restrictions as names.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>removeVar(sName, ...)</dt>
<dd>
<p>
Removes one or more variables from the beacon URL.  This is useful within a plugin to reset the values of
parameters that it is about to set.  It can also be used in a <code>before_beacon</code> handler to stop
the beacon from being sent.  See <a href="../howtos/howto-5.html">Howto #5</a> for how to do this.
</p>
<p>
This method accepts either a list of variable names, or a single array containing a list of variable names.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>sendBeacon()</dt>
<dd>
<p>
Request boomerang to send its beacon.  Boomerang may ignore this request.  When this method is called,
boomerang checks all plugins.  If any plugin has not completed its checks (ie, the plugin's <code>is_complete()</code>
method returns false, then this method does nothing.  If all plugins have completed, then this method fires the
<code>before_beacon</code> event with all variables that will be sent on the beacon.
</p>
<p>
After all <code>before_beacon</code> handlers return, this method checks if a <code>beacon_url</code> has been
configured and if there are any beacon parameters to be sent.  If both are true, it fires the beacon.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>log(sMessage, sLevel, sSource)</dt>
<dd>
<p>
Log a <code>sMessage</code> to the configured logger with a level of <code>sLevel</code>.  This method
simply passes all logging information on to the configured logger.  See
<a href="../howtos/howto-6.html">Howto #6</a> for details on how to configure this.
</p>
<p>
You probably want to use one of the convenience methods below instead that set the log level correctly.
</p>
<h3>Returns</h3>
<p>
nothing
</p>
</dd>

<dt>debug(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>debug</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>info(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>info</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>warn(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>warn</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

<dt>error(sMessage, sSource)</dt>
<dd>
<p>
Log <code>sMessage</code> to the configured logger with a level of <code>error</code>.  If <code>sSource</code> is set,
it is appended to the string "boomerang." and set as the source of the log message.  Use this
parameter to mention a plugin name and/or a line number/function name.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR</code> object, so you can chain methods.
</p>
</dd>

</dl>

<h2 id="events">Events</h2>

<dl class="api">
<dt>page_ready</dt>
<dd>
<p>
Fired when the page is usable by the user.  By default this is fired when <code>window.onload</code> fires,
but if you set <code>autorun</code> to <code>false</code> when calling <code>BOOMR.init()</code>, then
you must explicitly fire this event by calling <code>BOOMR.page_ready()</code>.
</p>
<h3>Callback</h3>
<p>
No additional event data is passed to the callback function.  Any callback data is passed as specified in
the <code>subscribe()</code> method.
</p>
</dd>

<dt>page_unload</dt>
<dd>
<p>
Fired just before the browser unloads the page.  This is fired when <code>window.onbeforeunload</code> fires
(<code>onunload</code> on Opera).
</p>
<h3>Callback</h3>
<p>
No additional event data is passed to the callback function.  Any callback data is passed as specified in
the <code>subscribe()</code> method.
</p>
</dd>

<dt>before_beacon</dt>
<dd>
<p>
Fired just before the beacon is sent to the server.  You can stop the beacon from firing by calling
<code>BOOMR.removeVar()</code> for all beacon parameters.
</p>
<h3>Callback</h3>
<p>
The callback function is called with two parameters.  The first parameter is an object containing all
parameters that will be added to the beacon.  The second parameter is the callback data object that
was passed in to the <code>subscribe()</code> method.  If the callback function removes all parameters
from boomerang, the beacon will not fire.
</p>
</dd>

</dl>

<h2 id="beacon">Beacon Parameters</h2>
<p>
On its own, with no plugins set up, boomerang will send the following parameters across through the beacon:
</p>
<dl>
<dt>v</dt>
<dd>The version number of the boomerang library in use.</dd>
<dt>u</dt>
<dd>The URL of the page that sends the beacon.</dd>
</dl>

<p>
Each plugin may add its own parameters, and these are specified in each plugin's API docs.
</p>

<p class="perma-link">
The latest code and docs is available on <a href="http://github.com/yahoo/boomerang/">github.com/yahoo/boomerang</a>
</p>

</body>
</html>