Re: [w3c/IndexedDB] Adding examples for “versionchange” and “blocked”. (#133)

inexorabletash commented on this pull request.



> @@ -278,6 +278,63 @@ request.onsuccess = function() {
 };
 </pre>
 
+The database cannot upgrade while other tabs are still using it. To avoid blocking
+other tabs, you should use the "versionchange" event to close the connection to

should use → may listen for

> +the database.
+
+<pre class=lang-javascript>
+db.onversionchange = function() {
+  // First, save any unsaved data:
+  saveUnsavedData().then(function() {
+    // Now you need to close the database.
+    // If the document isn't being actively used, it may be appropriate to reload:
+    if (!document.hasFocus()) {
+      location.reload();
+      // Reloading will close the database, and also reload with the new JavaScript
+      // and database definitions.
+    } else {
+      // Alternatively you may close the database and display a message to the
+      // user. You need to ensure this isn't a disruptive user experience.
+      db.close();

maybe also `db = null` so that other page logic can notice the connection is done.

> +      db.close();
+      displayMessage("Disconnected from database, please refresh to reconnect.");
+    }
+  });
+};
+
+function saveUnsavedData() {
+  // How you do this depends on your app.
+}
+
+function displayMessage() {
+  // Show some sort of alert to the user.
+}
+</pre>
+
+Your new tabs can use the "blocked" event to detect if older tabs are preventing

Your new tabs → Pages
older tabs → tabs with older versions of the code

> +};
+
+request.onblocked = function() {
+  displayMessage("Please close other tabs to this site.");
+};
+
+request.onsuccess = function() {
+  hideMessage();
+};
+
+function hideMessage() {
+  // Hide a previously displayed message.
+}
+</pre>
+
+The user will only see the above message if another tab fails to disconnect from

Maybe clarify (based on previous questions that have been raised in this area)

If all recipients of "versionchange" close the connection synchronously within the handler then "blocked" will not be fired. But if they don't close synchronously (i.e. they ignored it, or they do async work like starting a final transaction to save state) then the "blocked" event will be seen.

Once all connections finally close then "success" will be seen - that is, the blocked state is not permanent. That's why it's important to hide the message when "success" comes in. 

> +Your new tabs can use the "blocked" event to detect if older tabs are preventing
+them from upgrading the database.
+
+<pre class=lang-javascript>
+var request = indexedDB.open("library", 4); // Request version 4.
+
+request.onupgradeneeded = function(event) {
+  // ...
+};
+
+request.onblocked = function() {
+  displayMessage("Please close other tabs to this site.");
+};
+
+request.onsuccess = function() {
+  hideMessage();

Should probably have `// ...` here indicating proceeding with the usual open steps

> @@ -278,6 +278,63 @@ request.onsuccess = function() {
 };
 </pre>
 
+The database cannot upgrade while other tabs are still using it. To avoid blocking
+other tabs, you should use the "versionchange" event to close the connection to

other tabs → other tabs trying to upgrade the database

> +other tabs, you should use the "versionchange" event to close the connection to
+the database.
+
+<pre class=lang-javascript>
+db.onversionchange = function() {
+  // First, save any unsaved data:
+  saveUnsavedData().then(function() {
+    // Now you need to close the database.
+    // If the document isn't being actively used, it may be appropriate to reload:
+    if (!document.hasFocus()) {
+      location.reload();
+      // Reloading will close the database, and also reload with the new JavaScript
+      // and database definitions.
+    } else {
+      // Alternatively you may close the database and display a message to the
+      // user. You need to ensure this isn't a disruptive user experience.

Do we want to list the other alternative, which is to notify the user that another tab wants to upgrade, so the user should finish their work and close (or reload) this one?

(That's probably getting too long.)


-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/IndexedDB/pull/133#pullrequestreview-15389391