### Quickstart: Basic List View

Source: https://blacksmithgu.github.io/datacore/code-views/list

A quickstart example for `dc.List` demonstrating fetching data with `dc.useQuery` and rendering it using a simple `renderer` function that returns the book's link.

```javascript
return function View() {
    // Start by fetching your data via a query.
    const data = dc.useQuery("#book and @page");

    // Pass the full data to `rows`, and specify what to show in the list via `renderer`:
    return <dc.List rows={data} renderer={book => book.$link} />;
}
```

--------------------------------

### Quickstart: List View for Embeds

Source: https://blacksmithgu.github.io/datacore/code-views/list

A quickstart example for `dc.List` showing how to render embeds with paging enabled. It fetches blocks using `dc.useQuery` and uses `dc.embed` as the renderer.

```javascript
return function View() {
    const data = dc.useQuery("#important-note and @block");

    // Uses `dc.embed` to render an embed of all of the given blocks, with paging for performnace.
    return <dc.List rows={data} paging={true} renderer={dc.embed} />;
}
```

--------------------------------

### Create a Table View with Datacore JSX

Source: https://blacksmithgu.github.io/datacore/quickstart

This snippet shows how to create a Datacore view that displays queried pages in a table format. It defines the columns for the table and uses `dc.useQuery` to fetch pages matching a specific tag (e.g., '#game'). The built-in `dc.Table` component is used for rendering.

```jsx
// A list of columns to show in the table.
const COLUMNS = [
    { id: "Name", value: page => page.$link },
    { id: "Rating", value: page => page.value("rating") }
];

return function View() {
    // Selecting `#game` pages, for example.
    const pages = dc.useQuery("@page and #game");

    // Uses the built in table component for showing objects in a table!
    return <dc.Table columns={COLUMNS} rows={pages} />;
}
```

--------------------------------

### Display Page Count with Datacore JSX

Source: https://blacksmithgu.github.io/datacore/quickstart

This snippet demonstrates how to create a simple Datacore view that displays the total number of markdown pages in your Obsidian vault. It utilizes the `dc.useQuery` hook to fetch page data and returns a React component to render the count.

```jsx
return function View() {
    const pages = dc.useQuery("@page").length;

    return <p>You have {pages} pages in your vault!</p>;
}
```

--------------------------------

### Querying Datablocks by Type

Source: https://blacksmithgu.github.io/datacore/data/blocks

Shows a Datacore query example to filter datablocks based on a specific field and value, demonstrating how to target structured data like exercise logs.

```text
@datablock and type = "exercise"
```

--------------------------------

### Datacore Processing Data with useMemo

Source: https://blacksmithgu.github.io/datacore/code-views

Demonstrates processing fetched data using `dc.useMemo()` for memoization. This example fetches all pages tagged '#game', then constructs a histogram of games based on their 'rating' metadata. The results are displayed in an unordered list.

```jsx
return function View() {
    // Fetch all pages tagged #game.
    const games = dc.useQuery("#game and @page");

    // We want to manually construct a histogram of games by the rating we gave them.
    const ratingBuckets = dc.useMemo(() => {
        const ratings = {};
        for (const game of games) {
            if (!game.value("rating")) continue;

            // Convert all ratings to strings since who knows what people put in metadata these days.
            const rating = game.value("rating") + "";
            ratings[rating] = (ratings[rating] ?? 0) + 1;
        }

        return ratings;
    }, [games]);

    // Then show those buckets!
    return (
        <ul>
            {Object.keys(ratingBuckets).map(rating => (
                <li>Rating {rating}: {ratingBuckets[rating] ?? 0} entries.</li>
            ))}
        </ul>
    );
}
```

--------------------------------

### Markdown Frontmatter Example

Source: https://blacksmithgu.github.io/datacore/data

A standard markdown frontmatter block used to define metadata properties for a page. These properties are then indexed by Datacore.

```markdown
---
length: 35 hours
rating: 10
time-played: 2013-06-10
---
# Dark Souls

#game, #game/hard

The game that eventually lead to [[Dark Souls 2]] and [[Elden Ring]]!
```

--------------------------------

### Basic dc.Table Usage with Rows and Columns

Source: https://blacksmithgu.github.io/datacore/code-views/table

Demonstrates the fundamental setup of a dc.Table, requiring data ('rows') and column definitions ('columns'). Each column needs an 'id' and a 'value' function to extract data from a row. It also shows how to fetch data using dc.useQuery.

```javascript
const COLUMNS = [
    {
        // A unique ID which identifies this specific column.
        id: "link",
        // The value to show in the column.
        value: (row) => row.$link
    },
    { id: "Rating", value: (row) => row.value("rating") },
    { id: "Genre", value: (row) => row.value("genre") }
]

