List

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.

Filter

New syntax, v1.3.0+

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)

Examples

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"

References:

/Regex/

Ruby string functions

Experiment with more advanced expressions:

TryRuby playground

Filters

Old syntax, < v1.3.0

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.

Examples

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