Doc: update Topic.image doc and example

xmindltd · Sep 26, 2023 · 4c832cf · 4c832cf
1 parent c7ee64b
commit 4c832cf
Show file tree

Hide file tree

Showing 2 changed files with 165 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -273,9 +273,10 @@ topic.marker(Object.assign({}, marker.smiley('cry'), {del: true}));
 
 You can use `.image()` to get `image key` back.
 
-However, you need to write image into manifest by `zip.updateManifestMetadata()`.
+However, you need to write image into manifest by `zip.updateManifestMetadata()` or `dumper.updateManifestMetadata()`.
 
 > [See image example](./example/example.image.js)
+> [See image in browser example](./example/example.image.browser.html)
 
 #### .summary(options) => Topic
 
@@ -383,6 +384,8 @@ Save components to the logic disk in the form of zip.
 
 The module of `Dumper` only works under browser.
 
+### Dumper methods
+
 #### .dumping() => Array<{filename: string, value: string}>
 
 Return an array of objects composed of file content.
@@ -393,6 +396,33 @@ you need to compress these files in the form of zip with the suffix `.xmind`.
 > 
 > Don't include top level folders, otherwise the software can't extract files
 
+#### .updateManifestMetadata(key, content, creator) => Promise\<void\>
+
+Update manifest for image insertion.
+
+| Name | Type | Default | Required | Description |
+|:---- |:----:|:-------:|:--------:|:------------|
+| key | string | null | Y | The key only can get by topic.image() |
+| content | File \| Blob \| ArrayBuffer | null | Y | The data of image |
+| creator | FileCreator | | Y | specify how to save the file |
+
+where `FileCreator` is
+
+```typescript
+interface FileCreator {
+  /**
+   * hint that should create a folder-like structure, enter the folder if exists
+   * @param name Folder name
+   */
+  folder(name: string): Promise<void>
+  /**
+   * hint that should create a file-like object with `content`, update the file if exists
+   * @param name Filename
+   */
+  file(name: string, content: File | Blob | ArrayBuffer): Promise<void>
+}
+```
+
 ## Contributing
 Thank you for being interested in the SDK.
 

diff --git a/example/example.image.browser.html b/example/example.image.browser.html
@@ -0,0 +1,134 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script src="../dist/xmind-sdk.bundle.js"></script>
+    <title>Example browser</title>
+  </head>
+
+  <body>
+    <label>
+      Insert Image:
+      <input type="file" accept="image/*" id="image-input" />
+    </label>
+
+    <script>
+      const input = document.getElementById("image-input");
+      input.addEventListener("change", (e) => {
+        if (!e.currentTarget.files || !e.currentTarget.files.length) {
+          return;
+        }
+
+        const [file] = e.currentTarget.files;
+
+        if (window.Workbook) {
+          const { Workbook, Topic, Dumper } = window;
+          const workbook = new Workbook();
+          const topic = new Topic({ sheet: workbook.createSheet("sheet-1") });
+          topic
+            .on()
+            .add({ title: "main topic 1" })
+            .add({ title: "main topic 2" });
+
+          const dumper = new Dumper({ workbook });
+
+          const imageKey = topic.image();
+          // work with the image, e.g. save the image to the storage
+          const storage = getStorage();
+          dumper
+            .updateManifestMetadata(imageKey, file, {
+              folder(name) {
+                return storage.folder(name);
+              },
+              file(name, content) {
+                return storage.file(name, content);
+              },
+            })
+            .then(() => {
+              const files = dumper.dumping();
+              console.log(files);
+
+              for (const file of files) {
+                console.log(file.filename, "\n", file.value);
+              }
+            });
+        }
+      });
+    </script>
+
+    <script>
+      // mock storage, not important
+      function getStorage() {
+        /** @type {Promise<IDBDatabase>} */
+        const dbReadyPromise = new Promise((resolve) => {
+          /** @type {IDBDatabase} */
+          let db;
+          const setupStore = () => {
+            return new Promise((resolve) => {
+              const resourcesStore = db
+                .transaction("resources", "readwrite")
+                .objectStore("resources");
+              resourcesStore.clear().addEventListener("success", () => {
+                console.log("[mock] store cleared");
+                resolve(db);
+              });
+            });
+          };
+
+          const openDbRequest = indexedDB.open("example", 1);
+          openDbRequest.addEventListener("error", () => {
+            console.error("[mock] error openning db");
+          });
+          openDbRequest.addEventListener("success", () => {
+            db = openDbRequest.result;
+            resolve(setupStore());
+          });
+          openDbRequest.addEventListener("upgradeneeded", (e) => {
+            db = e.target.result;
+            const resources = db.createObjectStore("resources", {
+              keyPath: "id",
+            });
+
+            resources.createIndex("id", "id", { unique: true });
+
+            resources.transaction.addEventListener("complete", () => {
+              resolve(setupStore());
+            });
+          });
+        });
+
+        const saveFile = (/** @type {IDBDatabase} */ db, { name, content }) => {
+          return Promise.resolve()
+            .then(() =>
+              content instanceof Blob ? content.arrayBuffer() : content
+            )
+            .then(
+              (resolvedContent) =>
+                new Promise((resolve) => {
+                  db.transaction("resources", "readwrite")
+                    .objectStore("resources")
+                    .put({ id: name, content: resolvedContent })
+                    .addEventListener("success", () => {
+                      console.log("[mock] file saved");
+                      resolve();
+                    });
+                })
+            );
+        };
+
+        const getDB = () => dbReadyPromise;
+
+        return {
+          file(name, content) {
+            return getDB().then((db) => saveFile(db, { name, content }));
+          },
+          folder(name) {
+            return getDB().then(() => {
+              console.log("[mock] move to resources");
+            });
+          },
+        };
+      }
+    </script>
+  </body>
+</html>