| description |
|---|
A generic and flexible way to automatically list large sets of items |
👁️ PREVIEW
Takes a list of data, filters it, loops through it, and displays each item with some component.
{%
include list.html
data="citations"
component="citation"
filter="category == 'featured'"
style="rich"
%}| Parameter | Description |
|---|---|
data | The set of items to loop through, e.g. citations, posts, members, etc. If your list has date fields, it is also sorted from newest to oldest, and grouped into sections by year. |
component | The component to show for each item in the list. The fields in your data should match what this component takes as parameters (except for style, see below). |
filter | Filter your data by arbitrary fields and values. See detailed explanation below. |
style | A style parameter to automatically pass to every component in the list, so you don't have to repetitively set it on every data item. This is the only field that works this way, because all other fields are likely to be different for each item, but you usually want the style to be the same within a list. |
Technically you can use any structure of data and any component with the list component, but by default, the template comes with a few placeholder data lists and matching components for common needs.
{% hint style="info" %} New syntax, v1.3.0+ {% endhint %}
The filter parameter offers a flexible way to filter the items displayed by the list component. It can be any valid Ruby expression. For each item, if the expression is true, the item is shown; otherwise, it is hidden.
Your expression can get/check any field on any item in any data list. Simply refer to a field by its name, but in snake_case format (anything not a letter replaced with a _). You can also get a field by its unmodified name from item (a hash). If the expression references something that isn't a field on the item, it will treat it as nil (null).
For example, if your data looked like this:
# ... previous item
# current item filter is looking at
- id: abc
Some-Field-123: xxx
# ... another item
- id: def
Some-Field-123: yyy
optional-field: Lorem ipsum...you could make references in your filter="" like this:
# snake_cased field name
Some_Field
# exact original field name
item['Some-Field-123']
# field perhaps present on other items, but not present on this item
optional_field # treated as `nil` (null)| Filter expression | Show item if... | Example scenario |
|---|---|---|
repo | has some repo field | "Show my tools that have a repo link" |
!id | has no id field | "Show my manual citations" |
type == 'package' and category != 'featured' | type is package and category is not featured | "Show my secondary packages" |
role =~ /student/i | role contains student, case-insensitive | "Show my students, of any level" |
role =~ /^Senior/ | role starts with Senior, case-sensitive | "Show my senior level members" |
date.between?('2020', '2023') | date is between 2020 and 2023 | "Show my papers published during COVID" |
publisher.end_with?('Biology') | publisher ends with Biology | "Show my papers in major biology journals" |
alumni ? name === 'Steve McQueen' : true | not alumni , or alumni where name is Steve McQueen | "Hide my past members, unless they're super cool" |
{% hint style="info" %} References:
Ruby string functions {% endhint %}
Experiment with more advanced expressions:
{% hint style="danger" %} Old syntax, < v1.3.0 {% endhint %}
The filters parameter is a comma separated list of field/value filters, like field: value, field: value, field: value. An item is considered a match only if all of the filters match.
The field is the particular field/key of the data item to check. The value is the value to compare against. value can be:
- A plain string for a partial match.
- Blank to match unspecified fields.
- Ruby-flavored regex string for more complex matching.
| Filter string | Show items that have... |
|---|---|
role: programmer, alumni: true |
role containing programmer AND alumni containing true |
affiliation: ^CU$ |
affiliation EXACTLY equal to CU |
category: |
no specified category |
description: .+ |
some specified/defined description |
date: ^2020 |
date starting with 2020 |
role: ^(?!pi$) |
role NOT equal to pi |