> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-legacy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# TimeList Block

> The **TimeList Block** takes an array of objects with at least a date time attribute. It groups this items in time ranges sections. Default groups are "today", "last 7 days", "last 30 days" and "latest" but you can set your own sections definitions. Each item is rendered with a Workspace Block. It manages pagination if event is set. It can update or remove single item and add new ones.

[Demo](https://demo.pages.prisme.ai/en/TimeList)

## Minimal usage

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
```

This simple example emit `init my time list` event on init and wait for an `update my time list` event with items in payload. This udpate event payload needs to take a `items` array of objects.

Each item needs to have an attribute with datetime value. You can set the name of the attribute if
it's different from default one : `createdAt`, with the `dateField` attribute:

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
  dateField: updatedAt
```

Without a valid date field, nothing will be displayed.

A `templateBlock` will be also mandatory to display anything. As we can't guess the objects structures and how to use their attribute, it's impossible to propose a default display, so you have to set as `templateBlock` attribute the name of a valid Block in your Workspace:

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
  dateField: updatedAt
  templateBlock: TimeListItem
```

This block will receive an `item` object for each in the list. Read `{{item.attr}}` in your block template like:

```yaml theme={null}
# Page/Block
- slug: BlocksList
  blocks:
    - slug: RichText
      content: '{{item.firstName}}'
    - slug: RichText
      content: '{{item.lastName}}'
```

This is the very least needed to use this TimeList block.

## Advanced usage

Then, you can use additional functionnalities:

`selected` attribute set the current item selected (it adds a className). The value must be an object with at least an attribute discriminating an item. For example, to display as selected the item with `id: 12345`:

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
  dateField: updatedAt
  templateBlock: TimeListItem
  selected:
    id: 12345
```

`updateItemOn` is an event name to tell the block to update or remove a present item. The payload of the set event will take `item` and `selector` attribute and optionaly `remove`.

With:

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
  dateField: updatedAt
  templateBlock: TimeListItem
  selected:
    id: 12345
  updateItemOn: update my time list item
```

To update an item:

```yaml theme={null}
# Automation
- emit:
    event: update my time list item
    payload:
      item:
        title: updated title
      selector:
        id: 12345
```

To delete an item:

```yaml theme={null}
# Automation
- emit:
    event: update my time list item
    payload:
      item:
        title: updated title
      selector:
        id: 12345
      remove: true
```

To add a single item, juste emit the `updateOn` event with an array of your single item.

`onPagination` is an event emit when user click on next page button. It will add a `page` attribute starting from 1 to your `onPagination.payload` and incrementing after each `updateOn` trigger.

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
  dateField: updatedAt
  templateBlock: TimeListItem
  selected:
    id: 12345
  updateItemOn: update my time list item
  onPagination:
    event: init my time list
    payload:
      foo: bar
```

Clicking the "load more" button" will emit:

```yaml theme={null}
# Automation
- emit:
    event: init my time list
    payload:
      foo: bar
      page: 2 # and so long for each click
```

`loadMoreLabel` is a localized string to replace the default load more button label:

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
  dateField: updatedAt
  templateBlock: TimeListItem
  selected:
    id: 12345
  updateItemOn: update my time list item
  onPagination:
    event: init my time list
    payload:
      foo: bar
  loadMoreLabel:
    fr: Charger les plus anciens
    en: Load latest
```

`sections` replace the default time range sections. It's an array of object with a label and a timerange defined by a number and a type of duration. For example \[2, 'day'] to group the items 2 days old, or \[42, 'month'] for the 42 months old. The final section (the latest items) can have no timerange set.

```yaml theme={null}
# Page/Block
- slug: TimeList
  onInit:
    event: init my time list
    payload:
      foo: bar
  updateOn: update my time list
  dateField: updatedAt
  templateBlock: TimeListItem
  selected:
    id: 12345
  updateItemOn: update my time list item
  onPagination:
    event: init my time list
    payload:
      foo: bar
  loadMoreLabel:
    fr: Charger les plus anciens
    en: Load latest
  sections:
    - timerange:
        - 1
        - hour
      label:
        fr: Il y a une heure
        en: A hour ago
    - timerange:
        - 1
        - day
      label:
        fr: Il y a un jour
        en: A day ago
    - label:
        fr: Tout le reste
        en: Everything else
```