|
| 1 | +--- |
| 2 | +title: Codeblock API |
| 3 | +sidebar_label: Codeblock API |
| 4 | +sidebar_position: 100 |
| 5 | +--- |
| 6 | + |
| 7 | +Datacore views are built around the datacore codeblock (also known as "local") API, which is available in any datacore |
| 8 | +codeblock as `dc`. The codeblock API provides access to a large number of useful utility functions and components with |
| 9 | +which you can build our more complicated views. |
| 10 | + |
| 11 | +Datacore codeblocks are built on React, so the basic structure of any codeblock will generally look like: |
| 12 | + |
| 13 | +~~~ |
| 14 | +```datacorejsx |
| 15 | +// Return a react functional component which renders your view. |
| 16 | +return function View() { |
| 17 | + // Call functions on the datacore API, 'dc'. |
| 18 | + const data = dc.useQuery("#book"); |
| 19 | +
|
| 20 | + // And then return a view, possibly using more datacore API calls. |
| 21 | + return <dc.List rows={data} renderer={book => book.$link} />; |
| 22 | +} |
| 23 | +``` |
| 24 | +~~~ |
| 25 | + |
| 26 | +## Fetching Data |
| 27 | + |
| 28 | +Datacore provides several methods for querying for data, including by the full query language and by path explicitly. |
| 29 | + |
| 30 | +#### `dc.useCurrentFile()` |
| 31 | + |
| 32 | +Loads the metadata for the file that the view is in - this will usually be `MarkdownPage`, but can also be a `CanvasPage`. |
| 33 | +Using this hook will automatically refresh the view whenever the current file changes. |
| 34 | + |
| 35 | +```jsx |
| 36 | +return function View() { |
| 37 | + const file = dc.useCurrentFile(); |
| 38 | + |
| 39 | + return <p>Hello, {file.$name}!</p>; |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +`dc.useCurrentFile` accepts an optional settings argument, which currently allows you to configure how often the view |
| 44 | +should update via the `debounce` property. |
| 45 | + |
| 46 | +```jsx |
| 47 | +// Only update the view at most once per 10 seconds (1000ms). |
| 48 | +const file = dc.useCurrentFile({ debounce: 10000 }); |
| 49 | +``` |
| 50 | + |
| 51 | +#### `dc.useCurrentPath()` |
| 52 | + |
| 53 | +Loads the path of the file that the view is in - this will usually be `MarkdownPage`, but can also be a `CanvasPage`. |
| 54 | +Using this hook will automatically refresh the view whenever the current file changes. |
| 55 | + |
| 56 | +```jsx |
| 57 | +return function View() { |
| 58 | + const path = dc.useCurrentPath(); |
| 59 | + |
| 60 | + return <p>The file is at {path}!</p>; |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +Like `useCurrentFile`, `dc.useCurrentPath` accepts an optional settings argument which can configure a `debounce`: |
| 65 | + |
| 66 | +```jsx |
| 67 | +// Only update the view at most once per 10 seconds (1000ms). |
| 68 | +const path = dc.useCurrentPath({ debounce: 10000 }); |
| 69 | +``` |
| 70 | + |
| 71 | +#### `dc.useQuery()` |
| 72 | + |
| 73 | +Query for a list of results using the [query language](/data/query). This will return a vanilla javascript list containing |
| 74 | +all of the results that match the query, which can be a wide range of different data types. This hook will cause the view |
| 75 | +to update whenever the query returns new results. |
| 76 | + |
| 77 | +```jsx |
| 78 | +return function View() { |
| 79 | + const books = dc.useQuery("#book and @page"); |
| 80 | + |
| 81 | + return <dc.List rows={books} renderer={book => book.$link} />; |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +`dc.useQuery` accepts an optional second argument containing configuration; currently, the only configuration option is `debounce`, |
| 86 | +which allows you to control how fast the view is allowed to update to reflect new results: |
| 87 | + |
| 88 | +```jsx |
| 89 | +return function View() { |
| 90 | + // Only allow the view to update every 10000ms (aka, 10 seconds). |
| 91 | + const books = dc.useQuery("#book and @page", { debounce: 10000 }); |
| 92 | + |
| 93 | + return <dc.List rows={books} renderer={book => book.$link} />; |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | + |
| 98 | +#### `dc.useFullQuery()` |
| 99 | + |
| 100 | +Variant of `dc.useQuery` which returns a full search result object, which mainly provides a bit of useful extra metadata about how the |
| 101 | +search performed. Specifically, it returns the following data: |
| 102 | + |
| 103 | +```jsx |
| 104 | +export interface SearchResult<O> { |
| 105 | + /** The query used to search. */ |
| 106 | + query: IndexQuery; |
| 107 | + /** All of the returned results. */ |
| 108 | + results: O[]; |
| 109 | + /** The amount of time in seconds that the search took. */ |
| 110 | + duration: number; |
| 111 | + /** The maximum revision of any document in the result, which is useful for diffing. */ |
| 112 | + revision: number; |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +`dc.useFullQuery` can otherwise be used identically to `dc.useQuery`: |
| 117 | + |
| 118 | +```jsx |
| 119 | +return function View() { |
| 120 | + // Only allow the view to update every 10000ms (aka, 10 seconds). |
| 121 | + const bookResult = dc.useFullQuery("#book and @page", { debounce: 10000 }); |
| 122 | + |
| 123 | + return <dc.Stack> |
| 124 | + <p>The search took {bookResult.duration.toFixed(2)}s to run.</p> |
| 125 | + <dc.List rows={bookResult.results} renderer={book => book.$link} /> |
| 126 | + </dc.Stack>; |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +#### `dc.useIndexUpdates()` |
| 131 | + |
| 132 | +A minimal query which just returns the current `revision` of the datacore index. The index `revision` is a monotonically increasing number |
| 133 | +which is incremented every time something in your vault changes. This call is mainly useful if you are making heavy usage of direct |
| 134 | +`dc.query` calls (which don't cause the view to refresh on their own), as it will cause the view to re-render every time something |
| 135 | +changes in your vault. |
| 136 | + |
| 137 | +```jsx |
| 138 | +return function View() { |
| 139 | + |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +Like the other hooks, `dc.useIndexUpdates` accepts an optional second parameter of configuration. |
0 commit comments