> 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**](/portals/portal-settings/datasets/connect-to-dataset/context.md)   | Which dataset, and how its rows are ordered, grouped and addressed. |
| [**Criteria**](/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**.                                                             |
| **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.

{% 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 %}

## 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](/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](/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 %}