fix(docs): update calendar view documentation

This commit is contained in:
Elian Doran 2025-03-15 19:44:15 +02:00
parent 00106580ca
commit 36fa0af706
No known key found for this signature in database
2 changed files with 271 additions and 249 deletions

View File

@ -52,18 +52,22 @@ For each note of the calendar, the following attributes can be used:
| `#calendar:color` | Similar to `#color`, but applies the color only for the event in the calendar and not for other places such as the note tree. | | `#calendar:color` | Similar to `#color`, but applies the color only for the event in the calendar and not for other places such as the note tree. |
| `#iconClass` | If present, the icon of the note will be displayed to the left of the event title. | | `#iconClass` | If present, the icon of the note will be displayed to the left of the event title. |
| `#calendar:title` | Changes the title of an event to point to an attribute of the note other than the title, either a label (e.g. `#assignee`) or a relation (e.g. `~for`). See _Advanced use-cases_ for more information. | | `#calendar:title` | Changes the title of an event to point to an attribute of the note other than the title, either a label (e.g. `#assignee`) or a relation (e.g. `~for`). See _Advanced use-cases_ for more information. |
| `#calendar:promotedAttributes` | Allows displaying the value of one or more promoted attributes in the calendar like this: ![](13_Calendar%20View_image.png) <br> <br>`<br>#label:weight="promoted,number,single,precision=1"<br>#label:mood="promoted,alias=Mood,single,text"<br>#calendar:promotedAttributes="label:weight,label:mood" <br>` <br> <br>It can also be used with relations, case in which it will display the title of the target note: <br> <br>`<br>#relation:assignee="promoted,alias=Assignee,single,text"<br>#calendar:promotedAttributes="relation:assignee" <br>~assignee=@My assignee<br>` | | `#calendar:displayedAttributes` | Allows displaying the value of one or more attributes in the calendar like this: <br><br>![](13_Calendar%20View_image.png)<br><br>```<br>#weight="70"<br>#Mood="Good"<br>#calendar:displayedAttributes="weight,Mood"<br>```<br><br>It can also be used with relations, case in which it will display the title of the target note:<br><br>```<br>~assignee=@My assignee<br>#calendar:displayedAttributes="assignee"<br>``` |
| `#calendar:startDate` | Allows using a different label to represent the start date, other than `#startDate` (e.g. `#expiryDate`). The label name must be prefixed with `#`. If the label is not defined for a note, the default will be used instead. | | `#calendar:startDate` | Allows using a different label to represent the start date, other than `startDate` (e.g. `expiryDate`). The label name **must not be** prefixed with `#`. If the label is not defined for a note, the default will be used instead. |
| `#calendar:endDate` | Allows using a different label to represent the start date, other than `#endDate`. The label name must be prefixed with `#`. If the label is not defined for a note, the default will be used instead. | | `#calendar:endDate` | Allows using a different label to represent the start date, other than `endDate`. The label name **must not be** prefixed with `#`. If the label is not defined for a note, the default will be used instead. |
## How the calendar works ## How the calendar works
![](17_Calendar%20View_image.png)The calendar displays all the child notes of the book that have a `#startDate`. An `#endDate` can optionally be added. ![](17_Calendar%20View_image.png)
The calendar displays all the child notes of the book that have a `#startDate`. An `#endDate` can optionally be added.
If editing the start date and end date from the note itself is desirable, the following attributes can be added to the book note: If editing the start date and end date from the note itself is desirable, the following attributes can be added to the book note:
``` ```
#viewType=calendar #label:startDate(inheritable)="promoted,alias=Start Date,single,date" #label:endDate(inheritable)="promoted,alias=End Date,single,date" #hidePromotedAttributes #viewType=calendar #label:startDate(inheritable)="promoted,alias=Start Date,single,date"
#label:endDate(inheritable)="promoted,alias=End Date,single,date"
#hidePromotedAttributes
``` ```
This will result in: This will result in:

View File