return function View() {
    // Start by fetching your data via a query.
    const data = dc.useQuery("#book and @page");

    // Pass the full data to `rows`, along with your columns.
    return <dc.Table rows={data} columns={COLUMNS} />;
}
```

--------------------------------

### JSON Codeblock Example

Source: https://blacksmithgu.github.io/datacore/data/blocks

Demonstrates a JSON codeblock defined using markdown backticks. It shows how to specify languages and the content position within the block.

```json
{ "a codeblock": "with some stuff in it" }
```

--------------------------------

### Install Datacore API via npm/Yarn

Source: https://blacksmithgu.github.io/datacore/index

This section shows how to add the Datacore API typings to your project using either Yarn or npm. This is useful for Obsidian plugins that need to interoperate with Datacore.

```shell
# Yarn:  
yarn add @blacksmithgu/datacore
```

```shell
# npm:  
npm install @blacksmithgu/datacore
```

--------------------------------

### Datacore Fetching Data with useQuery

Source: https://blacksmithgu.github.io/datacore/code-views

Illustrates how to fetch data using the `dc.useQuery()` hook. This hook takes a Datacore query string and returns an array of matching objects. The example displays the count of games matching the query '#game and @page and rating > 7'.

```jsx
return function View() {
    const games = dc.useQuery("#game and @page and rating > 7");
    return <p>You have written about {games.length} games!</p>;
}
```

--------------------------------

### List Item Example

Source: https://blacksmithgu.github.io/datacore/data/blocks

Demonstrates the structure of a list item in Datacore, which can be a regular list item or a task. List items have properties like $type, $position, $line, and can contain sub-items.

```markdown
- Regular list item.
- Another regular list item.
    - A sublist item.
```

--------------------------------

### Combining Grouping and Hierarchies in Datacore List

Source: https://blacksmithgu.github.io/datacore/code-views/list

This advanced example combines grouping and hierarchical display in a Datacore List. It groups books by genre and recursively displays linked pages/sections for each book, limiting the child depth to one level.

```javascript
// Finds all things linked to book that themselves can be linked to.
function findLinked(book) {
	return dc.query(`[[${book.$path}]] and $types.econtains("linkable")`);
}

return function View() {
    // Groups both by
    const books = dc.useQuery("@page and #book");
    const groupedBooks = dc.useArray(books, array => array.groupBy(book => book.value("genre") ?? "No Genre"));

    return <dc.List rows={groupedBooks} renderer={(book) => book.$link} maxChildDepth={1} childSource={findLinked} />;
}
```

--------------------------------

### Nested Lists for Hierarchies in Datacore

Source: https://blacksmithgu.github.io/datacore/code-views/list

This example demonstrates creating hierarchical lists in Datacore by leveraging the default behavior of rendering sublists from '$children' and 'children' properties. It displays top-level items with their nested subitems.

```javascript
const DATA = [
    {
        title: "Hello",
        children: [
            { title: "One" },
            { title: "Two" },
            { title: "Three" }
        ]
    },
    {
        title: "Goodbye",
        children: [
            { title: "Four" },
            { title: "Five" },
            { title: "Six" }
        ]
    }
];

return function View() {
    return <dc.List rows={DATA} renderer={item => item.title} />;
}
```

--------------------------------

### Finding Pages with Specific Sections

Source: https://blacksmithgu.github.io/datacore/data/query

Identifies pages that contain sections with the exact name 'Daily'. This example utilizes the `parentof()` function to locate pages containing sections that match the specified criteria.

```javascript
// Find pages which have `Daily` sections.  
@page and parentof(@section and $name = "Daily")  
```

--------------------------------

### Custom Group Rendering with 'groupings' in Datacore List

Source: https://blacksmithgu.github.io/datacore/code-views/list

This example shows how to customize the rendering of group headers in a Datacore List using the 'groupings' prop. It converts each genre key into a file link, adding embellishments to the default text rendering.

```javascript
return function View() {
    // Fetch all books and then group them by genre.
    const books = dc.useQuery("#book and @page");
    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));

    // Render each grouping key as a file link instead of just text.
    return <dc.List rows={booksByGenre} renderer={book => book.$link} groupings={(key) => dc.fileLink(key)} />;
}
```

--------------------------------

### Paragraph Block Example

Source: https://blacksmithgu.github.io/datacore/data/blocks

Illustrates a paragraph block in Datacore, which consists of a contiguous set of text lines. Empty lines are used to separate distinct paragraphs.

```markdown
A contiguous set of text lines
is considered a paragraph.

