> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/portals/portal-settings/datasets/connect-to-dataset.md).

# Connect to dataset

Point a list section at a dataset, and decide what visitors can do with it.

A dataset is content with no shape — rows in a table, waiting to be shown. **Connecting** is what gives it one: you point a list section at the dataset and say which rows to take, in what order, and what a visitor may do with them.

## Where this sits

The work splits across two places, and it helps to keep them straight:

| You do this                                        | Where                             | It decides                              |
| -------------------------------------------------- | --------------------------------- | --------------------------------------- |
| Define the fields, write the rows                  | **Settings → Content → Datasets** | What content exists                     |
| Point a section at the dataset, and bind its slots | The builder, on the section       | What that content looks like, and where |

The section never stores rows. It stores a **query** — *this dataset, these criteria, this order* — and runs it when the page loads. That's why an item edited in settings is live on the Portal straight away, with nothing to republish.

It also means one dataset can feed several sections at once, each asking a different question of it.

{% hint style="info" %}
Everything here assumes the dataset already has fields and at least some items. If it doesn't, build that first — the settings are all named after fields, so there's nothing to choose from until the fields exist.
{% endhint %}

## Which sections can connect

Any section built on a **list**: **Release notes**, **Blog**, **Directory**, **Agenda**, **Contact**, **Downloads** and the like. The list is the repeating part — the thing that draws one row, over and over.

## The list's toolbar

Selecting a list in the builder brings up its own row of controls, above the section's. On a dataset-connected list they are:

| Control                  | Does                                                                        |
| ------------------------ | --------------------------------------------------------------------------- |
| **+ Add item**           | Opens the connected dataset with a new-item form up — see below.            |
| **Show template**        | Reveals the row template so you can bind its slots to fields — see below.   |
| **Manage connections** ● | Opens the connect dialog. The circle is filled while the list is connected. |
| **Adjust grid** ▦        | Columns and spacing of the list itself.                                     |
| **✕**                    | Deselects the list.                                                         |

A list with no connection shows **+ Add item** in place of **Show template**, and that button adds a row to the list itself rather than opening a dataset.

## Opening the connect dialog

1. Select the list in the builder.
2. Choose **Manage connections** — the circular button on its toolbar.
3. The dialog asks **How do you want to connect list to API?** Choose **Connect to dataset**.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FhIVeHPNPTnPmwlXYlZwh%2Fimage.png?alt=media&#x26;token=e8740efa-67e2-456c-b819-ca659ef37497" alt=""><figcaption><p>The connect dialog, with the list's three possible sources down the left.</p></figcaption></figure>

The three answers down the left are the list's three sources:

| Answer                 | The list shows                           |
| ---------------------- | ---------------------------------------- |
| **None**               | The items you typed into it by hand.     |
| **Connect to DAM**     | Assets from your DAM.                    |
| **Connect to dataset** | Rows from one of this Portal's datasets. |

## Context and Criteria

Choosing **Connect to dataset** opens two tabs on the right. Fill in the first; the second is optional.

