Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Revision 545517 of indexed-db

  • Revision slug: Mozilla/Add-ons/SDK/High-Level_APIs/indexed-db
  • Revision title: indexed-db
  • Revision id: 545517
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment
Tags: 

Revision Content

Experimental

Exposes the IndexedDB API to add-ons.

Usage

Scripts running in web pages can access IndexedDB via the window object. For example:

window.indexedDB = window.indexedDB || window.webkitIndexedDB || window.mozIndexedDB || window.msIndexedDB;

var request = window.indexedDB.open("MyDatabase");
request.onerror = function(event) {
  console.log("failure");
};
request.onsuccess = function(event) {
  console.log("success");
};

Because your main add-on code can't access the DOM, you can't do this. So you can use the indexed-db module to access the same API:

var { indexedDB } = require('indexed-db');

var request = indexedDB.open('MyDatabase');
request.onerror = function(event) {
  console.log("failure");
};
request.onsuccess = function(event) {
  console.log("success");
};

Most of the objects that implement the IndexedDB API, such as IDBTransaction, IDBOpenDBRequest, and IDBObjectStore, are accessible through the indexedDB object itself.

The API exposed by indexed-db is almost identical to the DOM IndexedDB API, so we haven't repeated its documentation here, but refer you to the IndexedDB API documentation for all the details.

The database created will be unique and private per add-on, and is not linked to any website database. The module cannot be used to interact with a given website database. See bug 778197 and bug 786688.

Example

Here's a complete add-on that adds two buttons to the browser: the button labeled "Add" adds the title of the current tab to a database, while the button labeled "List" lists all the titles in the database.

The add-on implements helper functions open(), addItem() and getItems() to open the database, add a new item to the database, and get all items in the database.

var { indexedDB, IDBKeyRange } = require('sdk/indexed-db');

var database = {};

database.onerror = function(e) {
  console.error(e.value)
}

function open(version) {
  var request = indexedDB.open("stuff", version);

  request.onupgradeneeded = function(e) {
    var db = e.target.result;
    e.target.transaction.onerror = database.onerror;

    if(db.objectStoreNames.contains("items")) {
      db.deleteObjectStore("items");
    }

    var store = db.createObjectStore("items",
      {keyPath: "time"});
  };

  request.onsuccess = function(e) {
    database.db = e.target.result;
  };

  request.onerror = database.onerror;
};

function addItem(name) {
  var db = database.db;
  var trans = db.transaction(["items"], "readwrite");
  var store = trans.objectStore("items");
  var time = new Date().getTime();
  var request = store.put({
    "name": name,
    "time": time
  });

  request.onerror = database.onerror;
};

function getItems(callback) {
  var cb = callback;
  var db = database.db;
  var trans = db.transaction(["items"], "readwrite");
  var store = trans.objectStore("items");
  var items = new Array();

  trans.oncomplete = function() {
    cb(items);
  }

  var keyRange = IDBKeyRange.lowerBound(0);
  var cursorRequest = store.openCursor(keyRange);

  cursorRequest.onsuccess = function(e) {
    var result = e.target.result;
    if(!!result == false)
      return;

    items.push(result.value.name);
    result.continue();
  };

  cursorRequest.onerror = database.onerror;
};

function listItems(itemList) {
  console.log(itemList);
}

open("1");

var add = require("sdk/ui/button/action").ActionButton({
  id: "add",
  label: "Add",
  icon: "./add.png",
  onClick: function() {
    addItem(require("sdk/tabs").activeTab.title);
  }
});

var list = require("sdk/ui/button/action").ActionButton({
  id: "list",
  label: "List",
  icon: "./list.png",
  onClick: function() {
    getItems(listItems);
  }
});

Note that the run this add-on you'll need to provide icons names "add.png" and "list.png" in the add-on's "data" directory.

Globals

Properties

indexedDB

Enables you to create, open, and delete databases. See the IDBFactory documentation.

IDBKeyRange

Defines a range of keys. See the IDBKeyRange documentation.

DOMException

Provides more detailed information about an exception. See the DOMException documentation.

Revision Source

<div class="note">
 <p>Experimental</p>
</div>
<p><span class="seoSummary">Exposes the <a href="https://developer.mozilla.org/en-US/docs/IndexedDB">IndexedDB API</a> to add-ons.</span></p>
<h2 id="Usage">Usage</h2>
<p>Scripts running in web pages can access IndexedDB via the <code>window</code> object. For example:</p>
<pre class="brush: js">
window.indexedDB = window.indexedDB || window.webkitIndexedDB || window.mozIndexedDB || window.msIndexedDB;

var request = window.indexedDB.open("MyDatabase");
request.onerror = function(event) {
  console.log("failure");
};
request.onsuccess = function(event) {
  console.log("success");
};</pre>
<p>Because your main add-on code can't access the DOM, you can't do this. So you can use the <code>indexed-db</code> module to access the same API:</p>
<pre class="brush: js">
var { indexedDB } = require('indexed-db');