An empty line splits the text up
into two separate paragraphs.
```

--------------------------------

### Markdown Page Metadata Example

Source: https://blacksmithgu.github.io/datacore/data

Illustrates the structure of metadata for a simple markdown page as stored in the Datacore index. It shows intrinsic fields like '$name', '$path', '$tags', '$links', '$types', and '$frontmatter' derived from the markdown content.

```json
{
    "$name": "Dark Souls",
    "$path": "games/Dark Souls.md",
    "$tags": ["#game", "#game/hard"],
    "$links": [{ "path": "games/Dark Souls 2.md" }, { "path": "games/Elden Ring.md" }],
    "$types": ["page", "markdown", "file", "taggable", "linkable"],
    "$frontmatter": {
        "length": "35 hours",
        "rating": 10,
        "time-played": "2013-06-10"
    },
    "/** ... many more fields ... */"
}
```

--------------------------------

### Map Arrays to Create Lists in JSX

Source: https://blacksmithgu.github.io/datacore/code-views

Explains how to use the `map` function on arrays within JSX to dynamically generate lists. This example creates an ordered list from an array of numbers.

```javascript
return function View() {  
    const data = [1, 2, 3, 4];  
  
    return <ol>  
        {data.map(index => (  
            <li>{index}</li>  
        ))}  
    </ol>;  
}  

```

--------------------------------

### YAML Frontmatter Block Example

Source: https://blacksmithgu.github.io/datacore/data/blocks

Shows a YAML block, typically used for frontmatter in markdown files. This data is stored directly in the page as $frontmatter and does not have additional block-specific metadata.

```yaml
---
key: value
key2: value2
---
```

--------------------------------

### Filtering Sections by Name

Source: https://blacksmithgu.github.io/datacore/data/query

Filters for sections where the name is not equal to 'Daily' and sections whose names contain the substring 'Daily'. These examples demonstrate string comparison and containment checks within section names.

```javascript
// Find all sections which have a name NOT equal to 'Daily'.  
@section and $name != "Daily"  

// Find all sections whose name contains `Daily`.  
@section and $name.contains("Daily")  
```

--------------------------------

### Task List Item Example

Source: https://blacksmithgu.github.io/datacore/data/blocks

Illustrates task list items within Datacore. These are a type of list item with additional fields like $status and $completed, indicating their state (e.g., completed, uncompleted, questionable).

```markdown
- [ ] An uncompleted task.
- [?] A questionable task.
    - [X] A completed task.
```

--------------------------------

### Link Creation and Embedding in Datacore

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Covers the `link()` constructor for creating links to pages and the `embed()` function for converting links into embedded objects, such as images or other Datacore views. Includes postfix examples.

```Datacore Expression
link("Hello") // => link to page named 'Hello'
link("Hello", "Goodbye") // => link to page named 'Hello', displays as 'Goodbye'

// Postfix style:
"Hello".link() // => link to page named 'Hello'

embed(link("Hello.png")) // => embedded link to the "Hello.png" image, which will render as an actual image.

// Postfix style:
link("Hello.png").embed()
```

--------------------------------

### Custom Grouping Header Rendering in Datacore Table

Source: https://blacksmithgu.github.io/datacore/code-views/table

Shows how to customize the rendering of grouping headers in a Datacore Table by using the `groupings` prop with a function. This example converts genre keys into file links.

```javascript
const COLUMNS = [
    { id: "link", value: (row) => row.$link },
    { id: "Rating", value: (row) => row.value("rating") },
    { id: "Genre", value: (row) => row.value("genre") }
]

return function View() {
    // Fetch all books and then group them by genre.
    const books = dc.useQuery("#book and @page");
    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));

    // Assigns `groupings` to render the grouping headers using custom logic.
    return <dc.Table rows={booksByGenre} columns={COLUMNS} groupings={(key) => dc.fileLink(key)} />;
}
```

--------------------------------

### YAML Datablock Definition and Query

Source: https://blacksmithgu.github.io/datacore/data/blocks

Illustrates the definition of a datablock using 'yaml:data' annotation and provides examples of how to query datablocks and access their specific field values using Datacore's query language.

```javascript
// Fetch all datablocks which have a 'rating' field.
const datablocks = dc.query("@datablock and exists(rating)");

// Fetch data specifically from the values in the datablock.
datablocks[0].value("rating")
```

```yaml
key: value
key2: value2
```

```yaml
type: exercise
date: 2025-01-10
lifts:
    squat: 240
