Utiliser IndexedDB

IndexedDB est un moyen de stocker des données de manière persistante dans un navigateur. Cela vous laisse créer des applications web avec de riches possibilités de requêtes indépendamment de la disponibilité du réseau puisque vos applications peuvent fonctionner en ligne, ou hors-ligne. 

À propos de ce document

Ce tutoriel vous guide à travers l'utilisation de l'API asynchrone de IndexedDB. Si vous n'êtes pas familier avec le principe de IndexedDB, vous devriez d'abord lire les concepts basiques d'IndexedDB.

Pour la documentation de référence sur l'API d'IndexedDB, regardez l'article IndexedDB et ses sous-parties, qui détaille les types d'objets utilisés par IndexedDB, ainsi que les méthodes sur les API synchrones et asynchrones. 

Modèle de base

Le modèle de base qu'IndexedDB utilise est le suivant :

  1. Ouvrir une base de données.
  2. Créer un objet de stockage dans la base de données. 
  3. Démarrer une transaction, et faire des requêtes pour faire quelques opérations sur des bases de données, comme ajouter, ou récupérer des données.
  4. Attendre que l'éxécution soit terminée, en écoutant le bon type d'événement DOM.
  5. Faire quelque chose avec les résultats (qui peuvent être trouvés dans l'objet de la requête).

Maintenant que nous avons ces gros concepts attachés à nos ceintures, nous pouvons voir des choses plus concrètes.

Créer et structurer l'objet

Utiliser une version expérimentale d'IndexedDB

Au cas où vous souhaiteriez tester votre code dans des navigateurs qui utilisent toujours un préfixe, vous pouvez utiliser le code suivant :  

// Sur la ligne suivante, vous devez inclure les préfixes des implémentations que vous souhaitez tester.
window.indexedDB = window.indexedDB || window.mozIndexedDB || window.webkitIndexedDB || window.msIndexedDB;
// N'UTILISEZ PAS "var indexedDB = ..." si vous n'êtes pas dans une fonction.
// De plus, vous pourriez avoir besoin de réferences à des objets window.IDB*:
window.IDBTransaction = window.IDBTransaction || window.webkitIDBTransaction || window.msIDBTransaction;
window.IDBKeyRange = window.IDBKeyRange || window.webkitIDBKeyRange || window.msIDBKeyRange
// (Mozilla has never prefixed these objects, so we don't need window.mozIDB*)

Faites attention aux implémentations qui utilisent un préfixe ; elles peuvent être boguées, incomplètes, voire suivre une ancienne version de la spécification. Il n'est donc pas recommandé d'utiliser en production. Il serait préférable de ne pas supporter ces navigateurs :

if (!window.indexedDB) {
    window.alert("Votre navigateur ne supporte pas une version stable d'IndexedDB. Quelques fonctionnalités ne seront pas disponibles.")
}

Ouvrir une base de données

On commence l'ensemble du processus comme ceci :

// Ouvrons notre première base
var request = window.indexedDB.open("MyTestDatabase", 3);

Vous avez vu ? Ouvrir une base de données est comme n'importe quelle autre opération — vous avez juste à le "demander".

L'objet IndexedDB a juste une seule méthode, open(), qui, lorsqu'elle est appelée, ouvre une base de données nommée  "MyTestDatabase." Toutes les bases de données IndexedDB sont stockées à une même origine, ce qui veut dire que mozilla.com pourrait avoir une base nommée "binky" et mozilla.org pourrait avoir une base totalement différente nommée "binky". Si la base de données n'existe pas, elle est créée ; Si la base existe, elle est simplement ouverte.

La méthode open n'ouvre pas la base de données ou démarre une transaction aussitôt ; L'appel à la fonction  open() retourne un objet IDBOpenDBRequest avec un résultat  (success) ou une valeur d'erreur qui permet de la gérer comme un évènement. La plupart des autres fonctions asynchrones dans IndexedDB fonctionnent de la même façon - retourne un objet IDBRequest avec le résultat ou une erreur. Le résultat de la fonction open est une instance de IDBDatabase.

Le second paramètre de la méthode open est la version de la base. La version de la base détermine le schéma de celle-ci — Les objets stockés dans la base de données, et leur structure. Si la base de données n'existe pas, elle est créée par l'opération open, puis, un événement  onupgradeneeded est déclenché et vous créez le schéma de la base dans les instructions de cet événement. Si la base de données existe pas, mais que vous spécifiez un numéro de version plus élevé, un événement onupgradeneeded est déclenché  immédiatement, vous permettant de mettre à jour le schéma dans ses instructions (créer ou supprimer des objets de stockage, si celui-ci n'est pas à jour) - plus d'infos sur ceci dans  Updating the version of the database, plus bas.

Important: Le numéro de version est un entier naturel (max 32bits), ce qui veut dire qu'il ne peut être un très gros entier. Cela veut également dire que vous ne pouvez pas utiliser de réél, sinon, il sera converti au nombre entier le plus proche (inférieur) et la transaction peut ne pas démarrer, ou déclencher l'événement  onupgradeneeded. Par exemple, n'utilisez pas 2.4 comme un numéro de version :
var request = indexedDB.open("MyTestDatabase", 2.4); // Ne faites pas ça, même si la version sera arrondie à 2

Générer des instructions

La première chose que vous ferez avec la plupart des requêtes que vous générerez sera d'ajouter des instructions de succès ou d'erreurs :

request.onerror = function(event) {
  // Faire quelque chose avec request.errorCode !
};
request.onsuccess = function(event) {
  // Faire quelque chose avec request.result !
};

Laquelle de ces deux fonctions, onsuccess() or onerror(), sera appelée ? Si tout se passe bien, un évènement success (qui est, un évènement DOM à qui la propriété type property est déterminée à "success") est lancé avec request comme sa cible. Une fois lancé, la fonction onsuccess() de request est déclenchée avec l'évènement success comme argument. Sinon, s'il y avait un quelconque problème, un évènement erreur (qui est, un évènement DOM à qui la propriété type est définie à "error") est lancée à request. Cela déclenche la fonction onerror() avec l'évènement d'erreur comme argument.

L'API IndexedDB est conçue pour minimiser le besoin de la gestion des erreurs, donc vous ne serez pas amenés à voir beaucoup d'évènements erreurs (du moins, pas avant que vous utilisiez l'API!). Cependant, dans le cas d'une ouverture de base de données, il y a quelques conditions qui génèrent des évènements d'erreurs. Le problème le plus courant est que l'utilisateur a décidé d'interdire l'accès à la création de base de données. Un des principaux objectifs d'IndexedDB est de permettre un important stockage de données pour l'utilisation hors-ligne. (Pour en savoir plus sur la capacité de stockage de chaque navigateur, voyez Storage limits).

Évidemment, les navigateurs ne peuvent permettre à ce qu'une publicité en ligne ou un site malicieux pollue votre ordinateur, donc ils informent l'utilisateur la première fois qu'une application web tente d'ouvrir un espace de stockage IndexedDB. L'utilisateur peut choisir de permettre ou refuser l'accès. Aussi, IndexedDB est complètement désactivé en mode privé dans les navigateurs (Navigation privée pour Firefox et mode Incognito pour Chrome). L'intérêt principal de la navigation privée est de ne laisser aucune empreinte, donc essayer d'ouvrir une base de données dans ce mode, échouera.

Maintenant, admettons qu'un utilisateur ait accepté la création d'une base, et que vous receviez un évènement success pour déclencher une fonction de rappel ; On fait quoi après ? Le code suivant génère un appel à indexedDB.open(), donc request.result est une instance de IDBDatabase, et vous voulez garder en mémoire cela pour plus tard. Votre code devrait ressembler à ceci :

var db;
var request = indexedDB.open("MyTestDatabase");
request.onerror = function(event) {
  alert("Pourquoi ne permettez-vous pas à ma web app d'utiliser IndexedDB?!");
};
request.onsuccess = function(event) {
  db = request.result;
};

Gérer les erreurs

Les évènement d'erreurs « bouillonnent » ; Ceux-ci sont rattachés à la requête qui a généré l'erreur, puis l'évènement bouillonne jusqu'à la transaction, et enfin à l'objet de la base. Si vous souhaitez éviter d'ajouter une gestion des erreurs à chaque requête, vous pouvez ajouter un seul gestionnaire d'erreur à l'objet db, comme ceci :

db.onerror = function(event) {
  // Gestion d'erreur générique pour toutes les erreurs de requêtes de cette base
  alert("Database error: " + event.target.errorCode);
};

Une des erreurs communes possible lorsqu'on ouvre une base de données, c'est VER_ERR. Celle-ci indique que la version de la base de données stockée sur le disque est supérieure à la version que vous êtes en train d'essayer d'ouvrir. C'est un cas qui doit toujours être pris en considération par le gestionnaire d'erreurs.

Créer ou mettre à jour une version de base de données

Lorsque vous créez une nouvelle base de données, ou augmentez un numéro de version d'une base existante (en spécifiant un numéro de version supérieur que vous aviez auparavant, lorsque Opening a database), l'évènement onupgradeneeded sera déclenché et un objet IDBVersionChangeEvent sera passé à la gestion d'évènements. Pour la gestion de cet évènement, vous devez créer les objets de stockage requis pour cette version de base :

// Cet évènement est seulement implémenté dans des navigateurs récents
request.onupgradeneeded = function(event) { 
  var db = event.target.result;

  // Crée un objet de stockage pour cette base de données
  var objectStore = db.createObjectStore("name", { keyPath: "myKey" });
};

Dans ce cas, la base de données disposera aussitôt des objets de stockage de la précédente version de la base, donc vous n'aurez pas à créer de nouveau ces objet de stockage. Vous aurez seulement besoin de créer de nouveaux objets de stockage, ou de supprimer des objets de stockage de la version précédente dont vous n'avez plus besoin. Si vous avez besoin de changer un objet de stockage existant  (e.g., pour changer la keyPath), alors vous devez supprimer l'ancien objet de stockage et le créer à nouveau avec les nouveaux paramètres. (Notez que ceci supprimera les informations dans l'objet de stockage ! Si vous avez besoin de sauvegarder ces informations, vous devez les lire et les sauvegarder quelque part avant de mettre à jour la base de données.)

Esasyer de créer un objet de stockage avec un nom déjà existant (ou essayer de supprimer un objet de stockage avec un nom qui n'existe pas encore) renverra une erreur. 

Si l'évènement onupgradeneeded quitte avec succès, le gestionnaire onsuccess de la requête d'ouverture de la base de données sera déclenché. 

Blink/Webkit supporte la version courante de la spec, sortie dans Chrome 23+ et Opera 17+; IE10+ supporte aussi. Les autres ou anciennes n'implémentent pas  indexedDB.open(name, version).onupgradeneeded signature désormais. Pour plus d'informations sur la mise à jour de version de base de données sur les anciens Webkit/Blink, référez vous à IDBDatabase reference article.

Structurer la base de données

Maintenant, structurons la base de données. IndexedDB utilise des objets de stockage plutôt que des tableaux, et une seule base de données peut contenir un nombre quelconque d'objets de stockage. Chaque fois qu'une valeur est stockée dans un objet de stockage, elle est associée à une clé. Il y a différentes manières pour une clé d'être définie, selon que l'objet de stockage utilise un key path ou un key generator.

Le tableau suivant montre les différentes manières d'attribution des clés.

Key Path (keyPath) Key Generator (autoIncrement) Description
No No L'objet de stockage peut contenir n'importe quel type de valeur, même des valeurs primitives comme des nombres ou des chaînes de caractères. Vous devez fournir en argument une clé chaque fois que vous souhaiter ajouter une nouvelle valeur.
Yes No L'objet de stockage peut contenir des objets JavaScript. Les objets doivent avoir une propriété qui a le même nom que le key path.
No Yes L'objet de stockage peut contenir n'importe quel type de valeur. La clé est générée pour vous automatiquement, ou vous pouvez fournir en argument une clé si vous voulez utiliser une clé spécifique.
Yes Yes L'objet de stockage peut contenir des objets JavaScript. Normalement, une clé est générée, et la valeur de la clé générée est stockée dans l'objet dans une propriété avec le même nom que le key path. Cependant, si une telle propriété existait, la valeur de cette propriété est utilisée en tant que clé, plutôt que de générer une nouvelle clé.

Vous pouvez aussi créer des index sur un objet de stockage, à condition que l'objet de stockage contienne des objets, et non des primitives. Un index vous permet de consulter les valeurs stockées dans un objet de stockage en utilisant la valeur d'une propriété de l'objet stocké, plutôt que la clé de l'objet.

En outre, les index ont la capacité d'appliquer des contraintes simples sur les données stockées. En paramétrant l'option unique lorsque l'on crée l'index, l'index s'assure que deux objets stockés n'auront pas la même valeur. Par exemple, si vous avez un objet de stockage qui contient un ensemble de personnes, et que vous voulez vous assurer que deux personnes n'auront pas la même adresse mél, vous pouvez utiliser un index avec un marqueur unique pour vous en assurer.

Cela semble confus, mais ce simple exemple devrait illustrer ces concepts. D'abord, nous définissons quelques données clients pour cet exemple :

// Voici à quoi ressemble nos données client.
const customerData = [
  { ssn: "444-44-4444", name: "Bill", age: 35, email: "bill@company.com" },
  { ssn: "555-55-5555", name: "Donna", age: 32, email: "donna@home.org" }
];

Bien sûr, vous n'utiliseriez pas le numéro de sécurité sociale comme clé primaire dans une table clients parce que tout le monde n'a pas de numéro de sécurité sociale, et vous pourriez stocker leur date de naissance au lieu de leur âge, mais laissons ces choix non pertinents pour des raisons de commodité et continuer.

Maintenant, voyons la création d'une base de données pour stocker ces données :

const dbName = "the_name";

var request = indexedDB.open(dbName, 2);

request.onerror = function(event) {
  // Gestion des erreurs.
};
request.onupgradeneeded = function(event) {
  var db = event.target.result;

  // Créer un objet de stockage qui contient les informations de nos clients. 
  // Nous allons utiliser "ssn" en tant que clé parce qu'il est garanti d'être 
  // unique - Du moins, c'est ce qu'on en disait au lancement.
  var objectStore = db.createObjectStore("customers", { keyPath: "ssn" });

  // Créer un index pour rechercher les clients par leur nom. Nous pourrions 
  // avoir des doubles, alors on n'utilise pas d'index unique.
  objectStore.createIndex("name", "name", { unique: false });

  // Créer un index pour rechercher les clients par leur adresse mél. Nous voulons nous
  // assurer que deux clients n'auront pas la même, donc, on utilise un index unique.
  objectStore.createIndex("email", "email", { unique: true });

  // Utiliser la transaction oncomplete pour être sûr que la création de l'objet de stockage
  // est terminée avant d'ajouter des données dedans.
  objectStore.transaction.oncomplete = function(event) {
    // Stocker les valeurs dans le nouvel objet de stockage.
    var customerObjectStore = db.transaction("customers", "readwrite").objectStore("customers");
    for (var i in customerData) {
      customerObjectStore.add(customerData[i]);
    }
  }
};
Comme indiqué précédemment, onupgradeneeded est le seul endroit où vous pouvez modifier la structure de la base de données. A l'intérieur, vous pouvez créer et supprimer des objets de stockage et construire et supprimer des index.
 

Les objets de stockage sont créés avec un simple appel à createObjectStore(). La méthode prend le nom du stockage et un paramètre objet. Même si le paramètre objet est optionnel, il est très important, puisqu'il vous laisse définir d'importantes propriétés optionnelles et redéfinir le type d'un objet de stockage que vous voulez créer. Dans ce cas, nous avons demandé un objet de stockage nommé "customers" et défini un keyPath, qui est la propriété qui fait qu'un objet individuel est unique dans le stockage. Cette propriété dans l'exemple est "ssn" puisqu'un numéro de sécurité sociale est garanti d'être unique. "ssn" doit être présent sur chaque objet stocké dans objetStore

Nous avons aussi demandé un index nommé "name" qui examine la propriété name dans les objets stockés. Comme avec createObjectStore(), createIndex() prend un objet optionnel options qui définit le type d'index qu'il doit créer. Ajouter des objets qui n'auront pas de propriété name fonctionnera, mais ces objets n'apparaitront pas dans l'index "name".

Nous pourrons récupérer les clients stockés directement en utilisant leur ssn dans l'objet de stockage, ou en utilisant leur nom via l'index name. Pour en savoir plus sur le fonctionnement, se référer à la section using an index.

Utiliser la génération de clés

Paramétrer un marqueur autoIncrement lorsque l'on crée un objet de stockage activera le génération de clés pour cet objet de stockage. Par défault, ce marqueur n'est pas défini.

Avec la génération de clés, une clé sera générée automatiquement lorsque vous ajoutez une valeur à un objet de stockage. Le compteur initial pour la génération de clés est toujours défini à 1 lorsque l'objet de stockage est créé pour la première fois. Fondamentalement, une nouvelle clé auto-générée sera incrémentée de 1 par rapport à la précédente clé. Le nombre initial d'un générateur de clé ne décroit jamais, à moins qu'un résultat d'opération sur la base soit annulé, par exemple, une transaction est annulée. Supprimer un enregistrement, voire l'ensemble des enregistrements d'un objet de stockage n'affecte jamais la génération de clé d'un objet de stockage.

Nous pouvons créer un autre objet de stockage avec un générateur de clé comme ci-dessous :

// Ouverture d'indexedDB.
var request = indexedDB.open(dbName, 3);

request.onupgradeneeded = function (event) {

    var db = event.target.result;

    // Création d'un autre objet appelé "names" avec l'option autoIncrement définie à true.    
    var objStore = db.createObjectStore("names", { autoIncrement : true });

    // Puisque l'objet "names" a un générateur de clé, la clé pour la valeur name est générée automatiquement.
    // Les enregistrements ajoutés ressembleront à ceci :
    // key : 1 => value : "Bill"
    // key : 2 => value : "Donna"
    for (var i in customerData) {
        objStore.add(customerData[i].name);
    }
}

Pour plus de détails sur la génération de clés, voyez "W3C Key Generators".

Ajouter, récupérer, et supprimer des données

Avant de faire quoi que ce soit avec votre nouvelle base de données, vous aurez besoin de démarrer une transaction. Les transactions viennent de l'objet base de données, et vous devez spécifier sur quel objet vous souhaitez faire pointer la transaction. Une fois dans la transaction, vous pouvez accéder à l'objet de stockage qui contient vos données et faire vos requêtes. Puis, vous devez décider si vous allez appliquer des changements à la base de données, ou si vous avez juste besoin de la lire. Les transactions disposent de trois modes disponibles: readonly, readwrite, et versionchange.

Pour changer le "schéma" ou la structure de la base de données — qui implique de créer ou supprimer des objets de stockage ou des index — la transaction doit être en mode versionchange. Cette transacton est ouverte en appelant la méthode IDBFactory.open  avec une version spécifiée. (Dans les navigateurs WebKit, qui n'ont pas implémenté la dernière spécification, la méthode IDBFactory.open prend seulement un paramètre, le nom de la base de données ; Vous devez donc appeler IDBVersionChangeRequest.setVersion pour établir la transaction versionchange.)

Pour lire les enregistrements d'un objet de stockage existant, la transaction peut être soit en mode readonly, soit readwrite. Pour appliquer des changements à un objet de stockage existant, la transaction doit être en mode readwrite. Vous démarrez ces transactions avec IDBDatabase.transaction. La méthode accepte deux paramètres : Les storeNames (la portée, définie comme un tableau d'objets de stockage auxquels vous souhaitez accéder) et le mode (readonly ou readwrite) pour la transaction. La méthode retourne un objet de transaction contenant la méthode IDBIndex.objectStore, que vous utilisez pour accéder à votre objet de stockage. Par défaut, lorsqu'aucun mode n'est spécifié, les transactions démarrent en mode readonly.

Note: A partir de Firefox 40, les transactions IndexedDB ont des garanties de durabilité relaxed afin d'augmenter les performances (voir bug 1112702.) Auparavant, lors d'une transaction readwrite IDBTransaction.oncomplete était déclenché seulement lorsque les données étaient garanties d'être écrites sur le disque. Dans Firefox 40+ l'évènement complete est déclenché une fois que l'OS a autorisé l'écriture de données, mais donc potentiellement avant que les données soient écrites sur le disque. L'évènement complete peut ainsi être livré plus vite qu'avant, cependant, il y une probabilité que l'ensemble de la transaction soit perdu si l'OS crashe ou qu'un problème électrique survient avant que les données soient écrites. Comme de tels évènements catastrophiques sont rares, la plupart des utilisateurs n'ont pas à s'en soucier. Si vous devez vous assurer de la durabilité pour quelconque raison (e.g. vous stockez des données critiques qui ne peuvent être recalculées plus tard) vous pouvez forcer une transaction à écrire sur le disque avant que l'évènement complete soit délivré en créant une transaction utilisant un mode expérimental (non-standard) readwriteflush  (se référer à IDBDatabase.transaction.

Vous pouvez accélérer l'accès à vos données en utilisant le bon mode et la bonne portée dans une transaction. Voici deux astuces :

  • Lorsque vous définissez la portée, spécifier uniquement les objets de stockage dont vous avez besoin. De cette manière, vous pouvez exécuter plusieurs transactions simultanément sans qu'elles se chevauchent.
  • Spécifier le mode readwrite pour une transaction seulement lorsque c'est nécessaire. Vous pouvez exécuter simulaténement plusieurs transactions readonly sans chevauchements, mais vous ne pouvez avoir qu'une seule transaction readwrite dans un objet de stockage. Pour en savoir plus, regardez la définition des transactions dans l'article des concepts de base.

Ajouter des données dans la base

Si vous venez juste de créer une base de données, alors vous souhaitez probablement écrire dedans. Voici à quoi ça peut ressembler :

var transaction = db.transaction(["customers"], "readwrite");
// Note: Les anciennes implémentations utilisent la constante dépréciée IDBTransaction.READ_WRITE au lieu de "readwrite".
// Au cas où vous souhaitiez supporter ces implémentations, vous pouvez écrire : 
// var transaction = db.transaction(["customers"], IDBTransaction.READ_WRITE);
La fonction transaction() prend deux arguments (bien qu'un soit optionnel) et retourne un objet transaction. Le premier argument est une liste d'objets de stockage que la transaction va traiter. Vous pouvez passer un tableau vide si vous voulez que la transaction traite l'ensemble des objets de stockage, mais ne le faites pas puisque la spécification désigne qu'un tableau vide devrait générer une InvalidAccessError. Si vous ne spécifiez rien pour le deuxième argument, vous démarrerez une transaction read-only. Si vous souhaitez écrire, vous devrez passer l'option "readwrite".

Maintenant que vous avez une transaction, vous devez comprendre sa durée de vie. Les transactions sont étroitement liées à la boucle de l'évènement. Si vous établissez une transaction et que vous sortez de la boucle d'évènements sans l'utiliser, alors la transaction deviendra inactive. La seule manière de garder la transaction active est d'y faire une requête. Lorsque la requête est terminée, vous aurez un évènement DOM, et en supposant que la requête a réussi, vous aurez une autre opportunité d'étendre la transaction durant ce callback. Si vous sortez de la boucle d'évènements sans étendre la transaction, alors elle deviendra inactive, etc… Tant qu'il restera des demandes en attente, la transaction restera active. La durée de vie des transactions est vraiment très simple, mais cela peut prendre un peu de temps à l'utiliser. Quelques exemples supplémentaires aideront. Si vous commencez à voir des codes d'erreur TRANSACTION_INACTIVE_ERR, alors vous avez raté quelque chose.

Les transactions peuvent recevoir des évènements DOM events de trois types : error, abort, et complete. Nous avons déjà parlé du fait que les error « bouillonnent ». Une transaction peut recevoir des évènements d'erreur qui peuvent venir de n'importe quelle requête. Un point plus subtil sur le comportement par défaut d'une erreur est d'annuler la transaction où elle a eu lieu. A moins que vous gériez l'erreur en appelant d'abord stopPropagation() sur l'évènement erreur, puis que vous fassiez quelque chose, la transaction complète sera annulée. Cette conception vous oblige à réfléchir et gérer les erreurs, mais vous pouvez toujours ajouter un gestionnaire d'erreurs « fourre-tout » à la base de données si la gestion d'erreurs fines est trop lourde. Si vous ne gérez par un évènement d'erreur, ou si vous appelez abort() sur la transaction, alors la transaction sera annulée et un évènement abort est lancé sur la transaction. Sinon, une fois que toutes les demandes en instance seront terminées, vous aurez un évènement complete. Si vous faites beaucoup d'opérations sur les bases de données, suivre le résultat d'une transaction plutôt que des requêtes individuelles peuvent être une aide précieuse.

Maintenant que vous avons une transaction, nous avons besoin de récupérer l'objet de stockage de celle-ci. Les transactions vous permettent seulement d'avoir un objet de stockage que vous avez spécifié lors de la création de la transaction. Puis, vous pouvez ajouter toutes les données dont vous avez besoin.

// Faire quelque chose lors toutes les données sont ajoutées à la base de données.
transaction.oncomplete = function(event) {
  alert("All done!");
};

transaction.onerror = function(event) {
  // N'oubliez pas de gérer les erreurs !
};

var objectStore = transaction.objectStore("customers");
for (var i in customerData) {
  var request = objectStore.add(customerData[i]);
  request.onsuccess = function(event) {
    // event.target.result == customerData[i].ssn;
  };
}
La méthode result d'une requête venant d'un appel à add() est la clé de la valeur qui vient d'être ajoutée. Dans ce cas, ce devrait être égal à la propriété ssn de l'objet qui vient d'être ajouté, puisque l'objet de stockage utilise la propriété ssn pour le key path. Notez que la fonction add() requiert qu'aucun objet déjà présent en base ait la même clé. Si vous essayez de modifier une entrée existante, si peu vous importe qu'une entrée existe déjà, vous pouvez utiliser la fonction put(), comme montré plus loin dans la section Updating an entry in the database.
 

Supprimer des données dans la base de données

Supprimer des données est très similaire :

var request = db.transaction(["customers"], "readwrite")
                .objectStore("customers")
                .delete("444-44-4444");
request.onsuccess = function(event) {
  // c'est supprimé !
};

Récupérer des données de la base de données

Maintenant que la base de données dispose de quelques infos, vous pouvez les récupérer de plusieurs façons. D'abord, la plus simple get(). Vous devez fournir une clé pour récupérer la valeur, comme ceci :

var transaction = db.transaction(["customers"]);
var objectStore = transaction.objectStore("customers");
var request = objectStore.get("444-44-4444");
request.onerror = function(event) {
  // gestion des erreurs!
};
request.onsuccess = function(event) {
  // Faire quelque chose avec request.result !
  alert("Name for SSN 444-44-4444 is " + request.result.name);
};

Ça fait beaucoup de code pour une "simple" récupération. Voici comment raccourcir un peu en supposant que vous gériez les erreurs au niveau de la base de données :

db.transaction("customers").objectStore("customers").get("444-44-4444").onsuccess = function(event) {
  alert("Name for SSN 444-44-4444 is " + event.target.result.name);
};
Vous voyez comment ça fonctionne ? Comme il n'y a qu'un seul objet de stockage, vous pouvez éviter de passer une liste d'objets dont vous avez besoin dans votre transaction, et juste passer le nom comme une chaîne de caractères. Aussi, nous faisons seulement de la lecture de la base, donc nous n'avons pas besoin d'une transaction "readwrite". Appeler une transaction transaction() sans mode spécifié nous donne une transaction "readonly". Une autre subtilité ici est que nous n'assignons pas dans une variable l'objet de notre requête. Since the DOM event has the request as its target you can use the event to get to the result property.

Note that you can speed up data access by limiting the scope and mode in the transaction. Here are a couple of tips:

  • When defining the scope, specify only the object stores you need. This way, you can run multiple transactions with non-overlapping scopes concurrently.
  • Only specify a readwrite transaction mode when necessary. You can concurrently run multiple readonly transactions with overlapping scopes, but you can have only one readwrite transaction for an object store. To learn more, see the definition for transactions in the Basic Concepts article.

Updating an entry in the database

Now we've retrieved some data, updating it and inserting it back into the IndexedDB is pretty simple. Let's update the previous example somewhat:

var objectStore = db.transaction(["customers"], "readwrite").objectStore("customers");
var request = objectStore.get("444-44-4444");
request.onerror = function(event) {
  // Handle errors!
};
request.onsuccess = function(event) {
  // Get the old value that we want to update
  var data = request.result;
  
  // update the value(s) in the object that you want to change
  data.age = 42;

  // Put this updated object back into the database.
  var requestUpdate = objectStore.put(data);
   requestUpdate.onerror = function(event) {
     // Do something with the error
   };
   requestUpdate.onsuccess = function(event) {
     // Success - the data is updated!
   };
};
So here we're creating an objectStore and requesting a customer record out of it, identified by its ssn value (444-44-4444). We then put the result of that request in a variable (data), update the age property of this object, then create a second request (requestUpdate) to put the customer record back into the objectStore, overwriting the previous value.

Note: In this case we've had to specify a readwrite transaction because we want to write to the database, not just read from it.

Using a cursor

Using get() requires that you know which key you want to retrieve. If you want to step through all the values in your object store, then you can use a cursor. Here's what it looks like:

var objectStore = db.transaction("customers").objectStore("customers");

objectStore.openCursor().onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    alert("Name for SSN " + cursor.key + " is " + cursor.value.name);
    cursor.continue();
  }
  else {
    alert("No more entries!");
  }
};
The openCursor() function takes several arguments. First, you can limit the range of items that are retrieved by using a key range object that we'll get to in a minute. Second, you can specify the direction that you want to iterate. In the above example, we're iterating over all objects in ascending order. The success callback for cursors is a little special. The cursor object itself is the result of the request (above we're using the shorthand, so it's event.target.result). Then the actual key and value can be found on the key and value properties of the cursor object. If you want to keep going, then you have to call continue() on the cursor. When you've reached the end of the data (or if there were no entries that matched your openCursor() request) you still get a success callback, but the result property is undefined.

One common pattern with cursors is to retrieve all objects in an object store and add them to an array, like this:

var customers = [];

objectStore.openCursor().onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    customers.push(cursor.value);
    cursor.continue();
  }
  else {
    alert("Got all customers: " + customers);
  }
};

Note: Mozilla has also implemented getAll() to handle this case (and getAllKeys(), which is currently hidden behind the dom.indexedDB.experimental preference in about:config). These aren't part of the IndexedDB standard, so they may disappear in the future. We've included them because we think they're useful. The following code does precisely the same thing as above:

objectStore.getAll().onsuccess = function(event) {
  alert("Got all customers: " + event.target.result);
};

There is a performance cost associated with looking at the value property of a cursor, because the object is created lazily. When you use getAll() for example, Gecko must create all the objects at once. If you're just interested in looking at each of the keys, for instance, it is much more efficient to use a cursor than to use getAll(). If you're trying to get an array of all the objects in an object store, though, use getAll().

Using an index

Storing customer data using the SSN as a key is logical since the SSN uniquely identifies an individual. (Whether this is a good idea for privacy is a different question, and outside the scope of this article.) If you need to look up a customer by name, however, you'll need to iterate over every SSN in the database until you find the right one. Searching in this fashion would be very slow, so instead you can use an index.

var index = objectStore.index("name");

index.get("Donna").onsuccess = function(event) {
  alert("Donna's SSN is " + event.target.result.ssn);
};

The "name" cursor isn't unique, so there could be more than one entry with the name set to "Donna". In that case you always get the one with the lowest key value.

If you need to access all the entries with a given name you can use a cursor. You can open two different types of cursors on indexes. A normal cursor maps the index property to the object in the object store. A key cursor maps the index property to the key used to store the object in the object store. The differences are illustrated here:

// Using a normal cursor to grab whole customer record objects
index.openCursor().onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    // cursor.key is a name, like "Bill", and cursor.value is the whole object.
    alert("Name: " + cursor.key + ", SSN: " + cursor.value.ssn + ", email: " + cursor.value.email);
    cursor.continue();
  }
};