var request = indexedDB.open('MyDatabase');
request.onerror = function(event) {
  console.log("failure");
};
request.onsuccess = function(event) {
  console.log("success");
};</pre>
<p>Most of the objects that implement the IndexedDB API, such as <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBTransaction">IDBTransaction</a>, <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBOpenDBRequest">IDBOpenDBRequest</a>, and <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBObjectStore">IDBObjectStore</a>, are accessible through the indexedDB object itself.</p>
<p>The API exposed by <code>indexed-db</code> is almost identical to the DOM IndexedDB API, so we haven't repeated its documentation here, but refer you to the <a href="https://developer.mozilla.org/en-US/docs/IndexedDB">IndexedDB API documentation</a> for all the details.</p>
<p>The database created will be unique and private per add-on, and is not linked to any website database. The module cannot be used to interact with a given website database. See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=779197">bug 778197</a> and <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=786688">bug 786688</a>.</p>
<h3 id="Example">Example</h3>
<p>Here's a complete add-on that adds two buttons to the browser: the button labeled "Add" adds the title of the current tab to a database, while the button labeled "List" lists all the titles in the database.</p>
<p>The add-on implements helper functions <code>open()</code>, <code>addItem()</code> and <code>getItems()</code> to open the database, add a new item to the database, and get all items in the database.</p>
<pre class="brush: js">
var { indexedDB, IDBKeyRange } = require('sdk/indexed-db');

var database = {};

database.onerror = function(e) {
&nbsp; console.error(e.value)
}

function open(version) {
&nbsp; var request = indexedDB.open("stuff", version);

&nbsp; request.onupgradeneeded = function(e) {
&nbsp;&nbsp;&nbsp; var db = e.target.result;
&nbsp;&nbsp;&nbsp; e.target.transaction.onerror = database.onerror;

&nbsp;&nbsp;&nbsp; if(db.objectStoreNames.contains("items")) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; db.deleteObjectStore("items");
&nbsp;&nbsp;&nbsp; }

&nbsp;&nbsp;&nbsp; var store = db.createObjectStore("items",
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {keyPath: "time"});
&nbsp; };

&nbsp; request.onsuccess = function(e) {
&nbsp;&nbsp;&nbsp; database.db = e.target.result;
&nbsp; };

&nbsp; request.onerror = database.onerror;
};

function addItem(name) {
&nbsp; var db = database.db;
&nbsp; var trans = db.transaction(["items"], "readwrite");
&nbsp; var store = trans.objectStore("items");
&nbsp; var time = new Date().getTime();
&nbsp; var request = store.put({
&nbsp;&nbsp;&nbsp; "name": name,
&nbsp;&nbsp;&nbsp; "time": time
&nbsp; });

&nbsp; request.onerror = database.onerror;
};

function getItems(callback) {
&nbsp; var cb = callback;
&nbsp; var db = database.db;
&nbsp; var trans = db.transaction(["items"], "readwrite");
&nbsp; var store = trans.objectStore("items");
&nbsp; var items = new Array();

&nbsp; trans.oncomplete = function() {
&nbsp;&nbsp;&nbsp; cb(items);
&nbsp; }

&nbsp; var keyRange = IDBKeyRange.lowerBound(0);
&nbsp; var cursorRequest = store.openCursor(keyRange);

&nbsp; cursorRequest.onsuccess = function(e) {
&nbsp;&nbsp;&nbsp; var result = e.target.result;
&nbsp;&nbsp;&nbsp; if(!!result == false)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return;

&nbsp;&nbsp;&nbsp; items.push(result.value.name);
&nbsp;&nbsp;&nbsp; result.continue();
&nbsp; };

&nbsp; cursorRequest.onerror = database.onerror;
};

function listItems(itemList) {
&nbsp; console.log(itemList);
}

open("1");

var add = require("sdk/ui/button/action").ActionButton({
&nbsp; id: "add",
&nbsp; label: "Add",
&nbsp; icon: "./add.png",
&nbsp; onClick: function() {
&nbsp;&nbsp;&nbsp; addItem(require("sdk/tabs").activeTab.title);
&nbsp; }
});

var list = require("sdk/ui/button/action").ActionButton({
&nbsp; id: "list",
&nbsp; label: "List",
&nbsp; icon: "./list.png",
&nbsp; onClick: function() {
&nbsp;&nbsp;&nbsp; getItems(listItems);
&nbsp; }
});
</pre>
<p>Note that the run this add-on you'll need to provide icons names "add.png" and "list.png" in the add-on's "data" directory.</p>
<h2 id="Globals">Globals</h2>
<h3 id="Properties">Properties</h3>
<h4 class="addon-sdk-api-name" id="indexedDB"><code>indexedDB</code></h4>
<p>Enables you to create, open, and delete databases. See the <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBFactory">IDBFactory documentation</a>.</p>
<h4 class="addon-sdk-api-name" id="IDBKeyRange"><code>IDBKeyRange</code></h4>
<p>Defines a range of keys. See the <a href="https://developer.mozilla.org/en-US/docs/IndexedDB/IDBKeyRange">IDBKeyRange documentation</a>.</p>
<h4 class="addon-sdk-api-name" id="DOMException"><code>DOMException</code></h4>
<p>Provides more detailed information about an exception. See the <a href="https://developer.mozilla.org/en-US/docs/DOM/DOMException">DOMException documentation</a>.</p>
Revert to this revision