Listening for Load and Unload

  • Revision slug: Mozilla/Add-ons/SDK/Tutorials/Listening_for_load_and_unload
  • Revision title: Listening for Load and Unload
  • Revision id: 510007
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

To follow this tutorial you'll need to have installed the SDK and learned the basics of cfx.

exports.main()

Your add-on's main.js code is executed as soon as it is loaded. It is loaded when it is installed, when it is enabled, or when Firefox starts.

If your add-on exports a function called main(), that function will be called immediately after the overall main.js is evaluated, and after all top-level require() statements have run (so generally after all dependent modules have been loaded).

exports.main = function (options, callbacks) {};

options is an object describing the parameters with which your add-on was loaded.

options.loadReason

options.loadReason is one of the following strings describing the reason your add-on was loaded:

install
enable
startup
upgrade
downgrade

options.staticArgs

You can use the cfx --static-args option to pass arbitrary data to your program.

The value of --static-args must be a JSON string. The object encoded by the JSON becomes the staticArgs member of the options object passed as the first argument to your program's main function. The default value of --static-args is "{}" (an empty object), so you don't have to worry about checking whether staticArgs exists in options.

For example, if your main.js looks like this:

exports.main = function (options, callbacks) {
  console.log(options.staticArgs.foo);
};

And you run cfx like this:

  cfx run --static-args="{ \"foo\": \"Hello from the command line\" }"

Then your console should contain this:

info: Hello from the command line

The --static-args option is recognized by cfx run and cfx xpi. When used with cfx xpi, the JSON is packaged with the XPI's harness options and will therefore be used whenever the program in the XPI is run.`

exports.onUnload()

If your add-on exports a function called onUnload(), that function will be called when the add-on is unloaded.

exports.onUnload = function (reason) {};

reason is one of the following strings describing the reason your add-on was unloaded:

But note that due to bug 627432, your onUnload listener will never be called with uninstall: it will only be called with disable. See in particular comment 12 on that bug.

uninstall
disable
shutdown
upgrade
downgrade

You don't have to use exports.main() or exports.onUnload(). You can just place your add-on's code at the top level instead of wrapping it in a function assigned to exports.main(). It will be loaded in the same circumstances, but you won't get access to the options or callbacks arguments.

Revision Source

<div class="note">
 <p><span>To follow this tutorial you'll need to have <a href="/en-US/Add-ons/SDK/Tutorials/Installation">installed the SDK</a> and learned the <a href="/en-US/Add-ons/SDK/Tutorials/Getting_Started_With_cfx">basics of <code>cfx</code></a>. </span></p>
</div>
<h2 id="exports.main()">exports.main()</h2>
<p>Your add-on's <code>main.js</code> code is executed as soon as it is loaded. It is loaded when it is installed, when it is enabled, or when Firefox starts.</p>
<p>If your add-on exports a function called <code>main()</code>, that function will be called immediately after the overall <code>main.js</code> is evaluated, and after all top-level <code>require()</code> statements have run (so generally after all dependent modules have been loaded).</p>
<div>
 <div>
  <pre>
<span class="brush: js">exports.main = function (options, callbacks) {};</span></pre>
 </div>
</div>
<p><code>options</code> is an object describing the parameters with which your add-on was loaded.</p>
<h3 id="options.loadReason">options.loadReason</h3>
<p><code>options.loadReason</code> is one of the following strings describing the reason your add-on was loaded:</p>
<pre>
install
enable
startup
upgrade
downgrade
</pre>
<h3 id="options.staticArgs">options.staticArgs</h3>
<p>You can use the <a><code>cfx</code></a> <code>--static-args</code> option to pass arbitrary data to your program.</p>
<p>The value of <code>--static-args</code> must be a JSON string. The object encoded by the JSON becomes the <code>staticArgs</code> member of the <code>options</code> object passed as the first argument to your program's <code>main</code> function. The default value of <code>--static-args</code> is <code>"{}"</code> (an empty object), so you don't have to worry about checking whether <code>staticArgs</code> exists in <code>options</code>.</p>
<p>For example, if your <code>main.js</code> looks like this:</p>
<div>
 <div>
  <pre>
<span class="brush: js">exports.main = function (options, callbacks) {
  console.log(options.staticArgs.foo);
};</span></pre>
 </div>
</div>
<p>And you run cfx like this:</p>
<pre>
  cfx run --static-args="{ \"foo\": \"Hello from the command line\" }"
</pre>
<p>Then your console should contain this:</p>
<pre>
info: Hello from the command line
</pre>
<p>The <code>--static-args</code> option is recognized by <code>cfx run</code> and <code>cfx xpi</code>. When used with <code>cfx xpi</code>, the JSON is packaged with the XPI's harness options and will therefore be used whenever the program in the XPI is run.`</p>
<h2 id="exports.onUnload()">exports.onUnload()</h2>
<p>If your add-on exports a function called <code>onUnload()</code>, that function will be called when the add-on is unloaded.</p>
<div>
 <div>
  <pre>
<span class="brush: js">exports.onUnload = function (reason) {};</span></pre>
 </div>
</div>
<p><code>reason</code> is one of the following strings describing the reason your add-on was unloaded:</p>
<p><span>But note that due to <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=627432">bug 627432</a>, your <code>onUnload</code> listener will never be called with <code>uninstall</code>: it will only be called with <code>disable</code>. See in particular <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=627432#c12">comment 12 on that bug</a>.</span></p>
<pre>
uninstall
disable
shutdown
upgrade
downgrade
</pre>
<p>You don't have to use <code>exports.main()</code> or <code>exports.onUnload()</code>. You can just place your add-on's code at the top level instead of wrapping it in a function assigned to <code>exports.main()</code>. It will be loaded in the same circumstances, but you won't get access to the <code>options</code> or <code>callbacks</code> arguments.</p>
Revert to this revision