Merge pull request #15 from tmcw/data-view-example

Add dataview example

README.md

@@ -37,7 +37,7 @@ of this readme for some examples.
 
 ## Demo
 
-https://github.com/tmcw/obsidian-freeform/assets/32314/56b4e23a-2837-4a06-84c7-ee35b09c2634
+<https://github.com/tmcw/obsidian-freeform/assets/32314/56b4e23a-2837-4a06-84c7-ee35b09c2634>
 
 ### Examples
 
@@ -70,7 +70,7 @@ it with Freeform.
 #### Importing a module from esm.sh
 
 Most npm modules that are compatible with browsers are available from
-https://esm.sh/, jsdelivr, unpkg, or skypack. Observable Plot is an especially
+<https://esm.sh/>, jsdelivr, unpkg, or skypack. Observable Plot is an especially
 tricky one, but most "just work."
 
     ```freeform
@@ -90,6 +90,45 @@ like Preact [can work without it](https://preactjs.com/guide/v10/getting-started
     render(app, document.body);
     ```
 
+#### Querying DataView
+
+DataView is accessible via `window.top.app.plugins.plugins.dataview.api`.
+Here's an example of using it:
+
+    ```freeform
+    import * as Plot from "https://cdn.jsdelivr.net/npm/@observablehq/plot@0.6/+esm";
+
+    const items = await window.top.app.plugins.plugins.dataview.api
+      .query(`table price, purchased, color
+    from "03 Stuff"
+    where price and sold = undefined
+    sort purchased desc`);
+
+    const mapped = items.value.values
+      .map((item) => {
+        if (!item[2]) return;
+        return {
+          price: item[1],
+          date: new Date(item[2].toMillis()),
+        };
+      })
+      .filter((r) => r);
+
+    display(Plot.dot(mapped, { y: "price", x: "date" }).plot());
+    ```
+
+If you're doing more than one thing with the DataView API, you will probably
+want to alias the variable, like
+
+```js
+const dv = window.top.app.plugins.plugins.dataview.api
+```
+
+Also, note that `Date` objects that you get from DataView queries are
+originated from the top frame, so some code might not recognize them as Date
+instances. Recreating them with `new Date`, as in the example above, will
+fix that issue.
+
 ### Notes
 
 - There is a `width` variable, much like [Observable's](https://observablehq.com/framework/javascript#width), but
@@ -98,8 +137,8 @@ like Preact [can work without it](https://preactjs.com/guide/v10/getting-started
   way as it does on any webpage.
 - Only HTTP ESM imports are supported. This isn't Node.js or Deno - there
   isn't a node_modules directory, and you don't have short names for dependencies.
-  Thankfully, this usually isn't a problem because you can use https://esm.sh/
-  https://www.jsdelivr.com/ and more to import modules.
+  Thankfully, this usually isn't a problem because you can use <https://esm.sh/>
+  <https://www.jsdelivr.com/> and more to import modules.
 
 ## Components