#Query Blocks

This plugin uses the concept of filters to fetch data from Todoist. To create a query block, insert a code block like the following in any note:

```todoist
filter: "today | overdue"
```

This query will fetch all tasks that are due either today or are overdue and will render them in place of this code block.

#Options

The query is defined as YAML and there are a number of options available.

#filter

The filter option is required and should be a valid Todoist filter. Note that this must be the content of the filter, you cannot refer to a filter that already exists in your Todoist account.

There are a few unsupported filters, these are tracked in this GitHub issue:

• Wildcard filters do not work as expected. E.g. - @*ball
• You cannot combine multiple filters with commas. E.g. - today | overdue, p1

This field also supports replacements:

• {{filename}} will be replaced with the current note's name, without the .md extension.

#completedTasks

Set completedTasks to true to include completed tasks alongside active tasks. It defaults to false, so existing query blocks continue to show active tasks only.

The initial refresh loads the newest three-month window. Each Todoist request asks for up to 200 completed tasks, and the plugin follows next_cursor until that entire window has loaded.

Completed pages are added to the block's saved query cache. The next time you open the note, the previously loaded history appears immediately while the newest tasks refresh in the background.

Completed tasks use the same filter as active tasks. Todoist supports many, but not all, filter expressions for completed tasks; an unsupported expression will produce the same invalid-filter error as other Todoist queries.

Completed tasks are rendered with a checked, read-only checkbox. They continue to support the query's grouping, sorting, and metadata options.

For example:

```todoist
filter: "##Computer Networks"
groupBy: "section"
completedTasks: true
```

#name

If you want to have an embedded header rendered with your query, you can use the name option. This will render a <h4> element above your tasks.

For example:

```todoist
name: "Today & Overdue"
filter: "today | overdue"
```

#autorefresh

The autorefresh option allows you to specify the number of seconds between automatic refreshes. This takes precedence over the plugin level setting. Omitting this option means the query will follow the plugin level settings.

For example:

```todoist
filter: "today | overdue"
autorefresh: 120
```

#sorting

The sorting property allows you to specify the ordering for how your tasks are rendered. This is specified as a list, where we sort in the order of the properties in the list. The possible values are:

• alphabetical or alphabeticalAscending: sorts tasks alphabetically by name (A→Z, case-insensitive)
• alphabeticalDescending: sorts tasks alphabetically by name (Z→A, case-insensitive)
• date or dateAscending: sorts tasks in ascending order based on due date
• dateDescending: sorts tasks in descending order based on due date
• priority or priorityAscending: sorting tasks in ascending order based on priority
• priorityDescending: sorts tasks in descending order based on priority
• order: sorts task according to the ordering defined in Todoist
• dateAdded or dateAddedAscending: sorts tasks in ascending order based on the date the task was added
• dateAddedDescending: sorts tasks in descending order based on the date the task was added
• deadline or deadlineAscending: sorts tasks in ascending order based on the deadline
• deadlineDescending: sorts tasks in descending order based on the deadline

If no sorting option is provided, tasks will be sorted by their Todoist order.

For example:

```todoist
filter: "today | overdue"
sorting:
    - date
    - priority
```

You can also sort tasks alphabetically:

```todoist
filter: "#work"
sorting:
    - priority
    - alphabetical
```

#groupBy

The groupBy property controls how tasks are grouped when they are rendered. If omitted, there will be no grouping. The possible values are:

• project: group by project, using the project order as in Todoist
• section: group by project and section, using the project and section order as in Todoist
• due or date: group by due date, all overdue tasks are grouped and shown together
• labels: group by the task labels, all unlabelled tasks are grouped together
• priority group by task priority, priorities are shown in high-low order

For example:

```todoist
filter: "today | overdue"
groupBy: project
```

#show

The show property controls which elements of the task metadata to render. If omitted, all task metadata will be rendered.

The possible values are:

• due or date: render the due date of the task
• time: render only the time component of the due date of the task (the end date will be shown if the task duration spans days)
• deadline: render the deadline of the task
• description: render the description of the task
• project: render the project (and section, if applicable) of the task
• section: render only the section name of the task (if the task has a section)
• labels: render the labels of the task

For example:

```todoist
filter: "today | overdue"
show:
    - due
    - project
```

You can also set this to none to hide all task metadata.

For example:

```todoist
filter: "today | overdue"
show: none
```

#view

The view objects allows you to configure how the query results are displayed.

#noTasksMessage

The noTasksMessage property allows you to customize the message displayed when a query returns no tasks. If not specified, the default message will be shown.

For example:

```todoist
filter: "today"
view:
  noTasksMessage: "Nothing due today! Take a break."
```

#hideNoTasks

The hideNoTasks property allows you to completely hide the query output when no tasks are returned. When set to true, nothing will be rendered if the query returns no tasks, rather than showing a message.

For example:

```todoist
filter: "#work & today"
view:
  hideNoTasks: true
```