@ -21,34 +21,36 @@
<p>Unlike other Book view types, the Calendar view also allows some kind <p>Unlike other Book view types, the Calendar view also allows some kind
of interaction, such as moving events around as well as creating new ones.</p> of interaction, such as moving events around as well as creating new ones.</p>
<h2>Creating a calendar</h2> <h2>Creating a calendar</h2>
<table> <figure class="table">
<thead> <table>
<tr> <thead>
<th></th> <tr>
<th></th> <th>&nbsp;</th>
<th></th> <th>&nbsp;</th>
</tr> <th>&nbsp;</th>
</thead> </tr>
<tbody> </thead>
<tr> <tbody>
<td>1</td> <tr>
<td> <td>1</td>
<img src="3_Calendar View_image.png" alt=""> <td>
</td> <img src="3_Calendar View_image.png" alt="">
<td>The Calendar View works only for Book note types. To create a new note, </td>
right click on the note tree on the left and select Insert note after, <td>The Calendar View works only for Book note types. To create a new note,
or Insert child note and then select <em>Book</em>.</td> right click on the note tree on the left and select Insert note after,
</tr> or Insert child note and then select <em>Book</em>.</td>
<tr> </tr>
<td>2</td> <tr>
<td> <td>2</td>
<img src="5_Calendar View_image.png" alt=""> <td>
</td> <img src="5_Calendar View_image.png" alt="">
<td>Once created, the “View type” of the Book needs changed to “Calendar”, </td>
by selecting the “Book Properties” tab in the ribbon.</td> <td>Once created, the “View type” of the Book needs changed to “Calendar”,
</tr> by selecting the “Book Properties” tab in the ribbon.</td>
</tbody> </tr>
</table> </tbody>
</table>
</figure>
<h2>Creating a new event/note</h2> <h2>Creating a new event/note</h2>
<ul> <ul>
<li>Clicking on a day will create a new child note and assign it to that particular <li>Clicking on a day will create a new child note and assign it to that particular
@ -81,226 +83,242 @@
</ul> </ul>
<h2>Configuring the calendar</h2> <h2>Configuring the calendar</h2>
<p>The following attributes can be added to the book type:</p> <p>The following attributes can be added to the book type:</p>
<table> <figure class="table">
<thead> <table>
<tr> <thead>
<th>Name</th> <tr>
<th>Description</th> <th>Name</th>
</tr> <th>Description</th>
</thead> </tr>
<tbody> </thead>
<tr> <tbody>
<td><code>#calendar:hideWeekends</code> <tr>
</td> <td><code>#calendar:hideWeekends</code>
<td>When present (regardless of value), it will hide Saturday and Sundays </td>
from the calendar.</td> <td>When present (regardless of value), it will hide Saturday and Sundays
</tr> from the calendar.</td>
<tr> </tr>
<td><code>#calendar:weekNumbers</code> <tr>
</td> <td><code>#calendar:weekNumbers</code>
<td>When present (regardless of value), it will show the number of the week </td>
on the calendar.</td> <td>When present (regardless of value), it will show the number of the week
</tr> on the calendar.</td>
<tr> </tr>
<td><code>~child:template</code> <tr>
</td> <td><code>~child:template</code>
<td>Defines the template for newly created notes in the calendar (via dragging </td>
or clicking).</td> <td>Defines the template for newly created notes in the calendar (via dragging
</tr> or clicking).</td>
</tbody> </tr>
</table> </tbody>
</table>
</figure>
<p>In addition, the first day of the week can be either Sunday or Monday <p>In addition, the first day of the week can be either Sunday or Monday
and can be adjusted from the application settings.</p> and can be adjusted from the application settings.</p>
<h2>Configuring the calendar events</h2> <h2>Configuring the calendar events</h2>
<p>For each note of the calendar, the following attributes can be used:</p> <p>For each note of the calendar, the following attributes can be used:</p>
<table> <figure
<thead> class="table">
<tr> <table>
<th>Name</th> <thead>
<th>Description</th> <tr>
</tr> <th>Name</th>
</thead> <th>Description</th>
<tbody> </tr>
<tr> </thead>
<td><code>#startDate</code> <tbody>
</td> <tr>
<td>The date the event starts, which will display it in the calendar. The <td><code>#startDate</code>
format is <code>YYYY-MM-DD</code> (year, month and day separated by a minus </td>
sign).</td> <td>The date the event starts, which will display it in the calendar. The
</tr> format is <code>YYYY-MM-DD</code> (year, month and day separated by a minus
<tr> sign).</td>
<td><code>#endDate</code> </tr>
</td> <tr>
<td>Similar to <code>startDate</code>, mentions the end date if the event spans <td><code>#endDate</code>
across multiple days. The date is inclusive, so the end day is also considered. </td>
The attribute can be missing for single-day events.</td> <td>Similar to <code>startDate</code>, mentions the end date if the event spans
</tr> across multiple days. The date is inclusive, so the end day is also considered.
<tr> The attribute can be missing for single-day events.</td>
<td><code>#color</code> </tr>
</td> <tr>
<td>Displays the event with a specified color (named such as <code>red</code>, <code>gray</code> or <td><code>#color</code>
hex such as <code>#FF0000</code>). This will also change the color of the </td>
note in other places such as the note tree.</td> <td>Displays the event with a specified color (named such as <code>red</code>, <code>gray</code> or
</tr> hex such as <code>#FF0000</code>). This will also change the color of the
<tr> note in other places such as the note tree.</td>
<td><code>#calendar:color</code> </tr>
</td> <tr>
<td>Similar to <code>#color</code>, but applies the color only for the event <td><code>#calendar:color</code>
in the calendar and not for other places such as the note tree.</td> </td>
</tr> <td>Similar to <code>#color</code>, but applies the color only for the event
<tr> in the calendar and not for other places such as the note tree.</td>
<td><code>#iconClass</code> </tr>
</td> <tr>
<td>If present, the icon of the note will be displayed to the left of the <td><code>#iconClass</code>
event title.</td> </td>
</tr> <td>If present, the icon of the note will be displayed to the left of the
<tr> event title.</td>
<td><code>#calendar:title</code> </tr>
</td> <tr>
<td>Changes the title of an event to point to an attribute of the note other <td><code>#calendar:title</code>
than the title, either a label (e.g. <code>#assignee</code>) or a relation </td>
(e.g. <code>~for</code>). See <em>Advanced use-cases</em> for more information.</td> <td>Changes the title of an event to point to an attribute of the note other
</tr> than the title, either a label (e.g. <code>#assignee</code>) or a relation
<tr> (e.g. <code>~for</code>). See <em>Advanced use-cases</em> for more information.</td>
<td><code>#calendar:promotedAttributes</code> </tr>
</td> <tr>
<td>Allows displaying the value of one or more promoted attributes in the <td><code>#calendar:displayedAttributes</code>
calendar like this: </td>
<img src="13_Calendar View_image.png" alt=""> <td>
<br> <p>Allows displaying the value of one or more attributes in the calendar
<br><code>&lt;br&gt;#label:weight="promoted,number,single,precision=1"&lt;br&gt;#label:mood="promoted,alias=Mood,single,text"&lt;br&gt;#calendar:promotedAttributes="label:weight,label:mood" &lt;br&gt;</code> like this:&nbsp;</p>
<br> <p>
<br>It can also be used with relations, case in which it will display the <img src="13_Calendar View_image.png" alt="">
title of the target note: </p><pre><code class="language-text-x-trilium-auto">#weight="70"
<br> #Mood="Good"
<br><code>&lt;br&gt;#relation:assignee="promoted,alias=Assignee,single,text"&lt;br&gt;#calendar:promotedAttributes="relation:assignee" &lt;br&gt;~assignee=@My assignee&lt;br&gt;</code> #calendar:displayedAttributes="weight,Mood"</code></pre>
</td> <p>It can also be used with relations, case in which it will display the
</tr> title of the target note:</p><pre><code class="language-text-x-trilium-auto">~assignee=@My assignee
<tr> #calendar:displayedAttributes="assignee"</code></pre>
<td><code>#calendar:startDate</code> </td>
</td> </tr>
<td>Allows using a different label to represent the start date, other than <code>#startDate</code> (e.g. <code>#expiryDate</code>). <tr>
The label name must be prefixed with <code>#</code>. If the label is not <td><code>#calendar:startDate</code>
defined for a note, the default will be used instead.</td> </td>
</tr> <td>Allows using a different label to represent the start date, other than <code>startDate</code> (e.g. <code>expiryDate</code>).
<tr> The label name <strong>must not be</strong> prefixed with <code>#</code>.
<td><code>#calendar:endDate</code> If the label is not defined for a note, the default will be used instead.</td>
</td> </tr>
<td>Allows using a different label to represent the start date, other than <code>#endDate</code>. <tr>
The label name must be prefixed with <code>#</code>. If the label is not <td><code>#calendar:endDate</code>
defined for a note, the default will be used instead.</td> </td>
</tr> <td>Allows using a different label to represent the start date, other than <code>endDate</code>.
</tbody> The label name <strong>must not be</strong> prefixed with <code>#</code>.
</table> If the label is not defined for a note, the default will be used instead.</td>
<h2>How the calendar works</h2> </tr>
<p> </tbody>
<img src="17_Calendar View_image.png" alt="">The calendar displays all the child notes of the book that have a <code>#startDate</code>. </table>
An <code>#endDate</code> can optionally be added.</p> </figure>
<p>If editing the start date and end date from the note itself is desirable, <h2>How the calendar works</h2>
the following attributes can be added to the book note:</p><pre><code class="language-text-x-trilium-auto">#viewType=calendar #label:startDate(inheritable)="promoted,alias=Start Date,single,date" #label:endDate(inheritable)="promoted,alias=End Date,single,date" #hidePromotedAttributes </code></pre> <p>
<p>This will result in:</p> <img src="17_Calendar View_image.png" alt="">
<p> </p>
<img src="14_Calendar View_image.png" alt=""> <p>The calendar displays all the child notes of the book that have a <code>#startDate</code>.
</p> An <code>#endDate</code> can optionally be added.</p>
<p>When not used in a Journal, the calendar is recursive. That is, it will <p>If editing the start date and end date from the note itself is desirable,
look for events not just in its child notes but also in the children of the following attributes can be added to the book note:</p><pre><code class="language-text-x-trilium-auto">#viewType=calendar #label:startDate(inheritable)="promoted,alias=Start Date,single,date"
these child notes.</p> #label:endDate(inheritable)="promoted,alias=End Date,single,date"
<h2>Use-cases</h2> #hidePromotedAttributes </code></pre>
<h3>Using with the Journal / calendar</h3> <p>This will result in:</p>
<p>It is possible to integrate the calendar view into the Journal with day <p>
notes. In order to do so change the note type of the Journal note (calendar <img src="14_Calendar View_image.png" alt="">
root) to Book and then select the Calendar View.</p> </p>
<p>Based on the <code>#calendarRoot</code> (or <code>#workspaceCalendarRoot</code>) <p>When not used in a Journal, the calendar is recursive. That is, it will
attribute, the calendar will know that it's in a calendar and apply the look for events not just in its child notes but also in the children of
following:</p> these child notes.</p>
<ul> <h2>Use-cases</h2>
<li>The calendar events are now rendered based on their <code>dateNote</code> attribute <h3>Using with the Journal / calendar</h3>
rather than <code>startDate</code>.</li> <p>It is possible to integrate the calendar view into the Journal with day
<li>Interactive editing such as dragging over an empty era or resizing an notes. In order to do so change the note type of the Journal note (calendar
event is no longer possible.</li> root) to Book and then select the Calendar View.</p>
<li>Clicking on the empty space on a date will automatically open that day's <p>Based on the <code>#calendarRoot</code> (or <code>#workspaceCalendarRoot</code>)
note or create it if it does not exist.</li> attribute, the calendar will know that it's in a calendar and apply the
<li>Direct children of a day note will be displayed on the calendar despite following:</p>
not having a <code>dateNote</code> attribute. Children of the child notes <ul>
will not be displayed.</li> <li>The calendar events are now rendered based on their <code>dateNote</code> attribute
</ul> rather than <code>startDate</code>.</li>
<p> <li>Interactive editing such as dragging over an empty era or resizing an
<img src="12_Calendar View_image.png" alt=""> event is no longer possible.</li>
</p> <li>Clicking on the empty space on a date will automatically open that day's
<h3>Using a different attribute as event title</h3> note or create it if it does not exist.</li>
<p>By default, events are displayed on the calendar by their note title. <li>Direct children of a day note will be displayed on the calendar despite
However, it is possible to configure a different attribute to be displayed not having a <code>dateNote</code> attribute. Children of the child notes
instead.</p> will not be displayed.</li>
<p>To do so, assign <code>#calendar:title</code> to the child note (not the </ul>
calendar/book note), with the value being <code>#name</code> where <code>name</code> can <p>
be any label. The attribute can also come through inheritance such as a <img src="12_Calendar View_image.png" alt="">
template attribute. If the note does not have the requested label, the </p>
title of the note will be used instead.</p> <h3>Using a different attribute as event title</h3>
<table> <p>By default, events are displayed on the calendar by their note title.
<thead> However, it is possible to configure a different attribute to be displayed
<tr> instead.</p>
<th></th> <p>To do so, assign <code>#calendar:title</code> to the child note (not the
<th></th> calendar/book note), with the value being <code>#name</code> where <code>name</code> can
</tr> be any label. The attribute can also come through inheritance such as a
</thead> template attribute. If the note does not have the requested label, the
<tbody> title of the note will be used instead.</p>
<tr> <figure class="table">
<td> <table>
<img src="7_Calendar View_image.png" alt=""> <thead>
</td> <tr>
<td> <th>&nbsp;</th>
<img src="9_Calendar View_image.png" alt=""> <th>&nbsp;</th>
</td> </tr>
</tr> </thead>
</tbody> <tbody>
</table> <tr>
<h3>Using a relation attribute as event title</h3> <td>
<p>Similarly to using an attribute, use <code>#calendar:title</code> and set <img src="7_Calendar View_image.png" alt="">
it to <code>~name</code> where <code>name</code> is the name of the relation </td>
to use.</p> <td>
<p>Moreover, if there are more relations of the same name, they will be displayed <img src="9_Calendar View_image.png" alt="">
as multiple events coming from the same note.</p> </td>
<table> </tr>
<thead> </tbody>
<tr> </table>
<th></th> </figure>
<th></th> <h3>Using a relation attribute as event title</h3>
</tr> <p>Similarly to using an attribute, use <code>#calendar:title</code> and set
</thead> it to <code>~name</code> where <code>name</code> is the name of the relation
<tbody> to use.</p>
<tr> <p>Moreover, if there are more relations of the same name, they will be displayed
<td> as multiple events coming from the same note.</p>
<img src="8_Calendar View_image.png" alt=""> <figure class="table">
</td> <table>
<td> <thead>
<img src="10_Calendar View_image.png" alt=""> <tr>
</td> <th>&nbsp;</th>
</tr> <th>&nbsp;</th>
</tbody> </tr>
</table> </thead>
<p>Note that it's even possible to have a <code>#calendar:title</code> on the <tbody>
target note (e.g. “John Smith”) which will try to render an attribute of <tr>
it. Note that it's not possible to use a relation here as well for safety <td>
reasons (an accidental recursion  of attributes could cause the application <img src="8_Calendar View_image.png" alt="">
to loop infinitely).</p> </td>
<table> <td>
<thead> <img src="10_Calendar View_image.png" alt="">
<tr> </td>
<th></th> </tr>
<th></th> </tbody>
</tr> </table>
</thead> </figure>
<tbody> <p>Note that it's even possible to have a <code>#calendar:title</code> on the
<tr> target note (e.g. “John Smith”) which will try to render an attribute of
<td> it. Note that it's not possible to use a relation here as well for safety
<img src="15_Calendar View_image.png" alt=""> reasons (an accidental recursion &nbsp;of attributes could cause the application
</td> to loop infinitely).</p>
<td> <figure class="table">
<img src="2_Calendar View_image.png" alt=""> <table>
</td> <thead>
</tr> <tr>
</tbody> <th>&nbsp;</th>
</table> <th>&nbsp;</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<img src="15_Calendar View_image.png" alt="">
</td>
<td>
<img src="2_Calendar View_image.png" alt="">
</td>
</tr>
</tbody>
</table>
</figure>
</div> </div>
</div> </div>
</body> </body>