search

mabeyj / trilium-collection-views

An extension for Trilium Notes that implements different ways of viewing collections of notes.
MIT License
77 stars 5 forks source link

readme

Collection Views

An extension for Trilium Notes that implements different ways of viewing collections of notes.

Table of contents

Screenshots

Board view

Board view screenshot

Gallery view

Gallery view screenshot

Table view

Table view screenshot

Requirements

Minimum Trilium version supported: v0.46

Installation

  1. Download collection-views.zip from the Releases page.

  2. Import collection-views.zip into your tree: right-click a parent note, then select "Import into note".

  3. Reload the frontend (Menu → Advanced → Reload Frontend).

Upgrading

  1. Download and extract collection-views.zip from the Releases page.

  2. Replace the css and js child notes of the Collection Views note with the updated files found in the zip archive:

    • Select the css child note, click "Upload new revision", and select the Collection Views/css.css file that was extracted.
    • Select the js child note, click "Upload new revision", and select the Collection Views/js.js file that was extracted.

  3. Reload the frontend (Menu → Advanced → Reload Frontend).

Usage

  1. Create a note that will render a view:

    • Type: Render Note
    • Add a renderNote relation targeting the Collection Views note.

  2. Add a query label to the Render Note with a search query as its value. This will be executed by Trilium's search engine, and the resulting notes will be displayed in the view.

  3. Optionally, add a view label to the Render Note to select which type of view to use. By default, the table view will be used.

  4. Optionally, add labels to the Render Note to configure the view.

Configuration

Render Note attributes

Views are configured by adding labels to the Render Note.

view

Selects which view to use. Possible values:

Example: #view=board

query

A search query that will be executed using Trilium's search engine. The notes returned by this search are the notes that will be included in the view.

The following tokens may be used inside of a search query. Tokens are replaced with attributes of the Render Note prior to executing the search.

When a token is replaced, the value will be surrounded by double quotes ("value").

Examples:

groupBy

Determines the columns of a board view. The value of this label has the same format described in attribute settings.

Columns are sorted by the specified attribute. Custom sorting is supported.

Most attribute settings are supported for formatting the values displayed in column headers.

Examples:

sort

Sorts notes in the view. The value of this label is a comma-separated list of names of attributes, properties, or attributes of related notes. Names can be prefixed with ! to sort values in descending order.

Values are sorted alphabetically and case-insensitively.

Notes are sorted by their titles last, and this is the default sort when no sorting is specified. Custom sorting is supported.

Example: #sort="type,!price" would sort notes by their type values first, then by price (in reverse order), then by their titles.

columns

Sets the number of columns in a gallery view.

Example: #columns=8

columnWidth

Sets the width of a board view's columns in pixels.

Example: #columnWidth=100

coverHeight

Sets the height of card cover images in pixels. Setting this to 0 hides cover images.

Example: #coverHeight=500

attribute

Configures which attributes will be displayed in the view and how they should be formatted.

By default, attribute values will be shown as plain text. For labels, the label's value will be shown. For relations, the titles of target notes will be shown.

Attribute settings control how the attribute's values are formatted.

Attribute settings