// Using a key cursor to grab customer record object keys
index.openKeyCursor().onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    // cursor.key is a name, like "Bill", and cursor.value is the SSN.
    // No way to directly get the rest of the stored object.
    alert("Name: " + cursor.key + ", SSN: " + cursor.value);
    cursor.continue();
  }
};

Specifying the range and direction of cursors

If you would like to limit the range of values you see in a cursor, you can use an IDBKeyRange object and pass it as the first argument to openCursor() or openKeyCursor(). You can make a key range that only allows a single key, or one that has a lower or upper bound, or one that has both a lower and upper bound. The bound may be "closed" (i.e., the key range includes the given value(s)) or "open" (i.e., the key range does not include the given value(s)). Here's how it works:

// Only match "Donna"
var singleKeyRange = IDBKeyRange.only("Donna");

// Match anything past "Bill", including "Bill"
var lowerBoundKeyRange = IDBKeyRange.lowerBound("Bill");

// Match anything past "Bill", but don't include "Bill"
var lowerBoundOpenKeyRange = IDBKeyRange.lowerBound("Bill", true);

// Match anything up to, but not including, "Donna"
var upperBoundOpenKeyRange = IDBKeyRange.upperBound("Donna", true);

// Match anything between "Bill" and "Donna", but not including "Donna"
var boundKeyRange = IDBKeyRange.bound("Bill", "Donna", false, true);