| Tab                                                                                                        | Answers                                                             |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [**Context**](https://docs.scaleflex.com/portals/portal-settings/datasets/connect-to-dataset/context.md)   | Which dataset, and how its rows are ordered, grouped and addressed. |
| [**Criteria**](https://docs.scaleflex.com/portals/portal-settings/datasets/connect-to-dataset/criteria.md) | Which rows the list shows, and what visitors may narrow it by.      |

Set them, then **Save**. **Cancel** closes without keeping anything.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FDh38b8LvsnoLHZFoey3G%2Fimage.png?alt=media&#x26;token=d725cd61-82ee-4ba0-a10f-746f9bdd2dd3" alt=""><figcaption><p><strong>Connect to dataset</strong> chosen, with the Context and Criteria tabs on the right.</p></figcaption></figure>

{% hint style="info" %}
The **Criteria** tab stays hidden until you've picked a dataset on **Context** — it has no schema to offer fields from, and an empty second tab reads as a broken one.
{% endhint %}

## Binding the row template

Connecting tells the list **which rows**. Binding tells it **what goes where** — and that's a separate job, done on the canvas rather than in the dialog.

A connected list draws every row from one **template**, and the template is hidden until you ask for it.

1. Select the list.
2. Choose **Show template** on its toolbar — its tooltip reads *Map fields to template placeholders*.
3. The template appears in place of the rows. Click on it and its **Content settings** dialog opens.
4. Set what that slot reads, and **Save**.
5. Choose **Hide template** to go back to the rows.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FdeV1qr1kyRiu4AmaCQud%2Fimage.png?alt=media&#x26;token=b20ba5ff-32f8-4153-ae8e-dc7b6a2a4117" alt=""><figcaption><p>The row template on the canvas, opened with <strong>Show template</strong>.</p></figcaption></figure>

While the template is open the button reads **Hide template** and its tooltip becomes *Update template configuration*.

### Content settings

One dialog per slot, and it decides both what the slot says and how it looks:

| Setting            | What it does                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Content source** | **From field** reads the value from each row. **Static text** keeps one value for every row.                                    |
| **Content**        | Which dataset field this slot reads. Only shown for **From field**.                                                             |
| **Format**         | How that value is written out — see below. Only shown for fields that have something to format.                                 |
| **Font size**      | The text level the slot renders at — *Heading 4*, a paragraph level, and so on.                                                 |
| **Line clamps**    | Caps the slot at **1 line**, **2 lines** and so on, or **None** for no cap. Keeps rows even when the content doesn't cooperate. |
| **Value colors**   | For a choice field, a colour per option — so a status or product label is coloured by its value.                                |

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FPAdZ2MAYrFsDkHOeK21r%2Fimage.png?alt=media&#x26;token=54acccf7-f160-41c1-9521-4d4bfd62ba9b" alt="" width="352"><figcaption><p>The <strong>Content settings</strong> dialog for one slot of the template.</p></figcaption></figure>

Choosing **Static text** replaces the field picker with a note: *This text is the same on every row and stays editable directly on the canvas.* That's the point of it — a fixed caption or an eyebrow that doesn't vary gets typed in place rather than set here.

**Line clamps** is the setting people miss. A dataset row's body copy is whatever someone typed, so without a clamp one long entry stretches its card and breaks the grid. Two lines is usually enough to tell entries apart.

#### Format

A value arrives from the dataset as it was stored — a date as a timestamp, a multiple-choice field as a list, a yes/no as a flag. **Format** decides how it reads on the page.

What you can choose depends on what the field holds, which is why the field picker shows each field's type beside its name. A text field has nothing to format, so **Format** doesn't appear for one at all.

| The field holds  | Your choices                                                                                                                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A date           | **Default**, **Relative (2 days ago)**, **Short (13/10/2026)**, **Medium (13 Oct 2026)**, **Long (13 October 2026)**, **Month and year (October 2026)**, **Date and time (13 Oct 2026, 14:05)** |
| A number         | **Default**, **Grouped (12,500)**, **Compact (12.5K)**                                                                                                                                          |
| A duration       | **Seconds (75)**, **Clock (1:15)**, **Words (1 min 15 sec)**                                                                                                                                    |
| A file size      | **Readable (2.3 MB)**, **Bytes (2,411,724)**                                                                                                                                                    |
| A list of values | **Default**, **Comma list (Photo, Video)**, **Dot separated (Photo · Video)**, **Count (2)**, **First value only (Photo)**                                                                      |
| Yes or no        | **Default**, **Yes / No**, **✓ / ✗**                                                                                                                                                            |
| One choice       | **Default**, **Option label**                                                                                                                                                                   |

Each option names the format and shows you what it looks like, so you can pick by example rather than by name. The first choice in each row is what you get without choosing anything.

Three things are worth knowing:

* **Formats follow the visitor, not you.** A date set to **Long** reads *13 October 2026* for an English visitor and *13 octobre 2026* for a French one, and numbers group the way that visitor's language groups them.
* **Changing the field resets the format.** The formats offered for a date make no sense for a list, so picking a new field starts again at **Default**.
* **A format that can't apply is ignored.** If the value turns out not to be a date after all, the slot falls back to rendering it plainly rather than showing nothing.

**Durations and file sizes come from your DAM**, not from a dataset — a list connected to the DAM uses this same dialog, and that's where **Video duration** and **Size** are offered.

{% hint style="info" %}
A slot bound to nothing renders empty on the published Portal, even where the builder still shows placeholder copy. Bind every slot the variant draws, or move to a variant that draws fewer.
{% endhint %}

### Media slots

A slot that draws a picture — an image, a video, a GIF — opens the **Media** dialog rather than **Content settings**. Its **Media source** names the dataset field each row takes its media from.

That is how a row's own picture reaches the page: point **Media source** at the row's **Media** field, and every row draws its own.

#### A cover for GIFs

When **Media source** is a **Media** field, the dialog adds **GIF cover image** under it, with the hint *Optional. For items whose media is a GIF: shown with a play button, the GIF plays on click. A cover set on the item itself wins.*

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FEhTPJ1DGiC2HsBg0mesi%2Fconnect-to-dataset-01-gif-cover-field.png?alt=media&amp;token=678d8211-1c4c-4811-87fe-f25cf61070dc" alt="The Media dialog for a dataset list&#x27;s photo slot, with the GIF cover image field" width="480"><figcaption><p>The <strong>Media</strong> dialog on a dataset-bound slot, with <strong>GIF cover image</strong> under <strong>Media source</strong>.</p></figcaption></figure>

Pick the dataset field that holds the still. Then, for every row whose media is a GIF:

* The row shows that cover with a play button, rather than the GIF looping in place.
* An item with its own **Cover image** — set on its media field in the dataset — keeps it. The field you pick here only fills in for items that have none.
* Rows whose media isn't a GIF are unaffected, and a GIF row with no cover at all still plays in place.

The picker leaves out the media source itself and its own preview option: that one is the item's own cover, which is already read first.

{% hint style="info" %}
On a slot whose source is a **Media** field, **GIF cover image** takes the place of **Preview image URL**. It isn't offered on a logo or a background image.
{% endhint %}

**What the visitor gets.** Pressing play opens the GIF in a dialog, the way a video opens. It always starts from its first frame, at its own size — scaled down to fit the screen, never stretched — with a fullscreen button inside the dialog. Closing the dialog stops it. On a row that links somewhere, clicking the cover still follows the link; only the play button opens the GIF.

## Where a row leads

A row can be a link. Its own control on the template opens **List item link settings**, and **Attach link** turns the whole thing on.

**Where does it go?** picks the destination:

| Destination               | The row opens                                  |
| ------------------------- | ---------------------------------------------- |
| **Page**                  | A page of this Portal.                         |
| **URL**                   | A web address.                                 |
| **Section or anchor**     | A particular section, on this page or another. |
| **DAM assets of the row** | A gallery of the assets that row stands for.   |

For **Page**, the dialog tells you which kind of link you have just built: *Each item opens its own row on ‹page›* when the destination comes from a field, or *Every item opens this same page* when every row points at one.

**Trigger download on button click** turns the row's button into a download rather than a navigation.

### DAM assets of the row

This is the destination that pays off a [**DAM assets**](https://docs.scaleflex.com/portals/portal-settings/datasets/fields.md) field: the row describes some assets, and selecting it opens them.

| Setting          | What it names                                                        |
| ---------------- | -------------------------------------------------------------------- |
| **Gallery page** | The page carrying the gallery that will show them.                   |
| **Assets field** | The row's **DAM assets** field — the one holding the rule.           |
| **Row filter**   | Whether the visitor may change what the row filtered the gallery to. |

**Row filter** is the one to think about: **Fixed** locks the gallery to the row's assets, **Visitor can change** opens it there and lets them browse outward. See [Lists connected to the DAM](https://docs.scaleflex.com/portals/building-a-portal/connecting-content/lists-connected-to-the-dam.md) for what each does to the filter panel.

## Adding a row without leaving the builder

A dataset-connected list also keeps a **+ Add item** button, and it does the sensible thing: opens the connected dataset in portal settings with the new-item form already up, in a new tab so your unsaved builder work stays put. The list shows the row as soon as you save it there.

If the dataset has no fields yet, it opens on the [Fields](https://docs.scaleflex.com/portals/portal-settings/datasets/fields.md) tab instead — there's nothing to fill in until the schema exists.

## What the visitor ends up with

Putting it together, a connected list gives them:

* The rows your **fixed criteria** allow, minus any that are still **Draft**.
* In the order the sort and **Group into sections** set, under headings if you grouped.
* **Items per page** at a time, with a pager.
* The **visitor filters** you offered, above the list.
* A linkable anchor per row, if you left **Row anchor** on.
* An entry in the page outline per row, if you turned the content tree on.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FJ9GKnlKD2hVojrzB1UWK%2Fimage.png?alt=media&#x26;token=7c838199-04c9-408e-920e-023016463f76" alt=""><figcaption><p>A dataset-driven list as a visitor meets it — filters above, grouped rows below.</p></figcaption></figure>

## The reference layouts

The **Release notes** section carries two variants built for dataset-driven content:

| Variant | Layout                                                                                                                      |
| ------- | --------------------------------------------------------------------------------------------------------------------------- |
| **E**   | Long-form entry — a labelled caption beside wide media.                                                                     |
| **F**   | Dense changelog rows with labels and a filter bar. This is the one that carries the visitor filters and the group headings. |

They share their slots with variants C and D, so switching between them keeps what you've written and what you've bound. See the [Section library](https://docs.scaleflex.com/portals/building-a-portal/sections/section-library.md) for the rest of the family.

{% hint style="warning" %}
A dataset-connected list can't be shown as a slider — a list configured that way falls back to the grid.
{% endhint %}
