IDBObjectStore.put()
====================

La méthode **`put()`**, rattachée à l'interface `IDBObjectStore`, renvoie un objet `IDBRequest` et, dans un autre *thread*, crée un clone structuré de la valeur puis enregistre ce clone dans le magasin d'objet. Cette méthode permet ainsi d'ajouter de nouveaux enregistrements ou de mettre à jour des enregistrements existants dans un magasin d'objet lorsque la transaction est en mode `readwrite` (lecture-écriture)

Si l'enregistrement est stocké avec succès, un évènement de succès sera déclenché sur la requête renvoyée par la méthode. La propriété `result` de cette requête contiendra la clé de l'enregistrement créé ou mis à jour. La propriété `transaction` de cette requête sera la transaction dans laquelle le magasin d'objet est ouvert.

La méthode `put()` permet d'ajouter ou de mettre à jour. Si on souhaite uniquement insérer, on utilisera plutôt `IDBObjectStore.add`.

**Note:** Cette fonctionnalité est disponible via les Web Workers

Syntaxe
-------


```js
var request = objectStore.put(monElement);
var request = objectStore.put(monElement, cleOptionnelle);
```

### Paramètres

`monElement`

La valeur qu'on souhaite enregistrer.

`cleOptionnelle` Facultatif

La clé qu'on souhaite utiliser pour identifier l'enregistrement. Si cet argument est absent, la valeur par défaut sera `null`.

### Valeur de retour

Un objet `IDBRequest` qui recevra les évènements qui seront déclenchés suite à cette opération.

### Exceptions

Cette méthode peut lever une de ces exceptions `DOMException` :

| Exception | Description |
| --- | --- |
| `ReadOnlyError` | 
 La transaction associée à l'opération est uniquement
 dans un mode de lecture seule.
  |
| `TransactionInactiveError` | 
 La transaction rattachée à l'objet
 `IDBObjectStore` est inactive.
  |
| `DataError` | L'une de ces conditions est vérifiée :* Le magasin d'objet utilise des clés en ligne (*in-line keys*)
 ou dispose d'un générateur de clés et le paramètre pour la clé a été
 utilisé.
* Le magasin d'objet utilise des clés en ligne (*in-line keys*), ne dispose pas d'un générateur de clés et le paramètre pour la
 clé n'a pas été utilisé.
* Le magasin d'objet utilise des clés en ligne (*in-line keys*), ne dispose pas d'un générateur de clés et le chemin de clé du
 magasin d'objet ne déclenche pas une clé valide.
* Le paramètre pour la clé a été fourni mais la valeur n'est pas une
 clé valide.
 |
| `InvalidStateError` | 
 L'objet `IDBObjectStore` a été supprimé ou
 déplacé.
  |
| `DataCloneError` | 
 Les données à enregistrer n'ont pas pu être clonées par l'algorithme
 interne.
  |

Exemples
--------

Dans l'exemple suivant, on effectue une requête pour obtenir l'enregistrement correspondant à un titre donné. Lorsque cette requête est réussie, on récupère l'enregistrement via la fonction `onsuccess`. Ensuite, on met à jour une des propriétés de l'enregistrement et on enregistre la valeur mise à jour dans le magasin d'objet avec une autre requête et `put()`.


```js
var title = "Walk dog";

// On ouvre une transaction
var objectStore = db
  .transaction(["toDoList"], "readwrite")
  .objectStore("toDoList");

// On obtient la liste to-do dont le titre correspond
var objectStoreTitleRequest = objectStore.get(title);

objectStoreTitleRequest.onsuccess = function () {
  // On récupère les données de l'objet associé
  // à l'enregistrement
  var data = objectStoreTitleRequest.result;

  // On met à jour la valeur de notified avec "yes"
  data.notified = "yes";

  // On crée une autre requête pour appliquer cette
  // mise à jour en base de données
  var updateTitleRequest = objectStore.put(data);

  // On imprime la transaction à l'origine
  // de la requête
  console.log(
    "La transaction originelle est " + updateTitleRequest.transaction,
  );

  // Lorsque cette nouvelle requête a réussi. On affiche
  // les données grâce à la fonction displayData()
  updateTitleRequest.onsuccess = function () {
    displayData();
  };
};
```

Spécifications
--------------

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbobjectstore-put① |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* Utiliser IndexedDB
* Initier une connexion : `IDBDatabase`
* Utiliser les transactions : `IDBTransaction`
* Définir un intervalle de clés : `IDBKeyRange`
* Récupérer et modifier les données : `IDBObjectStore`
* Utiliser les curseurs `IDBCursor`
* Exemple de référence : To-do Notifications (exemple *live*).