// To use one of the key ranges, pass it in as the first argument of openCursor()/openKeyCursor()
index.openCursor(boundKeyRange).onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    // Do something with the matches.
    cursor.continue();
  }
};

Sometimes you may want to iterate in descending order rather than in ascending order (the default direction for all cursors). Switching direction is accomplished by passing prev to the openCursor() function as the second argument:

objectStore.openCursor(boundKeyRange, "prev").onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    // Do something with the entries.
    cursor.continue();
  }
};

If you just want to specify a change of direction but not constrain the results shown, you can just pass in null as the first argument:

objectStore.openCursor(null, "prev").onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    // Do something with the entries.
    cursor.continue();
  }
};

Since the "name" index isn't unique, there might be multiple entries where name is the same. Note that such a situation cannot occur with object stores since the key must always be unique. If you wish to filter out duplicates during cursor iteration over indexes, you can pass nextunique (or prevunique if you're going backwards) as the direction parameter. When nextunique or prevunique is used, the entry with the lowest key is always the one returned.

index.openKeyCursor(null, "nextunique").onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    // Do something with the entries.
    cursor.continue();
  }
};

Please see "IDBCursor Constants" for the valid direction arguments.

Version changes while a web app is open in another tab

When your web app changes in such a way that a version change is required for your database, you need to consider what happens if the user has the old version of your app open in one tab and then loads the new version of your app in another. When you call open() with a greater version than the actual version of the database, all other open databases must explicitly acknowledge the request before you can start making changes to the database (an onblocked event is fired until they are closed or reloaded). Here's how it works:

