# List :eye: [PREVIEW](https://greenelab.github.io/lab-website-template/testbed#list) Takes a list of data, filters it, loops through it, and displays each item with some component. ```liquid {% 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](https://greene-lab.gitbook.io/lab-website-template-docs/advanced/custom-components) 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](https://greene-lab.gitbook.io/lab-website-template-docs/repo-structure#data-and-components). ## Filter {% 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](https://www.google.com/search?q=ruby+playground). 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: ```yaml # ... 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: ```ruby # 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"

{% hint style="info" %} References: [/Regex/](https://en.wikipedia.org/wiki/Regular_expression) [Ruby string functions](https://ruby-doc.org/3.2.2/String.html#class-String-label-Methods+for+Querying) {% endhint %} Experiment with more advanced expressions: {% embed url="" %} ## Filters {% 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](https://docs.ruby-lang.org/en/master/Regexp.html) 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` |