```

--------------------------------

### Get Link Path

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Extracts the file path portion from a link. This excludes any subpath information, such as headings or block IDs.

```Datacore
meta([[My Project]]).path = "My Project"  
meta([[My Project#Next Actions]]).path = "My Project"  
meta([[My Project#^9bcbe8]]).path = "My Project"  
```

--------------------------------

### Duration Parsing in Datacore

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Details the `dur()` function in Datacore for parsing durations from strings or other duration values. Includes examples of direct and postfix usage.

```Datacore Expression
dur(8 minutes) // = <8 minutes>
dur("8 minutes, 4 seconds") // = <8 minutes, 4 seconds>
dur(dur(8 minutes)) // = dur(8 minutes) = <8 minutes>

// Postfix style:
"8 minutes, 4 seconds".dur() // = <8 minutes, 4 seconds>
```

--------------------------------

### Object Creation in Datacore

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Shows how to create objects in Datacore using the `object()` constructor and object literal syntax. Covers creating empty objects and objects with key-value pairs.

```Datacore Expression
object() // => empty object
object("a", 6) // => object which maps "a" to 6
object("a", 4, "c", "yes") // => object which maps a to 4, and c to "yes"

{} // => empty object
{ a: 6 } // => object which maps "a" to 6
{ a: 4, c: "yes" } // => a => 4, and c => "yes"
```

--------------------------------

### Get Link Display Text

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Retrieves the explicitly defined display text for a link. If the link does not have custom display text (e.g., `[[Date|Display Text]]`), it returns null.

```Datacore
meta([[2021-11-01|Displayed link text]]).display = "Displayed link text"  
meta([[2021-11-01]]).display = null  
```

--------------------------------

### Get Link Metadata Object

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Retrieves an object containing metadata associated with a given link. This allows access to properties of the link itself, rather than the content of the linked file.

```Datacore
meta(link)

```

--------------------------------

### List Creation in Datacore

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Demonstrates creating lists in Datacore using the `list()` constructor, its alias `array()`, and list literal syntax. Covers creating empty lists and lists with elements.

```Datacore Expression
list() // => empty list
list(1, 2, 3) // => list with 1, 2, and 3
array("a", "b", "c") // => list with "a", "b", and "c"

[] // => empty list
[1, 2, 3] // => list with 1, 2, and 3
```

--------------------------------

### Get the number of elements in a list or fields in an object

Source: https://blacksmithgu.github.io/datacore/expressions/functions

The `length` function returns the count of elements in a list or the count of fields in an object. It supports both prefix and postfix styles.

```javascript
length([])
length([1, 2, 3])
length({"hello": 1, "goodbye": 2})
[1, 2, 3].length()
```

--------------------------------

### Find Minimum Value

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Computes the minimum value from a list of arguments or an array. Can handle both numbers and strings. Example: min([1, 2, 3]) returns 1.

```JavaScript
min(1, 2, 3) // = 1
min([1, 2, 3]) // = 1

min("a", "ab", "abc") // = "a"
```

--------------------------------

### Using Datacore Queries in React and Plugins

Source: https://blacksmithgu.github.io/datacore/data/query

Demonstrates how to use Datacore's query functions within a React component for live updates or in a plugin context for single-time execution. The `useQuery` hook automatically updates results, while `query` executes once.

```javascript
// Inside of a react component, watch the results of a query live. Automatically updates  
// whenever the query results change.  
const pages = dc.useQuery("@page");  
  
// In a plugin context or in more advanced usage, you can run a query a single time with `query`.  
const pages = dc.query("@page and rating > 9");  
```

--------------------------------

### Ceiling Number to Integer

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Rounds a number up to the smallest integer greater than or equal to it. Negative numbers become less negative. For example, ceil(-0.837764) results in 0.

```JavaScript
ceil(12.937) // = 13
ceil(-93.33333) // = -93
ceil(-0.837764) // = 0
```

--------------------------------

### Get Link Subpath

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Retrieves the subpath of a link, which can be a heading title or a block ID. If the link points directly to a file without a specific heading or block, this property will be null.

```Datacore
meta([[My Project#Next Actions]]).subpath = "Next Actions"  
meta([[My Project#^9bcbe8]]).subpath = "9bcbe8"  
meta([[My Project]]).subpath = null  
```

--------------------------------

### Basic Function Usage and Postfix Style in Datacore

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Demonstrates how to use Datacore functions with arguments and in a postfix style for chaining operations. This covers string manipulation functions like 'lower' and 'replace'.

```Datacore Expression
lower("YES") // -> "yes"
replace("yes", "e", "a") // -> "yas"

"YES".lower() // Same as lower("YES")
"YES".lower().replace("e", "a") // Same as replace(lower("YES"), "e", "a")
```

--------------------------------

### Get Object Type

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Returns the data type of any given object as a string. Useful for conditional logic based on data types. Supports various primitive and complex types.

```JavaScript
typeof(8) // => "number"
typof("text") // => "string"
typof([1, 2, 3]) // => "array"
typof({ a: 1, b: 2 }) // => "object"
typof(date(2020-01-01)) // => "date"
typof(dur(8 minutes)) // => "duration"
```

--------------------------------

### DataArray Indexing and Swizzling

Source: https://blacksmithgu.github.io/datacore/code-views/data-array

Explains and demonstrates Datacore's DataArray indexing and swizzling capabilities. It shows how to access elements using standard array indexing and how to use query-language-style swizzling to extract specific fields, automatically mapping and flattening nested arrays.

```javascript
const data = dc.array(dc.query("#books and @page"));

data.$name // => List of all book names.
data.$ctime // => List of all book created times.

```

--------------------------------

### Use Full Query Hook

Source: https://blacksmithgu.github.io/datacore/code-views/local-api

Illustrates the `dc.useFullQuery()` hook, a variant of `useQuery` that returns a comprehensive search result object including query details, results, duration, and revision. It also supports debounce configuration.

```javascript
export interface SearchResult<O> {
    /** The query used to search. */
    query: IndexQuery;
    /** All of the returned results. */
    results: O[];
    /** The amount of time in seconds that the search took. */
    duration: number;
    /** The maximum revision of any document in the result, which is useful for diffing. */
    revision: number;
}
```

```javascript
return function View() {
    // Only allow the view to update every 10000ms (aka, 10 seconds).
    const bookResult = dc.useFullQuery("#book and @page", { debounce: 10000 });

    return <dc.Stack>
        <p>The search took {bookResult.duration.toFixed(2)}s to run.</p>
        <dc.List rows={bookResult.results} renderer={book => book.$link} />
    </dc.Stack>;
}
```

--------------------------------

### Extract Substring

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Extracts a portion of a string starting from a specified index and ending at another index, or the end of the string if the end index is omitted. This function is available in prefix and postfix styles.

```datacore
substring("hello", 0, 2) = "he"
substring("hello", 2, 4) = "ll"
substring("hello", 2) = "llo"
substring("hello", 0) = "hello"

// Postfix style.
"hello".substring(0, 2) = "he"
```

--------------------------------

### Truncate Number Decimal

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Removes the decimal part of a number, effectively truncating it to the nearest integer towards zero. For example, trunc(12.937) results in 12, and trunc(-93.33333) results in -93.

```JavaScript
trunc(12.937) // = 12
trunc(-93.33333) // = -93
trunc(-0.837764) // = 0
```

--------------------------------

### Date Parsing in Datacore

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Explains how to parse dates in Datacore using the `date()` constructor with different input types (string, date, link) and formats. Also shows the postfix style for date parsing.

```Datacore Expression
date("2020-04-18") // = <date object representing April 18th, 2020>
date([[2021-04-16]]) // = <date object for the given page, referring to file.day>

// Postfix style:
"2020-04-18".date()

date("12/31/2022", "MM/dd/yyyy") // => DateTime for December 31th, 2022
date("210313", "yyMMdd") // => DateTime for March 13th, 2021
date("946778645000", "x") // => DateTime for "2000-01-02T03:04:05"

// Postfix style:
"210313".date("yyMMdd") // = DateTime for March 13th, 2021
```

--------------------------------

### Round Number to Digits

Source: https://blacksmithgu.github.io/datacore/expressions/functions

Rounds a given number to a specified number of decimal places. If no digits are specified, it rounds to the nearest whole number. Example: round(16.555555, 2) results in 16.56.

```JavaScript
round(16.555555) // = 17
round(16.555555, 2) // = 16.56
```

--------------------------------

### List View with Paging Enabled

Source: https://blacksmithgu.github.io/datacore/code-views/list

Shows how to enable pagination for `dc.List` using the `paging` prop. It can be set to `true` for default page size or a specific number for a custom page size.

```javascript
// Enable paging, with the page size equal to your default page size in the Datacore settings.
<dc.List paging={true} ... />

// Enable paging with the specific page size.
<dc.List paging={10} ... />
```

--------------------------------

### List View with Custom Renderer

Source: https://blacksmithgu.github.io/datacore/code-views/list

Explains how to use the `renderer` prop in `dc.List` to customize how each item is displayed. It maps query results (e.g., book objects) to their specific link property.

```javascript
return function View() {
    // This will give back a set of MarkdownPage objects, which are not useful to render on their own.
    const books = dc.useQuery("#book and @page");

    // Render books by rendering their links.
    return <dc.List rows={books} renderer={book => book.$link} />;
}
```

--------------------------------

### Basic List View with Rows

Source: https://blacksmithgu.github.io/datacore/code-views/list

Demonstrates the fundamental usage of `dc.List` by providing a simple array of strings to the `rows` prop. This creates a basic unordered list.

```javascript
const ITEMS = ["First", "Second", "Third"];

return function View() {
    return <dc.List rows={ITEMS} />;
}
```

--------------------------------

### Execute JavaScript in JSX Interpolation

Source: https://blacksmithgu.github.io/datacore/code-views

Illustrates running arbitrary JavaScript within interpolated blocks in JSX. This example extracts the first character of the current file's name using `substring()`.

```javascript
return function View() {  
    const data = dc.useCurrentFile();  
  
    return <p>The first character is {data.$name.substring(0, 1)}!</p>  
}  

```

--------------------------------

### Basic Datacore Codeblock Structure

Source: https://blacksmithgu.github.io/datacore/code-views/local-api

Demonstrates the fundamental structure of a Datacore codeblock using React. It shows how to define a functional component and utilize the 'dc' API for data querying and rendering.

```datacorejsx
return function View() {
    // Call functions on the datacore API, 'dc'.
    const data = dc.useQuery("#book");

    // And then return a view, possibly using more datacore API calls.
    return <dc.List rows={data} renderer={book => book.$link} />;
}
```

--------------------------------

### Use Query Hook

Source: https://blacksmithgu.github.io/datacore/code-views/local-api

Demonstrates the `dc.useQuery()` hook for querying data using the Datacore query language. It returns a list of results and can be configured with a debounce interval to control update frequency.

```javascript
return function View() {
    const books = dc.useQuery("#book and @page");

    return <dc.List rows={books} renderer={book => book.$link} />;
}
```

```javascript
return function View() {
    // Only allow the view to update every 10000ms (aka, 10 seconds).
    const books = dc.useQuery("#book and @page", { debounce: 10000 });

    return <dc.List rows={books} renderer={book => book.$link} />;
}
```

--------------------------------

### Extract a portion of an array - Datacore

Source: https://blacksmithgu.github.io/datacore/expressions/functions

The `slice` function returns a shallow copy of a portion of an array. It takes a start index and an optional end index. Negative indices count from the end of the array. Supports postfix notation.

```Datacore
slice([1, 2, 3, 4, 5], 3)
slice(["ant", "bison", "camel", "duck", "elephant"], 0, 2)
slice([1, 2, 3, 4, 5], -2)
slice(someArray)

// Postfix style.
[1, 2, 3, 4, 5].slice(-2)
```

--------------------------------

### Configuring Paging in dc.Table

Source: https://blacksmithgu.github.io/datacore/code-views/table

Illustrates how to enable and configure paging for a dc.Table using the 'paging' prop. It can be disabled, enabled with default settings, or set to a specific page size.

```javascript
// Explicitly disable paging.
<dc.Table paging={false} ... />

// Enable paging, with the page size equal to your default page size in the Datacore settings.
<dc.Table paging={true} ... />

// Enable paging with the specific page size.
<dc.Table paging={10} ... />
```

--------------------------------

### Accessing Fields with Javascript

Source: https://blacksmithgu.github.io/datacore/data/fields

Explains how to use the 'fields' API in Javascript to access frontmatter and inline fields efficiently. Supports loading metadata via `fields()`, `field(name)`, and `value(name)` methods.

```APIDOC
## Accessing Fields with Javascript

### Description
Most Datacore Javascript types support the 'fields' API for accessing frontmatter and inline fields. This API allows efficient loading of metadata.

### Method
- `fields()`
- `field(name)`
- `value(name)`

### Endpoint
N/A (Javascript API)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```javascript
// Load the 'rating' field from the current page.
dc.currentFile().value("rating")

// Get the raw, unparsed value of a field from frontmatter.
dc.currentFile().field("complex-date").raw
```

### Response
#### Success Response (200)
- **Field Object** (`fields()` or `field(name)`): 
  - `key` (string) - The canonical key name for the field.
  - `value` (Literal) - The value of the field.
  - `raw` (string, optional) - The raw value of the field before parsing.
  - `provenance` (Provenance, optional) - Describes where the field came from.
- **Literal** (`value(name)`): The value of the field.

#### Response Example
```json
// Example for page.field("rating")
{
  "key": "Rating",
  "value": 7,
  "raw": "7"
}

// Example for page.value("rating")
7
```
```

--------------------------------

### Link Utilities

Source: https://blacksmithgu.github.io/datacore/code-views/local-api

Utilities for creating and manipulating Datacore links, including resolving paths and creating links to files, headers, and blocks.

```APIDOC
## Link Utilities

### `dc.resolvePath(path, [sourcePath])`

#### Description
Resolves a local or absolute path to an absolute path, optionally from a given source path.

#### Method
GET (conceptual)

#### Endpoint
N/A (function call)

#### Parameters
- **path** (string) - The path to resolve.
- **sourcePath** (string) - Optional. The source path to resolve from.

#### Response Example
```javascript
// Can resolve by file name.
dc.resolvePath("Test") // returns "location/To/Test.md"

// Can resolve from an alternative source path.
dc.resolvePath("Test", "utils/Index.md") // returns "utils/Test.md"

// If it cannot find the file, returns the input path unchanged.
dc.resolvePath("noexist") // returns "noexist"
```

### `dc.fileLink(path)`

#### Description
Creates a Datacore `Link` from a path to a file.

#### Method
GET (conceptual)

#### Endpoint
N/A (function call)

#### Parameters
- **path** (string) - The path to the file.

#### Response Example
```javascript
dc.fileLink("Test.md") // returns Link object representing [[Test]]
```

### `dc.headerLink(filePath, header)`

#### Description
Creates a Datacore `Link` pointing to a header in a file.

#### Method
GET (conceptual)

#### Endpoint
N/A (function call)

#### Parameters
- **filePath** (string) - The path to the file.
- **header** (string) - The header name.

#### Response Example
```javascript
dc.headerLink("Terraria.md", "Review") // returns Link object representing [[Terraria#Review]]
```

### `dc.blockLink(filePath, blockId)`

#### Description
Creates a Datacore `Link` pointing to a specific block in a file.

#### Method
GET (conceptual)

#### Endpoint
N/A (function call)

#### Parameters
- **filePath** (string) - The path to the file.
- **blockId** (string) - The block ID.

#### Response Example
```javascript
dc.blockLink("Daily Thoughts.md", "38ha12d") // returns Link object representing [[Daily Thoughts#^38ha12d]]
```

### `dc.parseLink(linkString)`

#### Description
Parses a full link into a Datacore `Link`. Throws an error if the syntax is malformed.

#### Method
GET (conceptual)

#### Endpoint
N/A (function call)

#### Parameters
- **linkString** (string) - The link string to parse.

#### Response Example
```javascript
dc.parseLink("[[Test]]") // returns Link object representing [[Test]]
// dc.parseLink("[malformed]") // throws an exception
```

### `dc.tryParseLink(linkString)`

#### Description
Returns a Datacore `Result` containing the result of trying to parse a string link.

#### Method
GET (conceptual)

#### Endpoint
N/A (function call)

#### Parameters
- **linkString** (string) - The link string to parse.

#### Response Example
```json
{
  "successful": true,
  "value": "[[Test]]"
}
```
```json
{
  "successful": false,
  "error": "malformed input..."
}
```
```

--------------------------------

### Render Basic HTML with JSX

Source: https://blacksmithgu.github.io/datacore/code-views

Demonstrates how to output arbitrary HTML using Javascript JSX syntax for rendering paragraphs. This is a fundamental way to structure your views in Datacore.

```javascript
return function View() {  
    return <div>  
        <p>Hello!</p>  
        <p>Goodbye!</p>  
    </div>;  
}  

```

--------------------------------

### Explicit Grouping Configuration with 'groupings' in Datacore List

Source: https://blacksmithgu.github.io/datacore/code-views/list

This snippet illustrates creating an explicit `GroupingConfig` object to define how group keys are rendered. The `LINK_GROUPING` configuration specifies rendering each group key as a file link, which is then passed to the 'groupings' prop.

```javascript
const LINK_GROUPING = {
    render: (key, rows) => dc.fileLink(key)
};

return function View() {
    // Fetch all books and then group them by genre.
    const books = dc.useQuery("#book and @page");
    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));

    // Render each grouping key as a file link instead of just text.
    return <dc.List rows={booksByGenre} renderer={book => book.$link} groupings={LINK_GROUPING} />;
}
```

--------------------------------

### Datacore Fetching File Metadata

Source: https://blacksmithgu.github.io/datacore/code-views

Shows how to retrieve file metadata using `dc.useFile()` and `dc.useCurrentFile()`. `dc.useCurrentFile()` fetches metadata for the currently active file, while `dc.useFile()` fetches metadata for a file at a specified path. Both hooks update the view automatically when the file content changes.

```jsx
return function View() {
    // Returns full page metadata for the current file, and updates the view whenever the current
    // file changes.
    const current = dc.useCurrentFile();

    // Returns file metadata for a file at a specific path.
    const other = dc.useFile("secret/data.md");

    return <p>You are on {current.$path}; you are loading from {other.$path}.</p>;
}
```

--------------------------------

### ListState Interface

Source: https://blacksmithgu.github.io/datacore/code-views/list

Defines the properties available for configuring a Datacore list.

```APIDOC
## ListState Interface

### Description
This interface defines the full set of available properties for configuring the Datacore list component.

### Method
N/A (Interface Definition)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

### Properties
- **type** (string) - Optional - Specifies the list display type: 'ordered', 'unordered', or 'block'. Block lists render contiguous divs without list elements.
- **rows** (Grouping<T>) - Required - The complete collection of elements within the list.
- **groupings** (GroupingConfig<T> | GroupingConfig<T>[] | ((key: Literal, rows: Grouping<T>) => Literal | VNode)) - Optional - Allows overriding grouping header lines with custom rendering or logic.
- **renderer** ((row: T) => React.ReactNode | Literal) - Optional - A custom render function for each leaf element, capable of producing JSX or a plain literal value.
- **paging** (boolean | number) - Optional - Enables paging. If true, uses the default page size. If a number, sets a custom page size.
- **scrollOnPaging** (boolean | number) - Optional - Controls automatic scrolling to the top on page changes. If true, always scrolls. If a number, scrolls only if it exceeds the current page size.
- **maxChildDepth** (number) - Optional - Maximum level of children to render. A value of 0 disables child expansion.
- **childSource** (null | string | string[] | ((row: T) => T[])) - Optional - Property name, list of names, or function to extract children. Defaults to '$children' and 'children'. If null, child extraction is disabled. If undefined, uses the default.
```

--------------------------------

### Controlling Hierarchy Depth with 'maxChildDepth' in Datacore List

Source: https://blacksmithgu.github.io/datacore/code-views/list

This example demonstrates how to limit the display depth of nested lists in Datacore using the 'maxChildDepth' prop. Setting this prop to '2' ensures that only up to two levels of children are rendered.

```javascript
return function View() {
    // Show only at most two levels of children.
    return <dc.List rows={...} childSource={"items"} maxChildDepth={2} ... />;
}
```

--------------------------------

### Get Link Type with meta()

Source: https://blacksmithgu.github.io/datacore/expressions/functions

The `meta(link).type` function returns the type of a given link. It can identify if a link points to an entire file, a header within a file, or a specific block within a file. This is useful for understanding the scope of a linked resource.

```datacore
meta([[My Project]]).type = "file"
meta([[My Project#Next Actions]]).type = "header"
meta([[My Project#^9bcbe8]]).type = "block"
```

--------------------------------

### Create DataArray directly with dc.array

Source: https://blacksmithgu.github.io/datacore/code-views/data-array

Shows how to directly create a `DataArray` using the `dc.array` utility function. It also illustrates chaining operations like `map` and `limit` on the `DataArray` and converting it back to a regular array using the `.array()` method.

```javascript
return function View() {
    // da is a `DataArray`.
    const da = dc.array([1, 2, 3]);
    // da2 is still a `DataArray`.
    const da2 = da.map(x => x + 4).limit(2);

    // To get a regular array back, use `.array()`.
    const data = da2.array();
}

```

--------------------------------

### Group Data by Genre in Datacore Table

Source: https://blacksmithgu.github.io/datacore/code-views/table

Demonstrates how to fetch book data and group it by genre using Data Array syntax for rendering in a Datacore Table. No extra configuration is needed for default group rendering.

```javascript
const COLUMNS = [
    { id: "link", value: (row) => row.$link },
    { id: "Rating", value: (row) => row.value("rating") },
    { id: "Genre", value: (row) => row.value("genre") }
]

return function View() {
    // Fetch all books and then group them by genre.
    const books = dc.useQuery("#book and @page");
    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));

    // No extra configuration is required by default to show groups.
    return <dc.Table rows={booksByGenre} columns={COLUMNS} />;
}
```

--------------------------------

### Accessing Fields with JavaScript API

Source: https://blacksmithgu.github.io/datacore/data/fields

Shows how to use the Datacore JavaScript 'fields' API to load metadata from the current file. It covers methods for loading all fields, a specific field by name, and just the value of a field.

```javascript
// Load the 'rating' field from the current page.
dc.currentFile().value("rating")

// Get the raw, unparsed value of a field from frontmatter.
dc.currentFile().field("complex-date").raw
```

--------------------------------

### Group Data by Genre in Datacore List

Source: https://blacksmithgu.github.io/datacore/code-views/list

This snippet demonstrates how to fetch books and group them by genre using Data Array syntax. The grouped data is then rendered in a Datacore List. No special configuration is needed for default group rendering.

```javascript
return function View() {
    // Fetch all books and then group them by genre.
    const books = dc.useQuery("#book and @page");
    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));

    // No extra configuration is required by default to show groups.
    return <dc.List rows={booksByGenre} renderer={book => book.$link} />;
}
```

--------------------------------

### Get Detailed Query Results with `dc.fullquery`

Source: https://blacksmithgu.github.io/datacore/code-views/local-api

The `dc.fullquery` function executes a query against the Datacore index and returns the results along with additional metadata. This metadata includes the parsed query, the actual results, the query execution duration, and the index revision at the time of execution. It does not automatically trigger view updates.

```javascript
dc.fullquery("@page") // => {
    // Parsed query representation.
    query: { type: "type", type: "page" },
    // Actual results, like you would get from `dc.query`.
    results: [/* list of pages */],
    // Query runtime in seconds, accurate to the millisecond.
    duration: 0.01,
    // Index revision the query was executed against.
    revision: 317,
}
```