var openReq = mozIndexedDB.open("MyTestDatabase", 2);

openReq.onblocked = function(event) {
  // If some other tab is loaded with the database, then it needs to be closed
  // before we can proceed.
  alert("Please close all other tabs with this site open!");
};
  
openReq.onupgradeneeded = function(event) {
  // All other databases have been closed. Set everything up.
  db.createObjectStore(/* ... */);
  useDatabase(db);
}  
  
openReq.onsuccess = function(event) {
  var db = event.target.result;
  useDatabase(db);
  return;
}

function useDatabase(db) {
  // Make sure to add a handler to be notified if another page requests a version
  // change. We must close the database. This allows the other page to upgrade the database.
  // If you don't do this then the upgrade won't happen until the user closes the tab.
  db.onversionchange = function(event) {
    db.close();
    alert("A new version of this page is ready. Please reload!");
  };

  // Do stuff with the database.
}

Security

IndexedDB uses the same-origin principle, which means that it ties the store to the origin of the site that creates it (typically, this is the site domain or subdomain), so it cannot be accessed by any other origin.

It's important to note that IndexedDB doesn't work for content loaded into a frame from another site (either <frame> or <iframe>). This is a security and privacy measure and can be considered analogous to the blocking of third-party cookies. For more details, see bug 595307.

