From 2b00f7454ba185de93bd8e300c7c6e0154f864ba Mon Sep 17 00:00:00 2001 From: kolaente Date: Wed, 30 Oct 2024 14:28:31 +0100 Subject: [PATCH] docs: explain date math when used with filters --- markdoc.config.mjs | 3 + .../partials/DateMathExamples.astro | 83 +++++++++++++++++++ src/content/docs/usage/filters.mdoc | 49 +++++++++-- 3 files changed, 126 insertions(+), 9 deletions(-) create mode 100644 src/components/partials/DateMathExamples.astro diff --git a/markdoc.config.mjs b/markdoc.config.mjs index da27fa8..0182157 100644 --- a/markdoc.config.mjs +++ b/markdoc.config.mjs @@ -23,6 +23,9 @@ export default defineMarkdocConfig({ type: {type: String}, }, }, + dateMathExamples: { + render: component('./src/components/partials/DateMathExamples.astro'), + }, configOptions: { render: component('./src/components/partials/ConfigOptions.astro'), } diff --git a/src/components/partials/DateMathExamples.astro b/src/components/partials/DateMathExamples.astro new file mode 100644 index 0000000..6ac35b6 --- /dev/null +++ b/src/components/partials/DateMathExamples.astro @@ -0,0 +1,83 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nowRight now (Oct 30, 2024, 14:26:12)
now+24hIn 24h (Oct 31, 2024, 14:26:12)
now/dToday at 00:00 (Oct 30, 2024, 00:00:00)
now/wThe beginning of this week at 00:00 (Oct 27, 2024, 00:00:00)
now/w+1wThe end of this week (Nov 3, 2024, 00:00:00)
now+30dIn 30 days (Nov 29, 2024, 00:00:00)
Oct 30, 2024, 14:26:12||+1M/d + Oct 30, 2024, 14:26:12 plus one month at 00:00 of that day (Nov 30, 2024, 00:00:00) +
+ + diff --git a/src/content/docs/usage/filters.mdoc b/src/content/docs/usage/filters.mdoc index ab8f8cc..5ac9e4e 100644 --- a/src/content/docs/usage/filters.mdoc +++ b/src/content/docs/usage/filters.mdoc @@ -31,7 +31,7 @@ The available fields for filtering include: | `created` | The time and date when the task was created. | | `updated` | The time and date when the task was updated. | -You can date math to set relative dates. Click on the date value in a query to find out more. +You can use date math to set relative dates with any date field. [See below](#date-math) for an explanation. All strings must be either single-word or enclosed in `"` or `'`. This extends to date values like `2024-03-11`. @@ -59,14 +59,45 @@ To combine multiple conditions, you can use the following logical operators: | `\|\|` | OR operator | matches if any of the conditions are true | | `(` and `)` | Parentheses | for grouping conditions | -## Examples +## Date Math + +Date Math allows you to specify relative dates which are resolved on the fly by Vikunja when applying the filter. + +Each Date Math expression starts with an anchor date, which can either be `now`, or a date string ending with `||`. + +This anchor date can optionally be followed by one or more maths expressions, for example: + +* `+1d`: Add one day +* `-1d`: Subtract one day +* `/d`: Round down to the nearest day + +These expressions are similar to the ones provided by [Grafana](https://grafana.com/docs/grafana/latest/dashboards/time-range-controls/) and [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/common-options.html#date-math). + +### Supported time units + +| | | +|-----|---------| +| `s` | Seconds | +| `m` | Minutes | +| `h` | Hours | +| `d` | Days | +| `w` | Weeks | +| `M` | Months | +| `y` | Years | + +### Example date math expressions + +{% dateMathExamples %} +{% /dateMathExamples %} + +## Filter Examples Here are some examples of filter queries: -| | | -|--------------------------------------------------------------|-------------------------------------------------------------| -| `priority = 4` | tasks with priority level 4 | -| `dueDate < now` | tasks with a due date in the past | -| `done = false && priority >= 3` | undone tasks with priority level 3 or higher | -| `assignees in user1, user2` | tasks assigned to either user1 or user2 | -| `(priority = 1 \|\| priority = 2) &&`
`dueDate <= now` | tasks with priority level 1 or 2 and a due date in the past | +| | | +|------------------------------------------------------|-------------------------------------------------------------| +| `priority = 4` | tasks with priority level 4 | +| `dueDate < now` | tasks with a due date in the past | +| `done = false && priority >= 3` | undone tasks with priority level 3 or higher | +| `assignees in user1, user2` | tasks assigned to either user1 or user2 | +| `(priority = 1 \|\| priority = 2) && dueDate <= now` | tasks with priority level 1 or 2 and a due date in the past |