Labels that support attribute settings (#attribute and #groupBy) have a value that is a comma-separated list.

The first item in the list is a name of an attribute, a property, or a related note's attribute.

Any remaining items in the list are settings (described in the following sections) either in the form of a flag (settingName) or a key/value pair (settingName=value).

Note properties

There are some special attribute names (prefixed with $) which refer to a note's properties instead of user-defined attributes.

The following properties are treated as a label with a single value:

Date properties are in RFC 3339 format (YYYY-MM-DD hh:mm:ss.sssZ) and use UTC for the time zone.

Example: #attribute=$dateModified

Attributes of related notes

Instead of an attribute name, you can specify a "path" that refers to an attribute of a related note. This allows for using attributes of notes that are targeted by a note's relations.

A path consists of one or more names separated by a period (.). The last name in the path must be an attribute name or a property name. All other names in the path must be relation names.

Examples:

align

Sets the text alignment of cells in the attribute's column. This can by any CSS text-align value such as center or right.

Example: #attribute="price,align=right"

badge

Renders this attribute's value as a badge.

Badge colors can be customized in two ways:

Example: #attribute="status,badge"

badgeBackground

Sets the background style of badges for this attribute. Any CSS background style can be set. If set, the badge setting is implicitly enabled.

If this attribute is a relation, notes targeted by this relation can set the badgeBackground attribute to override this style. See custom badge colors.

Example: #attribute="status,badgeBackground=red"

badgeColor

Sets the font color of badges for this attribute. Any CSS color can be set. If set, the badge setting is implicitly enabled.

If this attribute is a relation, notes targeted by this relation can set the badgeColor attribute to override this style. See custom badge colors.

Example: #attribute="status,badgeColor=black"

boolean

Renders the attribute's value as a checkbox.

The checkbox will be checked unless the attribute's value is one of the following (case-insensitive):

If the attribute's value is empty, the checkbox will also be checked.

Example: #attribute="done,boolean"

header

Sets the text displayed in the header cell of the attribute's column.

Examples:

number

Formats the attribute's value as a number (inserting thousands separators).

Example: #attribute="price,number"

prefix

Adds a string in front of the attribute's value.

Examples:

precision

Sets the number of digits displayed after the decimal point when the attribute's value is formatted as a number. If set, the number setting is implicitly enabled.

Example: #attribute="price,precision=2"

progressBar

Renders a progress bar. The attribute's value will be the numerator. The value of this setting refers to the attribute whose value will be used as the denominator. It can be the name of an attribute, a property, or a related note's attribute.

Both attributes must be labels with numeric values.

Example: #attribute="completed,progressBar=total" — For a note having the attributes #completed=5 #total=10, this would display a progress bar that is 50% full.

repeat

Renders the value as a string repeated depending on the attribute's numeric value.

Example: #attribute="rating,repeat=⭐"

separator

Sets the string inserted between values when an attribute has multiple values. This can be one of the following values:

Or, it can be a custom separator. If this setting is not set to one of the above values, then the setting's value will be inserted as is between values.

Examples:

suffix

Adds a string behind the attribute's value.

Examples:

truncate

Truncates long text to some number of lines. If set as a flag, text is truncated to a single line. Otherwise, the setting's value specifies how many lines. If set, the wrap setting is implicitly enabled.

Examples:

width

Sets the minimum width (in pixels) of the attribute's column. Columns may be resized proportionally since tables are set to 100% width.

Example: #attribute=status,width=100

wrap

Toggles text wrapping. If enabled, long text in a column will wrap to multiple lines. For tables that scroll horizontally, setting a width will avoid text getting squashed into a very thin column.

Example: #attribute=description,wrap

Escape sequences

Escape sequences in setting values begin with a backtick (`). The following escape sequences are supported:

Since settings are separated by a comma, the most common use for escape sequences is for escaping a comma so that it can be used literally in a setting that accepts arbitrary text.

Example: #attribute=position,header=X`,Y would display a header containing the text "X,Y".

Covers

The board and gallery views display an optional cover image for each note.

Custom badge colors

When an attribute is a relation, its badge colors can be customized by adding certain labels to the note targeted by the relation:

Screenshot showing these labels defined and the result.

Custom sorting

Custom sorting is achieved by defining a sortableTitle label on a note. When notes are sorted by their titles, their sortableTitle is used for comparison if it is defined, otherwise their actual title is used.

This is useful in a couple ways:

Including views in notes

Views can be included in text notes using the Include Note feature.

Screenshot showing a view included in a note and the Include Note feature in the editor toolbar.

CSS variables

The following variables can be changed by themes or custom CSS:

body {
  --collection-view-margin: 10px;
  --collection-view-table-border-color: #bfbfbf;
}
Name Description
--collection-view-margin Outermost margin applied to all views.
--collection-view-table-border-color Table border-color for table views.