Warning About Browser Shutdown

When the browser shuts down (e.g., when the user selects Exit or clicks the Close button), any pending IndexedDB transactions are (silently) aborted — they will not complete, and they will not trigger the error handler. Since the user can exit the browser at any time, this means that you cannot rely upon any particular transaction to complete or to know that it did not complete. There are several implications of this behavior.

First, you should take care to always leave your database in a consistent state at the end of every transaction. For example, suppose that you are using IndexedDB to store a list of items that you allow the user to edit. You save the list after the edit by clearing the object store and then writing out the new list. If you clear the object store in one transaction and write the new list in another transaction, there is a danger that the browser will close after the clear but before the write, leaving you with an empty database. To avoid this, you should combine the clear and the write into a single transaction. 

Second, you should never tie database transactions to unload events. If the unload event is triggered by the browser closing, any transactions created in the unload event handler will never complete. An intuitive approach to maintaining some information across browser sessions is to read it from the database when the browser (or a particular page) is opened, update it as the user interacts with the browser, and then save it to the database when the browser (or page) closes. However, this will not work. The database transactions will be created in the unload event handler, but because they are asynchronous they will be aborted before they can execute.

In fact, there is no way to guarantee that IndexedDB transactions will complete, even with normal browser shutdown. See bug 870645.

