# 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/~/changes/a57wjuxagDtJUR241kyt/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/~/changes/a57wjuxagDtJUR241kyt/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: "abc" # ... another item ``` You could make references in your `filter` like this: ```ruby # snake cased field name Some_Field # 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` | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://greene-lab.gitbook.io/lab-website-template-docs/~/changes/a57wjuxagDtJUR241kyt/basics/components/list.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.