Locale-aware sorting

Mozilla have implemented the ability to perform locale-aware sorting of IndexedDB data in Firefox 43+. By default, IndexedDB didn’t handle internationalization of sorting strings at all, and everything was sorted as if it was English text. For example, b, á, z, a would be sorted as:

  • a
  • b
  • z
  • á

which is obviously not how users want their data to be sorted — Aaron and Áaron for example should go next to one another in a contacts list. Achieving proper international sorting therefore required the entire dataset to be called into memory, and sorting to be performed by client-side JavaScript, which is not very efficient.

This new functionality enables developers to specify a locale when creating an index using IDBObjectStore.createIndex() (check out its parameters.) In such cases, when a cursor is then used to iterate through the dataset and you want to specify locale-aware sorting, you can use a specialized IDBLocaleAwareKeyRange.

IDBIndex has also had new properties added to it to specify if it has a locale specified, and what it is: locale (returns the locale if any, or null if none is specified) and isAutoLocale (returns true if the index was created with an auto locale, meaning that the platform's default locale is used, false otherwise.)

Note: This feature is currently hidden behind a flag — to enable it and experiment, go to about:config and enable dom.indexedDB.experimental.

Full IndexedDB example

HTML Content

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>    

    <h1>IndexedDB Demo: storing blobs, e-publication example</h1>
    <div class="note">
      <p>
        Works and tested with:
      </p>
      <div id="compat">
      </div>
    </div>

    <div id="msg">
    </div>

    <form id="register-form">
      <table>
        <tbody>
          <tr>
            <td>
              <label for="pub-title" class="required">
                Title:
              </label>
            </td>
            <td>
              <input type="text" id="pub-title" name="pub-title" />
            </td>
          </tr>
          <tr>
            <td>
              <label for="pub-biblioid" class="required">
                Bibliographic ID:<br/>
                <span class="note">(ISBN, ISSN, etc.)</span>
              </label>
            </td>
            <td>
              <input type="text" id="pub-biblioid" name="pub-biblioid"/>
            </td>
          </tr>
          <tr>
            <td>
              <label for="pub-year">
                Year:
              </label>
            </td>
            <td>
              <input type="number" id="pub-year" name="pub-year" />
            </td>
          </tr>
        </tbody>
        <tbody>
          <tr>
            <td>
              <label for="pub-file">
                File image:
              </label>
            </td>
            <td>
              <input type="file" id="pub-file"/>
            </td>
          </tr>
          <tr>
            <td>
              <label for="pub-file-url">
                Online-file image URL:<br/>
                <span class="note">(same origin URL)</span>
              </label>
            </td>
            <td>
              <input type="text" id="pub-file-url" name="pub-file-url"/>
            </td>
          </tr>
        </tbody>
      </table>

      <div class="button-pane">
        <input type="button" id="add-button" value="Add Publication" />
        <input type="reset" id="register-form-reset"/>
      </div>
    </form>

    <form id="delete-form">
      <table>
        <tbody>
          <tr>
            <td>
              <label for="pub-biblioid-to-delete">
                Bibliographic ID:<br/>
                <span class="note">(ISBN, ISSN, etc.)</span>
              </label>
            </td>
            <td>
              <input type="text" id="pub-biblioid-to-delete"
                     name="pub-biblioid-to-delete" />
            </td>
          </tr>
          <tr>
            <td>
              <label for="key-to-delete">
                Key:<br/>
                <span class="note">(for example 1, 2, 3, etc.)</span>
              </label>
            </td>
            <td>
              <input type="text" id="key-to-delete"
                     name="key-to-delete" />
            </td>
          </tr>
        </tbody>
      </table>
      <div class="button-pane">
        <input type="button" id="delete-button" value="Delete Publication" />
        <input type="button" id="clear-store-button"
               value="Clear the whole store" class="destructive" />
      </div>
    </form>

    <form id="search-form">
      <div class="button-pane">
        <input type="button" id="search-list-button"
               value="List database content" />
      </div>
    </form>

    <div>
      <div id="pub-msg">
      </div>
      <div id="pub-viewer">
      </div>
      <ul id="pub-list">
      </ul>
    </div>

CSS Content

body {
  font-size: 0.8em;
  font-family: Sans-Serif;
}

form {
  background-color: #cccccc;
  border-radius: 0.3em;
  display: inline-block;
  margin-bottom: 0.5em;
  padding: 1em;
}

table {
  border-collapse: collapse;
}

input {
  padding: 0.3em;
  border-color: #cccccc;
  border-radius: 0.3em;
}

.required:after {
  content: "*";
  color: red;
}

.button-pane {
  margin-top: 1em;
}

#pub-viewer {
  float: right;
  width: 48%;
  height: 20em;
  border: solid #d092ff 0.1em;
}
#pub-viewer iframe {
  width: 100%;
  height: 100%;
}

#pub-list {
  width: 46%;
  background-color: #eeeeee;
  border-radius: 0.3em;
}
#pub-list li {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  padding-right: 0.5em;
}

#msg {
  margin-bottom: 1em;
}

.action-success {
  padding: 0.5em;
  color: #00d21e;
  background-color: #eeeeee;
  border-radius: 0.2em;
}

.action-failure {
  padding: 0.5em;
  color: #ff1408;
  background-color: #eeeeee;
  border-radius: 0.2em;
}

.note {
  font-size: smaller;
}

.destructive {
  background-color: orange;
}
.destructive:hover {
  background-color: #ff8000;
}
.destructive:active {
  background-color: red;
}

JavaScript Content

(function () {
  var COMPAT_ENVS = [
    ['Firefox', ">= 16.0"],
    ['Google Chrome',
     ">= 24.0 (you may need to get Google Chrome Canary), NO Blob storage support"]
  ];
  var compat = $('#compat');
  compat.empty();
  compat.append('<ul id="compat-list"></ul>');
  COMPAT_ENVS.forEach(function(val, idx, array) {
    $('#compat-list').append('<li>' + val[0] + ': ' + val[1] + '</li>');
  });

  const DB_NAME = 'mdn-demo-indexeddb-epublications';
  const DB_VERSION = 1; // Use a long long for this value (don't use a float)
  const DB_STORE_NAME = 'publications';

  var db;

  // Used to keep track of which view is displayed to avoid uselessly reloading it
  var current_view_pub_key;

  function openDb() {
    console.log("openDb ...");
    var req = indexedDB.open(DB_NAME, DB_VERSION);
    req.onsuccess = function (evt) {
      // Better use "this" than "req" to get the result to avoid problems with
      // garbage collection.
      // db = req.result;
      db = this.result;
      console.log("openDb DONE");
    };
    req.onerror = function (evt) {
      console.error("openDb:", evt.target.errorCode);
    };

    req.onupgradeneeded = function (evt) {
      console.log("openDb.onupgradeneeded");
      var store = evt.currentTarget.result.createObjectStore(
        DB_STORE_NAME, { keyPath: 'id', autoIncrement: true });

      store.createIndex('biblioid', 'biblioid', { unique: true });
      store.createIndex('title', 'title', { unique: false });
      store.createIndex('year', 'year', { unique: false });
    };
  }

  /**
   * @param {string} store_name
   * @param {string} mode either "readonly" or "readwrite"
   */
  function getObjectStore(store_name, mode) {
    var tx = db.transaction(store_name, mode);
    return tx.objectStore(store_name);
  }

  function clearObjectStore(store_name) {
    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
    var req = store.clear();
    req.onsuccess = function(evt) {
      displayActionSuccess("Store cleared");
      displayPubList(store);
    };
    req.onerror = function (evt) {
      console.error("clearObjectStore:", evt.target.errorCode);
      displayActionFailure(this.error);
    };
  }

  function getBlob(key, store, success_callback) {
    var req = store.get(key);
    req.onsuccess = function(evt) {
      var value = evt.target.result;
      if (value)
        success_callback(value.blob);
    };
  }

  /**
   * @param {IDBObjectStore=} store
   */
  function displayPubList(store) {
    console.log("displayPubList");

    if (typeof store == 'undefined')
      store = getObjectStore(DB_STORE_NAME, 'readonly');

    var pub_msg = $('#pub-msg');
    pub_msg.empty();
    var pub_list = $('#pub-list');
    pub_list.empty();
    // Resetting the iframe so that it doesn't display previous content
    newViewerFrame();

    var req;
    req = store.count();
    // Requests are executed in the order in which they were made against the
    // transaction, and their results are returned in the same order.
    // Thus the count text below will be displayed before the actual pub list
    // (not that it is algorithmically important in this case).
    req.onsuccess = function(evt) {
      pub_msg.append('<p>There are <strong>' + evt.target.result +
                     '</strong> record(s) in the object store.</p>');
    };
    req.onerror = function(evt) {
      console.error("add error", this.error);
      displayActionFailure(this.error);
    };

    var i = 0;
    req = store.openCursor();
    req.onsuccess = function(evt) {
      var cursor = evt.target.result;

      // If the cursor is pointing at something, ask for the data
      if (cursor) {
        console.log("displayPubList cursor:", cursor);
        req = store.get(cursor.key);
        req.onsuccess = function (evt) {
          var value = evt.target.result;
          var list_item = $('<li>' +
                            '[' + cursor.key + '] ' +
                            '(biblioid: ' + value.biblioid + ') ' +
                            value.title +
                            '</li>');
          if (value.year != null)
            list_item.append(' - ' + value.year);

          if (value.hasOwnProperty('blob') &&
              typeof value.blob != 'undefined') {
            var link = $('<a href="' + cursor.key + '">File</a>');
            link.on('click', function() { return false; });
            link.on('mouseenter', function(evt) {
                      setInViewer(evt.target.getAttribute('href')); });
            list_item.append(' / ');
            list_item.append(link);
          } else {
            list_item.append(" / No attached file");
          }
          pub_list.append(list_item);
        };

        // Move on to the next object in store
        cursor.continue();

        // This counter serves only to create distinct ids
        i++;
      } else {
        console.log("No more entries");
      }
    };
  }

  function newViewerFrame() {
    var viewer = $('#pub-viewer');
    viewer.empty();
    var iframe = $('<iframe />');
    viewer.append(iframe);
    return iframe;
  }

  function setInViewer(key) {
    console.log("setInViewer:", arguments);
    key = Number(key);
    if (key == current_view_pub_key)
      return;

    current_view_pub_key = key;

    var store = getObjectStore(DB_STORE_NAME, 'readonly');
    getBlob(key, store, function(blob) {
      console.log("setInViewer blob:", blob);
      var iframe = newViewerFrame();

      // It is not possible to set a direct link to the
      // blob to provide a mean to directly download it.
      if (blob.type == 'text/html') {
        var reader = new FileReader();
        reader.onload = (function(evt) {
          var html = evt.target.result;
          iframe.load(function() {
            $(this).contents().find('html').html(html);
          });
        });
        reader.readAsText(blob);
      } else if (blob.type.indexOf('image/') == 0) {
        iframe.load(function() {
          var img_id = 'image-' + key;
          var img = $('<img id="' + img_id + '"/>');
          $(this).contents().find('body').html(img);
          var obj_url = window.URL.createObjectURL(blob);
          $(this).contents().find('#' + img_id).attr('src', obj_url);
          window.URL.revokeObjectURL(obj_url);
        });
      } else if (blob.type == 'application/pdf') {
        $('*').css('cursor', 'wait');
        var obj_url = window.URL.createObjectURL(blob);
        iframe.load(function() {
          $('*').css('cursor', 'auto');
        });
        iframe.attr('src', obj_url);
        window.URL.revokeObjectURL(obj_url);
      } else {
        iframe.load(function() {
          $(this).contents().find('body').html("No view available");
        });
      }

    });
  }

  /**
   * @param {string} biblioid
   * @param {string} title
   * @param {number} year
   * @param {string} url the URL of the image to download and store in the local
   *   IndexedDB database. The resource behind this URL is subjected to the
   *   "Same origin policy", thus for this method to work, the URL must come from
   *   the same origin as the web site/app this code is deployed on.
   */
  function addPublicationFromUrl(biblioid, title, year, url) {
    console.log("addPublicationFromUrl:", arguments);

    var xhr = new XMLHttpRequest();
    xhr.open('GET', url, true);
    // Setting the wanted responseType to "blob"
    // http://www.w3.org/TR/XMLHttpRequest2/#the-response-attribute
    xhr.responseType = 'blob';
    xhr.onload = function (evt) {
                           if (xhr.status == 200) {
                             console.log("Blob retrieved");
                             var blob = xhr.response;
                             console.log("Blob:", blob);
                             addPublication(biblioid, title, year, blob);
                           } else {
                             console.error("addPublicationFromUrl error:",
                                           xhr.responseText, xhr.status);
                           }
                         };
    xhr.send();

    // We can't use jQuery here because as of jQuery 1.8.3 the new "blob"
    // responseType is not handled.
    // http://bugs.jquery.com/ticket/11461
    // http://bugs.jquery.com/ticket/7248
    // $.ajax({
    //   url: url,
    //   type: 'GET',
    //   xhrFields: { responseType: 'blob' },
    //   success: function(data, textStatus, jqXHR) {
    //     console.log("Blob retrieved");
    //     console.log("Blob:", data);
    //     // addPublication(biblioid, title, year, data);
    //   },
    //   error: function(jqXHR, textStatus, errorThrown) {
    //     console.error(errorThrown);
    //     displayActionFailure("Error during blob retrieval");
    //   }
    // });
  }

  /**
   * @param {string} biblioid
   * @param {string} title
   * @param {number} year
   * @param {Blob=} blob
   */
  function addPublication(biblioid, title, year, blob) {
    console.log("addPublication arguments:", arguments);
    var obj = { biblioid: biblioid, title: title, year: year };
    if (typeof blob != 'undefined')
      obj.blob = blob;

    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
    var req;
    try {
      req = store.add(obj);
    } catch (e) {
      if (e.name == 'DataCloneError')
        displayActionFailure("This engine doesn't know how to clone a Blob, " +
                             "use Firefox");
      throw e;
    }
    req.onsuccess = function (evt) {
      console.log("Insertion in DB successful");
      displayActionSuccess();
      displayPubList(store);
    };
    req.onerror = function() {
      console.error("addPublication error", this.error);
      displayActionFailure(this.error);
    };
  }

  /**
   * @param {string} biblioid
   */
  function deletePublicationFromBib(biblioid) {
    console.log("deletePublication:", arguments);
    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
    var req = store.index('biblioid');
    req.get(biblioid).onsuccess = function(evt) {
      if (typeof evt.target.result == 'undefined') {
        displayActionFailure("No matching record found");
        return;
      }
      deletePublication(evt.target.result.id, store);
    };
    req.onerror = function (evt) {
      console.error("deletePublicationFromBib:", evt.target.errorCode);
    };
  }

  /**
   * @param {number} key
   * @param {IDBObjectStore=} store
   */
  function deletePublication(key, store) {
    console.log("deletePublication:", arguments);

    if (typeof store == 'undefined')
      store = getObjectStore(DB_STORE_NAME, 'readwrite');

    // As per spec http://www.w3.org/TR/IndexedDB/#object-store-deletion-operation
    // the result of the Object Store Deletion Operation algorithm is
    // undefined, so it's not possible to know if some records were actually
    // deleted by looking at the request result.
    var req = store.get(key);
    req.onsuccess = function(evt) {
      var record = evt.target.result;
      console.log("record:", record);
      if (typeof record == 'undefined') {
        displayActionFailure("No matching record found");
        return;
      }
      // Warning: The exact same key used for creation needs to be passed for
      // the deletion. If the key was a Number for creation, then it needs to
      // be a Number for deletion.
      req = store.delete(key);
      req.onsuccess = function(evt) {
        console.log("evt:", evt);
        console.log("evt.target:", evt.target);
        console.log("evt.target.result:", evt.target.result);
        console.log("delete successful");
        displayActionSuccess("Deletion successful");
        displayPubList(store);
      };
      req.onerror = function (evt) {
        console.error("deletePublication:", evt.target.errorCode);
      };
    };
    req.onerror = function (evt) {
      console.error("deletePublication:", evt.target.errorCode);
      };
  }

  function displayActionSuccess(msg) {
    msg = typeof msg != 'undefined' ? "Success: " + msg : "Success";
    $('#msg').html('<span class="action-success">' + msg + '</span>');
  }
  function displayActionFailure(msg) {
    msg = typeof msg != 'undefined' ? "Failure: " + msg : "Failure";
    $('#msg').html('<span class="action-failure">' + msg + '</span>');
  }
  function resetActionStatus() {
    console.log("resetActionStatus ...");
    $('#msg').empty();
    console.log("resetActionStatus DONE");
  }

  function addEventListeners() {
    console.log("addEventListeners");

    $('#register-form-reset').click(function(evt) {
      resetActionStatus();
    });

    $('#add-button').click(function(evt) {
      console.log("add ...");
      var title = $('#pub-title').val();
      var biblioid = $('#pub-biblioid').val();
      if (!title || !biblioid) {
        displayActionFailure("Required field(s) missing");
        return;
      }
      var year = $('#pub-year').val();
      if (year != '') {
        // Better use Number.isInteger if the engine has EcmaScript 6
        if (isNaN(year))  {
          displayActionFailure("Invalid year");
          return;
        }
        year = Number(year);
      } else {
        year = null;
      }

      var file_input = $('#pub-file');
      var selected_file = file_input.get(0).files[0];
      console.log("selected_file:", selected_file);
      // Keeping a reference on how to reset the file input in the UI once we
      // have its value, but instead of doing that we rather use a "reset" type
      // input in the HTML form.
      //file_input.val(null);
      var file_url = $('#pub-file-url').val();
      if (selected_file) {
        addPublication(biblioid, title, year, selected_file);
      } else if (file_url) {
        addPublicationFromUrl(biblioid, title, year, file_url);
      } else {
        addPublication(biblioid, title, year);
      }

    });

    $('#delete-button').click(function(evt) {
      console.log("delete ...");
      var biblioid = $('#pub-biblioid-to-delete').val();
      var key = $('#key-to-delete').val();

      if (biblioid != '') {
        deletePublicationFromBib(biblioid);
      } else if (key != '') {
        // Better use Number.isInteger if the engine has EcmaScript 6
        if (key == '' || isNaN(key))  {
          displayActionFailure("Invalid key");
          return;
        }
        key = Number(key);
        deletePublication(key);
      }
    });

    $('#clear-store-button').click(function(evt) {
      clearObjectStore();
    });

    var search_button = $('#search-list-button');
    search_button.click(function(evt) {
      displayPubList();
    });

  }

  openDb();
  addEventListeners();

})(); // Immediately-Invoked Function Expression (IIFE)

Test the online live demo

See also

Reference

Tutorials

Related articles

Firefox

Étiquettes et contributeurs liés au document

Étiquettes : 
 Contributeurs à cette page : SphinxKnight, P45QU10U, zap221
 Dernière mise à jour par : SphinxKnight,