---
url: /tutorials/01-first-interface.md
---
# Building Your First Interface

> **Type:** Tutorial | **Audience:** New end-user | **Goal:** Create and save a simple interface with Title and Paragraph blocks

## Opening the Application

Interface Builder is accessed from Pipedrive via a OneClick button. When the app loads, you land on the **Interface Selection Page**, which lists all views belonging to this button. You will see two tabs at the top: **Views** and **Variables**.

## Creating a New Interface

1. On the Interface Selection Page, click the **Create New** button next to the **Your Views** heading.
2. The **Create new view** dialog opens.
3. Enter a descriptive **Name** — this name is how you will reference it later when setting up navigation between views. The optional **Description** and **Default view** toggle can be left at their defaults.
4. Click **Create**. The new view opens in the Builder.

## Understanding the Builder

When you open a view, the Builder loads with three main areas:

* **Canvas** (left side) — the main working area where you build your interface by arranging rows and blocks.
* **Sidebar** (right side) — shows configuration options for whatever is selected. It has two main tabs at the top: the current selection tab (Block Settings, Row Settings, etc.) and **View settings**.
* **Top Bar** — a navigation bar at the top of the canvas with the interface name, a back arrow to return to the view list, and three buttons on the right: **Preview**, **Test**, and **Sample data**.

The top bar also shows a **Saving...** spinner indicator whenever your changes are being auto-saved.

## Adding a Row

Before you can place any content blocks, you need a row. Rows define the column layout of your interface.

1. On an empty canvas, click the **Add first row** button. On a non-empty canvas, hover the gap between two rows and click the `+` button that appears.
2. The **Add row** dialog opens.
3. Pick a layout:
   * **Full width** — a single column at 100% width
   * **Two columns** — two equal 50/50 columns
   * **Three columns** — three equal 33/33/33 columns
   * **Sidebar left** — 25/75 split
   * **Sidebar right** — 75/25 split
   * **Form** — adds a Form Start + Form End marker pair (covered in [Building a Form](03-building-a-form.md))
4. The dialog closes and the new row appears on the canvas as an empty container with a grey column placeholder.

## Adding a Title Block

1. Click an empty column inside the row you just created. The **Add block** dialog opens.
2. Pick **Title** from the list.
3. The block appears on the canvas with an empty text value.

## Editing Block Content

1. Click on the Title block in the canvas to select it.
2. The sidebar switches to the **Block Settings** tab.
3. You will see a **Text** field. This is a Data-Picker-enabled input that supports both static text and dynamic data placeholders.
4. Type your title text, for example: `Welcome to My Interface`.
5. The canvas updates in real-time to reflect your changes.

## Adding a Paragraph Block

1. Add another row using the `+` button (or use a multi-column row from before).
2. Click an empty column to open **Add block** and pick **Paragraph**.
3. Click the new Paragraph block to select it.
4. In the **Block Settings** tab you will see a **Value** field — the same Data-Picker-enabled input as the Title block's **Text** field.
5. Type your paragraph text, for example: `This is my first interface built with Interface Builder.`

## Previewing Your Interface

1. Click the **Preview** button in the top bar.
2. The view switches from the Builder to Preview mode.
3. In Preview mode, you see your interface rendered as it will appear to end users. Click the **Pipedrive resource** button at the top to pick a specific deal, person, or organization to test with.
4. To return to the Builder, click the back arrow at the top-left of the Preview screen.

## Saving

Your work is saved automatically. After a brief pause in editing, the Builder saves your latest changes to the server. You will see a **Saving...** indicator with a spinner in the top bar while the save is in progress.

There is no manual save button — just keep building and your changes are persisted.

## Summary

In this tutorial you learned to:

* Open Interface Builder from the Interface Selection Page
* Create a new view via the **Create New** button and the **Create new view** dialog
* Understand the Builder layout: canvas, sidebar, and top bar
* Add rows from the **Add row** dialog and pick column layouts
* Add Title and Paragraph blocks from the **Add block** dialog
* Edit block content via the sidebar
* Preview your interface
* Rely on auto-save for persisting your work

---

---
url: /tutorials/02-data-binding-basics.md
---
# Displaying Pipedrive Data in Your Interface

> **Type:** Tutorial | **Audience:** End-user | **Goal:** Bind Pipedrive resource data to blocks using the Data Picker

## What is Data Binding?

Interfaces display data from Pipedrive resources -- deals, persons, organizations, and more. Instead of typing fixed text, you bind a block's text input to a field through the **Data Picker**, and the field's current value is rendered at run time.

The Data Picker inserts each field as a small **blue tag** into the editor. The compiled syntax behind the tag is `{{resource.field}}` (for example `{{deal.title}}`), but in the builder you do not type that syntax yourself -- you click the tag you want and the editor renders it as a tag.

## Opening the Data Picker

1. Select a block on the canvas (for example, a Title or Paragraph block).
2. In the Block Settings panel, find a **Data Picker-enabled input**: Title's **Text** field, Paragraph's **Value** field, and similar fields on other blocks.
3. Click inside the input. A **Data Picker tooltip** appears next to the field.
4. The tooltip's top bar contains an icon-only row of tabs:
   * **Deal** -- deal fields (title, value, currency, owner, ...)
   * **Organization** -- organization fields (name, address, ...)
   * **Person** -- person fields (name, email, phone, ...)
   * **User** -- the current logged-in user
   * **Custom** -- the JSON payload returned by your view's API endpoint or your saved Sample data
   * **Search Params** -- URL parameters passed in from another view
   * **Variable** -- interface-level variables you define in the Variables tab
   * **Functions** -- built-in helper functions

## Browsing Available Data

1. Click a tab to see the fields for that resource.
2. Simple fields (such as `title` or `value`) can be clicked directly to insert them as a tag.
3. Nested fields are expandable. For example, the deal's owner is an object -- expand it to pick `owner_id.name`.
4. The Data Picker remembers which tab you last opened.

## Binding a Deal Title to a Title Block

1. Add a **Title** block to your canvas (or select an existing one).
2. In Block Settings, click the **Text** field. The Data Picker opens.
3. Select the **Deal** tab.
4. Click on **Title**.
5. A blue **Title** tag is inserted into the Text field. The compiled value is `{{deal.title}}`, but you don't see the curly-brace syntax -- you see the tag.

## Combining Static Text and Dynamic Data

You can mix typed text with multiple tags in a single field.

1. Add a **Paragraph** block and select it.
2. In the **Value** field, type: `Deal: `
3. Open the Data Picker and insert the deal **Title** tag.
4. Insert the deal **Currency** tag right after it (or with a space between them).

The editor now shows: `Deal:` followed by a Title tag and a Currency tag. The compiled output is `Deal: {{deal.title}} {{deal.currency}}`.

This technique works in any Data Picker-enabled field across all block types.

## Testing with Real Data

1. Click **Preview** in the top bar to switch to Preview mode.
2. In the Preview top bar, next to the **Preview** title, there is a **Pipedrive resource** button labelled with the active resource (for example `Deal #1995`). Click it to open the **Pipedrive resource** dialog and pick a different deal, person, or organization from your account.
3. The system fetches the real data for the selected resource and replaces every Data Picker tag with the actual value.
4. Your Title and Paragraph blocks render with live Pipedrive data.

If a tag references a resource that is not present (for example a person tag when no person is linked), the rendered value may be empty.

## Understanding Data Types

The Data Picker organises fields by data type:

* **String** -- text values such as names, titles, emails.
* **Number** -- numeric values such as deal amounts and phone numbers.
* **Object** -- nested structures (for example `deal.owner_id` containing `name`, `email`, ...). Expand the object to pick a sub-field; the resulting tag follows the path.
* **Array** -- lists of items (for example deal products). Arrays are used by blocks that iterate, such as the Table block (covered in a later tutorial).

When you pick a sub-field of an object, the Data Picker creates a tag that renders the dotted path (for example `owner_id.name`).

## Summary

In this tutorial you learned to:

* Bind block fields by inserting Data Picker tags instead of typing placeholder syntax
* Browse the eight Data Picker tabs (Deal, Organization, Person, User, Custom, Search Params, Variable, Functions)
* Mix static text and multiple tags in a single field
* Preview your interface with a chosen Pipedrive resource via the Preview top-bar dialog
* Work with nested object fields by expanding them in the Data Picker

---

---
url: /tutorials/03-building-a-form.md
---
# Building a Form

> **Type:** Tutorial | **Audience:** End-user | **Goal:** Create a complete form with inputs and a submit button

## How Forms Are Structured

A form in Interface Builder is defined by two marker rows on the canvas -- **Form Start** at the top and **Form End** at the bottom -- with your content rows in between. Every input placed between those markers belongs to the form. A **Submit button** links to the form by its **Form Identifier** and is what users click to send their answers.

The screenshot below shows the finished tutorial form on the canvas: Form Start carries the `contact-form` identifier badge, and the Submit button shows the same `contact-form` badge — that match is how the button knows which form to send.

## Step 1: Add a Form Element

1. Hover the canvas (or the gap between two rows) to reveal a small `+` button.
2. Click `+` to open the **Add row** dialog.
3. Pick **Form** from the layout list.

Two marker rows appear on the canvas: **Form Start** on top and **Form End** at the bottom, with empty space between them.

## Step 2: Give the Form an Identifier

1. Click the **Form Start** row (Form End works too).
2. The sidebar switches to **Form Settings**.
3. In the **Form Identifier** field, enter a descriptive name. For this tutorial, use `contact-form`.

The identifier shows up as a badge on Form Start on the canvas, and it is how the Submit button (added later) will find the correct form.

## Step 3: Add a Full-Name Input

1. Hover the area between Form Start and Form End — a `+` button appears.
2. Click `+`, pick a one-column **Full** layout in the **Add row** dialog.
3. Click the empty column inside that new row to open the **Add block** dialog and pick **Input**.
4. Click the new Input block to open its settings. You will see fields for **Label**, **Type**, **Placeholder**, **Help text**, **Default Value**, **Required**, and **Disabled**.
5. Set **Label** to `Full Name`.
6. Leave **Type** as **Text**.

## Step 4: Add an Email Input

1. Repeat the same steps to add another row inside the form.
2. Add a second Input block in the new column.
3. Set **Label** to `Email Address`.
4. Change **Type** to **Email**.
5. Turn on the **Required** switch.

## Step 5: Add a Selection Input (Optional)

If you want a drop-down or multi-choice field, pick one of these selection types for **Type**: **Single Select**, **Multi Select**, **Checkbox**, or **Radio**. An **Options Type** selector then appears with two choices:

* **Static** -- you define label/value pairs manually. Use the options editor that appears to add each pair.
* **Dynamic** -- options come from data at render time using the Data Picker. Enter Data Picker expressions for **Labels** and **Values**.

## Step 6: Add Pattern Validation (Optional)

For the simple input types (Text, Email, Number, URL, Date) you can add regex validation:

1. In the input settings, scroll to the **Pattern** field and enter a regex (for example, `^[A-Za-z ]+$`).
2. Optionally fill **Pattern Error** with a custom message shown when the pattern fails.

Test your regex at [regex101.com](https://regex101.com/) before pasting it in.

## Step 7: Add a Submit Button

1. Add a new row using the `+` button. It can be inside or outside the form boundaries — both work.
2. Click an empty column in the new row, then pick **Button** in the **Add block** dialog.
3. Click the new Button to open its settings. Set **Button Type** to **Form Submit Button**.
4. A **Form** dropdown appears. Pick `contact-form` from the list.

## Step 8: Configure Submission

Once Button Type is Form Submit Button, extra settings appear. You will set **Form Type**, **Submit URL**, and an **After submission** behavior.

### Form Type

* **JSON** (default) -- posts form values as a JSON payload to the Submit URL.
* **Multipart/Form-Data** -- use this whenever any input has **Type = File**.
* **Open view with form data** -- instead of posting anywhere, navigates to another view and passes input values as URL search parameters.

### Submit URL

For **JSON** and **Multipart/Form-Data**, enter the endpoint in **Submit URL**. Opening the URL input reveals an advanced dialog where you can also add:

* **Headers** -- custom HTTP headers (key/value pairs; values support the Data Picker).
* **Query parameters** -- additional query string pairs.

### After submission

Pick one of:

* **Wait for response** -- waits up to **Timeout (s)** seconds (10--60) for the server to reply. You can turn on **Disable form after submission** (prevents double-submits) and **Show message after submission** (displays the server's confirmation).
* **Select view** -- immediately navigates to a chosen **View ID** after sending. You can pass static parameters, and optionally forward every input value as search parameters to the target view.

## Step 9: Add a Reset Button (Optional)

To let users clear the form:

1. Add another Button block (use the `+` button to add a row, then **Add block** → **Button**).
2. Set **Button Type** to **Form Reset Button**.
3. In the **Form** dropdown, pick `contact-form`.

## Step 10: Test the Form

1. Click **Preview** in the top bar. The form renders with live inputs.
2. Fill in the fields and click the submit button to see the behavior you configured.
3. For an end-to-end test, click **Test** in the top bar -- test mode runs the interface closer to production.

## Summary

In this tutorial you learned how to:

* Pick **Form** in the **Add row** dialog and work with the **Form Start** / **Form End** markers on the canvas
* Set a **Form Identifier** to name the form
* Add **Input** blocks with different **Types** (Text, Email, and selection types)
* Configure selection inputs with **Options Type** (Static or Dynamic)
* Add **Pattern** validation with a custom **Pattern Error** message
* Add a **Form Submit Button** and link it to the form
* Configure **Form Type**, **Submit URL**, **Headers**, and **After submission**
* Add a **Form Reset Button** to clear the form
* Test the form in Preview and Test modes

---

---
url: /tutorials/04-multi-view-app.md
---
# Building a Multi-View Application

> **Type:** Tutorial | **Audience:** End-user (intermediate) | **Goal:** Create an app with multiple views and navigation

## What are Views?

An interface can contain multiple **views** (pages). Each view is a separate canvas with its own rows and blocks. One view is marked as the **default view** -- it carries a green **Start** badge in the views list and is the view displayed by default when the interface loads.

Users navigate between views using:

* **Action buttons** with the "go to view" action
* **Navbar blocks** with interface-type links

Views are managed from the **Interface Views** page, where every view in the current interface is shown as a card.

## Creating a Second View

1. Go back to the **Interface Views** page by clicking the back arrow in the top bar of the Builder.
2. Click **Create New** to open the **Create new view** dialog.
3. Give it a descriptive name (for example `Order summary`) and click **Create**.
4. Back on the Interface Views list, click the **Edit** button on the new view's card to open it in the Builder.

## Building the Second View

1. With the new view open in the Builder, add rows and blocks as needed.
2. For example, add a Title block bound to `{{deal.title}}` and a Paragraph block showing deal details.
3. This view will serve as a detail page that users navigate to from the first view.

## Adding Navigation with an Action Button

On the first view, set up a button that navigates to the second view:

1. Go back to the Interface Views page and open your first view.
2. Add a **Button** block to the canvas.
3. In Button settings, set the **Button Type** to `Action Button`.
4. A new **Action Type** dropdown appears with two options:
   * **back** -- navigates to the previous view
   * **go to view** -- navigates to a specific view
5. Select **go to view**.
6. A **View Name** dropdown appears, listing all views in this interface. Select the second view you just created.
7. The button now navigates users to that view when clicked.

## Adding a Back Button

On the second view, add a way to return to the first view:

1. Open the second view in the Builder.
2. Add a **Button** block.
3. Set the **Button Type** to `Action Button`.
4. Set the **Action Type** to **back**.
5. This button returns users to whatever view they came from.

The settings panel looks the same as for "go to view" — just without the **View Name** dropdown.

## Passing Parameters Between Views

Action buttons can pass data from one view to another using parameters. The receiving view accesses these values via the **Search Params** tab in the Data Picker.

1. On the first view, select your "go to view" Action Button.
2. Below the View Name dropdown, you will see a **Parameters** section.
3. Click to open the parameters dialog.
4. Add key-value pairs. For example:
   * Key: `deal_id`, Value: a Data Picker tag pointing to the deal's **ID** field.
   * Key: `deal_title`, Value: a Data Picker tag pointing to the deal's **Title** field.
5. Values support Data Picker expressions, so you can pass dynamic data.

On the receiving view:

1. Select a block (for example, a Title block).
2. Open the Data Picker and switch to the **Search Params** tab (the icon-only tab in the picker's top bar).
3. You will see the parameter keys you defined. Selecting one inserts a tag that compiles to `{{searchparams.deal_id}}`.

## Using Navbar for Navigation

For persistent navigation across your interface, use a **Navbar** block:

1. Add a **Navbar** block to a row on your view. It typically goes in a full-width row at the top.
2. Click the Navbar block to open its settings. The settings are divided into sections.

### Brand

* Toggle **Show title** to display a text title in the navbar. Configure **Title Text**, **Font Size (px)** (12–48), **Font Weight** (Normal, Medium, Semibold, Bold), and **Title Color**.
* Toggle **Show logo** to display a logo image. Provide the **Image URL**, **Alt Text**, and **Width / Height (px)**.

### Aria Label

Below the Brand section, set the **Aria Label** for the navigation element (defaults to "Navigation menu"). This helps screen readers identify the navigation purpose.

### Layout

* **Layout Direction** — Horizontal or Vertical
* **Alignment** — Left, Center, Right, or Space Between
* **Spacing (px)** — pixel spacing between nav items (0–50)

### Navigation Links

1. Click the **Manage Links** button to open the links dialog.
2. Click **Add** to create a new link. Each link has:
   * **Label** — the text displayed in the navbar
   * **Link Type** — choose between:
     * **Interface** — navigates to another view within this interface. Select the target view from the **Target Interface** dropdown. You can also add **Parameters** (key-value pairs) that are passed to the target view.
     * **External URL** — opens an external URL (supports Data Picker expressions)
3. Add links for each view you want in your navigation.
4. Reorder links by dragging the grip handle on each link card.
5. Delete links using the trash icon.

## Summary

In this tutorial you learned to:

* Create multiple views from the Interface Views page
* Use Action Buttons with the "go to view" action to navigate between views
* Add "back" buttons for return navigation
* Pass parameters between views using key-value pairs and Data Picker expressions
* Access passed parameters on the receiving view via the Search Params tab
* Set up a Navbar block with interface-type links for persistent navigation
* Configure navbar Brand, Aria Label, Layout, and link settings

---

---
url: /tutorials/05-table-view.md
---
# Building a Table View

> **Type:** Tutorial | **Audience:** End-user | **Goal:** Create a data table with columns and actions

## When to Use Tables

The **Table** block displays array data in a structured grid with rows and columns. Common use cases include:

* Displaying deal products or line items
* Showing lists of related contacts or organizations
* Rendering any array data from Pipedrive or custom sources

Tables support configurable columns, per-row actions, sorting, conditional visibility, and custom styling.

## Adding a Table Block

1. Hover the canvas (or the gap between rows) to reveal the `+` button. Click it and pick **Full** in the **Add row** dialog — full-width works best for tables.
2. Click the empty column inside the new row to open **Add block**, then pick **Table**.
3. Click the Table block to open its settings in the sidebar.

## Setting the Data Source

The table needs an array data source to iterate over.

1. In Table settings, find the **Target Array** field. This is a Data Picker input that specifies which array to display.
2. Click the Target Array field to open the Data Picker.
3. Navigate to an array field. For example, under the **Deal** tab, find a field that contains array data (such as deal products or a custom field that returns a list).
4. You can also use the **Custom** tab if your data comes from a custom JSON source.
5. Select the array field. The placeholder is inserted into the Target Array field.

The table renders one row per item in the array.

## Table Header (Optional)

Above the data source, the sidebar exposes:

* **Table Title** — optional text rendered above the table, for example `Deal Products`. It is plain text: the Data Picker is not available here.
* **Title Alignment** — Left, Center, or Right alignment for the title text.
* **Default Cell Alignment** — fallback alignment applied to every column that does not set its own alignment. Choose Left, Center, or Right.
* **Empty table text** — text shown when the Target Array resolves to an empty list. This is a Data Picker input and supports dynamic values.

## Configuring Columns

Columns define what data appears in each table column. Use the **Manage Columns** dialog to add and configure them.

1. Click the **Manage Columns** button in Table settings.
2. The dialog opens with a column list on the left and a settings panel on the right.
3. Click the **Add** dropdown to add a new column. You can choose between:
   * **Add value column** — displays data from each array item.
   * **Add action column** — displays clickable action icons.
   * **Add subrow** — displays an extra row of text rendered below each row (useful for descriptions or secondary info).
4. Select a column on the left to edit its settings on the right.

Columns can be reordered by dragging the grip handle, duplicated with the copy icon, or deleted with the trash icon. Subrow columns cannot be reordered — they always render below the main row.

Each column has its settings split across four tabs in the right panel:

* **General** — the data fields that drive the column.
* **Styling** — width, cell alignment, and cell padding.
* **Sorting** — whether the column is sortable and how.
* **Conditional** — when the column is visible.

### Value Columns: General Tab

For each value column, fill in:

* **Header** — the column header text. This is a Data Picker input, so you can use static text or dynamic values.
* **Value(s)** — the data field to display for each row. This is a Data Picker input that resolves relative to each array item. For example, if your array contains objects with a `name` property, enter `name` or use the Data Picker to select the field.

### Value Columns: Styling Tab

* **Cell Alignment** — Left, Center, or Right for the cell content.
* **Column Width** — pick **Auto**, or set a fixed width in `%` or `px`.
* **Cell padding** — toggle to override the table default. When enabled, you can set Top, Right, Bottom, and Left padding individually.

### Value Columns: Sorting Tab

* **Allow sorting** — toggle to let end-users click the column header to reorder rows.
* **Sort by this column** — when enabled, this column is the table's default sort. Only one column can hold this flag.
* **Sort direction** — **Ascending** or **Descending** for the default sort.
* **Custom sort value** — when enabled, sort rows by a different value than the displayed one. Provide a Data Picker path for **Sort value**.

### Value Columns: Conditional Tab

* **Enable conditional visibility** — toggle to hide the column based on a condition.
* **Condition** — Data Picker expression. The column is hidden when the value resolves to empty or `"false"`. Any other value shows the column.

## Action Columns

Action columns add clickable buttons to each row, allowing users to perform operations on individual items. A button can show an icon, a text label, or both.

1. In the Manage Columns dialog, click **Add** and select **Add action column**.
2. The General tab shows the column's **Header** plus an accordion of **actions**. Each action has:
   * **Icon** — choose from grouped **Actions**, **Communication**, **Files**, and **Status** icons. The set includes View, Edit, Delete, Add, Copy, Play, Refresh, External link, Mail, Send, Phone, Message, Bell, User, File, Folder, Download, Upload, Image, Attachment, Print, Archive, Check, Close, Warning, Info, Clock, Star, Heart, Lock, and Unlock. Select **Custom** to fill **Custom Icon** with an image URL through the Data Picker.
   * **Action Type** — pick **Go to view** to navigate within the interface, **Go to URL** to open a URL, or **Send request** to send a POST without leaving the table.
   * **Label** — optional button text, shown after you pick an Action Type. It supports the Data Picker and resolves per row. With a Label set, **Icon position** chooses which side the icon sits on, and the Icon picker offers **No icon** for a text-only button.
   * **View Name** — when Action Type is **Go to view**, pick the destination from the dropdown. Optionally configure **Parameters** (key-value pairs passed to the target view; values reference fields from the current row).
   * **URL** — when Action Type is **Go to URL**, fill the address. The URL field supports Data Picker expressions, so you can construct URLs with row data.
   * **Request URL** — when Action Type is **Send request**, enter an absolute HTTP or HTTPS endpoint. Use the Data Picker to include row values.
   * **Body Data** — optionally configure a JSON payload as JSON or key-value pairs. Include the row's identifier because OneClick metadata identifies the view resource, not the row. Leave it empty for no configured body.
   * **Omit OneClick metadata envelope** — leave off to send Body Data alongside OneClick metadata; turn on to send only Body Data. Test requests in the Test view; Preview shows them disabled.
   * **Require confirmation** — when Action Type is **Send request**, turn this on to ask before the request is sent. The **Title** and **Description** support the Data Picker, so the dialog can name the row it acts on.
3. Click **Add Action** to add more actions to the same column.
4. Each action can be duplicated or deleted from the action's accordion menu.

The Styling, Sorting, and Conditional tabs apply to action columns in the same way as value columns.

### Passing Row Data to Another View

When an action navigates to a view, you can pass data from the current table row:

1. Set the action's **Action Type** to **Go to view**.
2. Choose the target view from **View Name**.
3. Expand the **Parameters** section.
4. Add key-value pairs where the values reference fields from the current array item. The Data Picker context is scoped to the current row, so you can directly select fields from the row item.

## Subrow Columns

A **subrow** column adds a second line of text below each main row — useful for descriptions, hints, or secondary details that do not need their own column.

* **Path** — the data field rendered as the subrow's text (Data Picker).
* The Styling tab supports **Cell Alignment** and **Cell padding** for the subrow text. Conditional visibility is not available for subrow columns.

## Customizing Appearance

In addition to per-column styling, the Table block uses the standard block style settings:

* **Background color**
* **Font size and color**
* **Borders** — top, right, bottom, and left borders with width, style, and color

The table renders with structured headers and data rows. When the array is empty, the **Empty table text** (if configured) is shown.

## Summary

In this tutorial you learned to:

* Add a Table block and set its data source via the **Target Array** field
* Configure the **Table Title**, **Title Alignment**, **Default Cell Alignment**, and **Empty table text** at the table level
* Add **value**, **action**, and **subrow** columns from the **Manage Columns** dialog
* Configure each column across the **General**, **Styling**, **Sorting**, and **Conditional** tabs
* Add **Go to view**, **Go to URL**, and **Send request** actions with per-row data
* Toggle **Allow sorting**, set a default sort column and direction, and use a custom sort value
* Hide columns conditionally using the **Conditional** tab

---

---
url: /how-to/blocks/alert-and-badge.md
---
# How to Use Alert and Badge Blocks

> **Type:** How-to | **Audience:** End-user | **Goal:** Add notification alerts and status badges

## Alert Block

1. Hover the gap between two rows and click the `+` button to add a row, then click an empty column and pick **Alert** in the **Add block** dialog.
2. Click the new block to open its settings in the sidebar.

### Setting the Variant

The variant controls the alert's visual style. The Variant card has two tabs:

**Select tab** (default): Pick a variant from the dropdown:

* **Default** -- neutral style
* **Destructive** -- red, for errors
* **Info** -- blue, for informational messages
* **Success** -- green, for confirmations
* **Warning** -- yellow/amber, for caution

**Data tab**: Use the Data Picker to bind the variant to a data field. The field value must be one of: `default`, `destructive`, `info`, `success`, `warning`.

### Title and Description

* **Title (Optional)**: Use the Data Picker to set the alert title. You can type static text or pick a dynamic value from your data source using `{{resource.field}}` syntax.
* **Description**: Use the Data Picker to set the alert body text. Same static/dynamic options as title.

***

## Badge Block

1. Hover the gap between two rows and click the `+` button to add a row, then click an empty column and pick **Badge** in the **Add block** dialog.
2. Click the new block to open its settings in the sidebar.

### Setting the Variant

Like Alerts, Badges have **Select** and **Data** tabs in the Variant card.

Static variants available:

* Default, Destructive, Info, Success, Warning, Secondary, Outline, Pink, Violet, Light Blue, Disabled

In the Data tab, use the Data Picker to bind the variant to a data field. Valid values: `default`, `destructive`, `info`, `success`, `warning`, `secondary`, `outline`, `pink`, `violet`, `lightBlue`, `disabled`.

### Setting the Value

Use the **Text** field to set the badge text. You can type static text or use the Data Picker with `{{resource.field}}` to pull values dynamically from your data source.

---

---
url: /how-to/blocks/avatar.md
---
# How to Add Avatars

> **Type:** How-to | **Audience:** End-user | **Goal:** Display profile/avatar images

## Adding an Avatar Block

1. Hover the gap between two rows and click the `+` button to add a row (pick any layout in the **Add row** dialog).
2. Click an empty column inside the row, then pick **Avatar** in the **Add block** dialog.
3. Click the new block to open its settings in the sidebar.

## Image Source

Use the **Image URL** field to set the avatar image URL. Typically you bind this to a dynamic data field such as a Pipedrive user photo or person photo URL using `{{resource.field}}` syntax.

If the URL resolves to a valid image, the avatar displays that image.

## Fallback Text

Use the **Fallback Name** field to define fallback text shown when no image is available. This is typically a person's name -- the avatar automatically extracts initials from the first two words (e.g., "John Doe" becomes "JD").

You can use static text or bind it dynamically via the Data Picker.

## Size Selection

Choose the avatar size from the dropdown:

* **Small (32px)**
* **Medium (40px)** — default
* **Large (56px)**

---

---
url: /how-to/blocks/button.md
---
# How to Add and Configure Buttons

> **Type:** How-to | **Audience:** End-user | **Goal:** Configure all button types

## Adding a Button Block

1. Add a row if you do not have one yet — hover the gap between two rows to reveal the `+` button, click it, and pick a layout.
2. Click an empty column inside the row to open the **Add block** dialog.
3. Pick **Button** from the list.
4. Click the new block to open its settings in the sidebar.
5. Choose a **Button Type**: **URL Button**, **Action Button**, **Form Submit Button**, or **Form Reset Button**.

***

## URL Button

Opens a URL or makes an API call when clicked.

1. Set **Button Type** to **URL Button**.
2. Optionally fill **Button Identifier** -- a unique identifier for tracking this button.
3. Choose the **Button URL** mode:
   * **Use view base url** -- appends a path to your view's base URL.
   * **Use custom url** -- a fully custom URL.
4. For **Use view base url**, set **Path**. For **Use custom url**, set **Custom URL**. Both support the Data Picker for dynamic values.
5. Optionally configure:
   * **Button Body Data** -- JSON or form-encoded body sent with the request.
   * **Headers** -- custom HTTP headers (key/value pairs). If the OneClick button this interface is attached to has its **Headers** toggle enabled, those headers are merged into the URL button's request automatically — see [OneClick-Level Headers](../../explanation/architecture.md#oneclick-level-headers).
   * **Query parameters** -- URL query parameters (key/value pairs).
   * **Wait page transition** -- enable to wait for interstitial messages and redirects from your backend (see below).
   * **Page Transition Timeout** -- how long to wait for the backend (in seconds).

### How a URL button handles the response

For the request shape your endpoint receives and the polling loop that runs while **Wait page transition** is on, see [URL Button Flow](../../explanation/url-button-flow.md).

When the user clicks a URL button, Interface Builder calls your backend and then:

* **If Wait page transition is off**, the response is used once: a string body becomes a success toast, an `oneclick_data` response can show a toast and/or navigate the user. Nothing else happens.
* **If Wait page transition is on**, Interface Builder keeps polling for updates from your backend for up to **Page Transition Timeout** seconds. Every time your backend writes a new message, the user sees it as a toast. If your backend eventually returns a redirect, the user is navigated there.

Use **Wait page transition** when the action behind the button takes time to complete and you want to show progress (for example, "Validating…", "Charging card…", "Creating invoice…") and then jump the user to a result page when done.

**Response shapes:**

```json
{ "oneclick_data": { "message": "Item added to cart" } }
```

Shown as a success toast.

```json
{
  "oneclick_data": {
    "message": "Payment successful",
    "redirect_view": { "id": "receipt-view", "params": { "order_id": "4321" } }
  }
}
```

Shown as a toast, then user is navigated to `receipt-view`.

```json
"Thanks!"
```

A plain string response is shown as a success toast.

See [HTTP Response Format](../../reference/data-binding/http-response-format.md) for every shape the button accepts, and [Messages & Toasts](../data/messages-and-toasts.md) for how to format the message text.

If the backend times out or returns an error, the user sees an error toast. No navigation happens.

***

## Action Button

Navigates between views in your interface.

1. Set **Button Type** to **Action Button**.
2. Choose the **Action Type**:
   * **go to view** -- navigate to a specific view.
   * **back** -- go to the previous view.
3. For **go to view**, select the target view from the **View Name** dropdown.
4. Optionally add **Parameters** -- key-value pairs passed to the target view.

***

## Form Submit Button

Submits a form's data.

1. Set **Button Type** to **Form Submit Button**.
2. Select the target form from the **Form** dropdown. This links to the **Form Identifier** set on the form.
3. Choose the **Form Type**:
   * **JSON** (default) -- sends form data as JSON. Requires a Submit URL.
   * **Multipart/Form-Data** -- sends as multipart data (use for file uploads). Requires a Submit URL.
   * **Open view with form data** -- passes form data to another view without making an HTTP request. Submit URL is not required.
4. For **JSON** and **Multipart/Form-Data**, set the **Submit URL** -- the endpoint that receives the data.
5. Configure **After submission**:
   * **Select view** -- navigate to a chosen view after submission. Optionally pass parameters or forward input values as search params.
   * **Wait for response** -- wait for the server response (timeout: 10-60 seconds). Optionally enable **Disable form after submission** to prevent double-submits, or **Show message after submission** to display a confirmation.
6. Optionally configure **Headers** and **Query parameters** for the request.

See [Configuring Form Submission](../forms/form-submission.md) for full details on submission behavior.

***

## Form Reset Button

Clears all fields in a form back to their default values.

1. Set **Button Type** to **Form Reset Button**.
2. Select the target form from the **Form** dropdown.

***

## Asking for Confirmation

Use a confirmation when a click deletes, sends, approves, or clears something. The button then opens a dialog and runs its action only after the user confirms. It works on all four button types.

1. Select the button and scroll to the **Confirmation** section at the bottom of the **Configuration** tab.
2. Turn on **Require confirmation**. The dialog is filled in for you: "Are you sure?", **Confirm**, and **Cancel**, with the Confirm choice copying the button's own variant.
3. Write the **Title** as the question the user answers, for example `Delete {{deal.title}}?`. It supports the Data Picker, so a button inside an Area loop asks about that iteration's record.
4. Optional: add a **Description** with what will happen. It also supports the Data Picker and keeps its line breaks.
5. Optional: adjust **Confirm Button Label** and **Confirm Button Variant** — pick **Destructive** for a delete — and the matching **Cancel** fields.
6. Test the button in the Test view: the dialog must open, and the action must run only after **Confirm**.

Cancel and Escape close the dialog and change nothing. Turning **Require confirmation** back off keeps the texts you wrote, so removing the gate for a test costs nothing.

### On a Form Submit Button

The dialog opens before the form is validated, so a user can confirm and then meet "field required". This is expected: the submission runs unchanged after the confirmation, validation and all. Keep the Title about the action ("Send the application?") rather than about the data being complete.

Pressing Enter in a text input opens the dialog too — the form clicks the gated button for you, so Enter cannot skip the question.

***

## Button Appearance

Variant and size live on the **Style** tab in Block Settings (next to **Configuration** and **Visibility**).

### Button Variant

Choose a visual style from the **Button Variant** selector:

* **Default** -- primary filled button
* **Destructive** -- red/danger style
* **Outline** -- bordered, no fill
* **Secondary** -- muted/secondary fill
* **Ghost** -- no border or fill, text only
* **Link** -- styled as a hyperlink
* **Custom** -- unlocks the rest of the Block Style panel (font size/weight/colours, etc.) so you can build your own look. The other variants ignore those custom style fields.

### Button Size

Choose from: **Small**, **Default**, or **Large**.

### Icons

Both icon slots sit on the same **Style** tab, between **Button Size** and **Button Variant**.

1. Open **Icon before text** and pick a glyph, or **Icon after text** for a trailing one.
2. Pick from the groups **Actions**, **Navigation**, **Communication**, **Files** and **Status**.
3. Choose **No icon** to clear a slot again.

The glyph takes the button's text colour and is always 16 px, so every Button Variant works.

### Making a button icon-only

Use this for a dense row of controls where the words cost more width than they earn.

1. Pick a glyph in **Icon before text**.
2. Turn **Show text** off.

The button becomes a square of the height its **Button Size** already had, keeping its variant colours.

What to expect:

* **Show text** stays unavailable until you pick an icon, and a note below it tells you so. A button with no text and no glyph would be empty.
* **Icon after text** becomes unavailable while the text is hidden. If your only glyph was in that slot, it moves to **Icon before text** when you hide the text.
* The block name is still the button's name: a screen reader announces it, and it appears as a tooltip on hover.
* Your service still receives the block name as the button name in the URL Button metadata.
* On a **Form Submit Button** with **Show error indicator on submit**, the hover reports the invalid field count while the form has errors; the name tooltip returns once the errors are fixed. The badge and the loading spinner are unaffected.

---

---
url: /how-to/blocks/chart.md
---
# How to Add Charts

> **Type:** How-to | **Audience:** End-user | **Goal:** Create bar, line, area, or pie charts

## Adding a Chart Block

1. Hover the gap between two rows and click the `+` button to add a row (pick any layout in the **Add row** dialog).
2. Click an empty column inside the row, then pick **Chart** in the **Add block** dialog.
3. Click the new block to open its settings in the sidebar.

## Selecting Chart Type

Choose the chart type from the **Chart Type** dropdown:

* **Bar** -- vertical bar chart (default)
* **Line** -- line chart
* **Area** -- filled area chart
* **Pie** -- pie/donut chart

## Configuring Data Source

Use the **Data Source** field to bind the chart to an array data source. The Data Picker only allows array-typed values here; pick the array field that holds your data points (it will appear as a blue tag, for example a custom field that resolves to a list of invoices).

Each item in the array must be an object whose properties supply the values and labels for the chart.

## Setting Keys

* **Data Keys** -- comma-separated list of property names to plot as values. For a single series, enter one key (for example `amount`). For multi-series charts, separate with commas (for example `paid,open,overdue`).
* **Name Key** -- the property used for labels on the X-axis or pie segments. Defaults to `name`.

Example data structure (matching the screenshot):

```json
[
  { "invoice_number": "INV-2026-001", "customer": "Acme Corporation Ltd", "amount": 12500, "status": "Paid" },
  { "invoice_number": "INV-2026-002", "customer": "Nordic Solutions AB",  "amount":  2400, "status": "Paid" },
  { "invoice_number": "INV-2026-003", "customer": "TechVenture GmbH",     "amount":  8750, "status": "Open" },
  { "invoice_number": "INV-2026-004", "customer": "Greenfield Industries","amount": 15000, "status": "Open" }
]
```

With **Data Keys** = `amount` and **Name Key** = `customer`, each row becomes one bar/segment labelled by customer name.

## Visual Options

* **Height** -- chart height in pixels (100--800, default `300`)
* **Show Grid** -- toggle background grid lines on/off (default on)
* **Show Tooltip** -- toggle hover tooltips on/off (default on)
* **Show Legend** -- toggle the chart legend on/off (default off)

---

---
url: /how-to/blocks/hover-card.md
---
# How to Use Hover Cards

> **Type:** How-to | **Audience:** End-user | **Goal:** Add tooltip-style hoverable cards

## Adding a Hover Card Block

1. Hover the gap between two rows and click the `+` button to add a row (pick any layout in the **Add row** dialog).
2. Click an empty column inside the row, then pick **Hover Card** in the **Add block** dialog.
3. Click the new block to open its settings in the sidebar.

## Trigger Type

Choose what the user hovers over to reveal the card. Set **Trigger Type** to:

* **Text Only** — displays trigger text only (default)
* **Icon Only** — displays an icon only
* **Text + Icon** — displays both text and an icon

When the trigger includes text, fill the **Trigger Text** field. You can use static text or bind it dynamically with the Data Picker.

## Icon Configuration

When the trigger type includes an icon (**Icon Only** or **Text + Icon**), the sidebar shows two extra fields:

* **Icon Type** — pick the icon style: **Warning (Triangle)**, **Info (Exclamation)**, or **Question (Help)**. Default: **Question (Help)**.
* **Icon Color** — pick the icon color: **Gray**, **Red**, **Yellow**, **Blue**, or **Green**. Default: **Gray**.

## Content, Width, Alignment

* **Content** — the hover card body content. Use static text or the Data Picker for dynamic values.
* **Width** — set the card width in pixels (100–600). Default: 320.
* **Alignment** — set card alignment relative to the trigger: **Start**, **Center**, or **End**. Default: **Center**.

---

---
url: /how-to/blocks/html.md
---
# How to Use the HTML Block

> **Type:** How-to | **Audience:** Advanced end-user | **Goal:** Embed custom HTML content

## Adding an HTML Block

1. Hover the gap between two rows and click the `+` button to add a row (pick any layout in the **Add row** dialog).
2. Click an empty column inside the row, then pick **HTML** in the **Add block** dialog.
3. Click the new block to open its settings in the sidebar.

## Writing HTML Content

Enter your HTML markup in the **HTML** field. The field accepts whatever you paste -- there is no validation in the builder itself.

> **Pasting from ChatGPT or similar tools**
> Pasted content is normalised before it is saved: smart quotes (`"` `"` `'` `'`) become straight quotes, en/em dashes (`–` `—`) become hyphens, non-breaking spaces become regular spaces, and zero-width characters and Windows line endings are stripped. This prevents invisible artefacts from breaking your markup. Valid HTML entities like `&` are left untouched.

When the view renders, the HTML is run through a sanitiser. Only a fixed allowlist of tags survives:

`p`, `span`, `div`, `br`, `hr`, `h1`--`h6`, `ul` / `ol` / `li`, `dl` / `dt` / `dd`, `table` / `thead` / `tbody` / `tfoot` / `tr` / `th` / `td` / `caption` / `colgroup` / `col`, `a`, `img`, `figure`, `figcaption`, `details`, `summary`, plus inline-formatting tags (`strong`, `b`, `em`, `i`, `u`, `s`, `strike`, `del`, `ins`, `sub`, `sup`, `small`, `mark`, `abbr`, `code`, `pre`, `blockquote`).

Allowed attributes: `href`, `src`, `alt`, `title`, `width`, `height`, `colspan`, `rowspan`, and `style` (so inline CSS is supported).

Anything else -- `<script>`, `<iframe>`, custom elements, event handlers, unsupported attributes -- is stripped at render time.

## Using Placeholders in HTML

You can mix dynamic data into your HTML using `{{resource.field}}` placeholder syntax. The HTML field is a Data Picker input, so you can also click a field in the Data Picker to insert it as a tag; either way the compiled output is the curly-brace placeholder. For example:

```html
<div>
  <h3>{{deal.title}}</h3>
  <p>Value: {{deal.value}} {{deal.currency}}</p>
</div>
```

The placeholders are resolved at render time with actual data from your data sources.

## Filling the Row with Cards

An HTML block is as wide as its content by default, so markup such as `width:100%` or `width:33%` is measured against that content, not against the row. To let cards share the whole row:

1. Select the HTML block.
2. In Block Settings, turn on **Full width**. The block now fills its column.
3. Put the cards in a wrapping flex container, and give every card an equal share with a floor at its own content width:

```html
<div style="display:flex;flex-wrap:wrap;gap:0.75em">
  <div style="flex:1 1 0;min-width:max-content;border:1px solid #E5E7EB;border-radius:8px;padding:0.75em">
    <strong>{{won_by_month.0.month}}</strong>
    <div>{{won_by_month.0.won}}</div>
  </div>
  <div style="flex:1 1 0;min-width:max-content;border:1px solid #E5E7EB;border-radius:8px;padding:0.75em">
    <strong>{{won_by_month.1.month}}</strong>
    <div>{{won_by_month.1.won}}</div>
  </div>
  <div style="flex:1 1 0;min-width:max-content;border:1px solid #E5E7EB;border-radius:8px;padding:0.75em">
    <strong>{{won_by_month.2.month}}</strong>
    <div>{{won_by_month.2.won}}</div>
  </div>
</div>
```

`flex:1 1 0` gives every card the same share of the row. `min-width:max-content` stops a card from getting narrower than its content, and `flex-wrap:wrap` then moves the cards that do not fit onto the next line. The layout needs no pixel widths: in a wide panel the cards sit side by side, and in a narrow panel they stack.

With **Full width** off, the same markup shrinks to the width of the cards' content.

## Preview

Switch to Preview mode to see the rendered HTML output. Disallowed markup is removed during sanitisation and Data Picker placeholders are replaced with the values of the chosen Pipedrive resource.

### Previewing without leaving the dialog

Click the expand icon on the **HTML** field and toggle **Show result** to render the compiled HTML inside the dialog itself — no need to switch to Preview mode. The dialog applies the same sanitiser as the live view, so anything that would be stripped in production is also stripped here.

---

---
url: /how-to/blocks/image.md
---
# How to Add Images

> **Type:** How-to | **Audience:** End-user | **Goal:** Add static or dynamic images

## Adding an Image Block

1. Hover the gap between two rows and click the `+` button to add a row (pick any layout in the **Add row** dialog).
2. Click an empty column inside the row, then pick **Image** in the **Add block** dialog.
3. Click the new block to open its settings in the sidebar.

## Settings

The Image block has four fields in the **Configuration** sub-tab:

| Setting | Description |
|---|---|
| **Name** | Internal name shown on the canvas block label and used in builder error messages. Does not appear in the rendered output. |
| **Url** | The image source. Paste a static URL or use the Data Picker to bind it to a data field (for example `{{person.picture_url}}`). |
| **Width** | Image width in pixels. Leave empty for `auto` (the image keeps its natural width, constrained by the column). |
| **Height** | Image height in pixels. Leave empty for `auto`. |

::: warning Alt text is hard-coded
The rendered image always uses the alt text `Picture`, regardless of what the image actually shows. Screen reader users will not get a meaningful description.
:::

If **Url** is empty or resolves to an empty string at render time, the `<img>` element still renders but with no `src`, which the browser shows as a broken-image placeholder. Bind a fallback through the Data Picker (for example `{{useDefault(person.picture_url, variable.placeholder_avatar_url)}}`) when the source field may be missing.

## Style and Visibility

Open the block's **Style** sub-tab to add borders or round the corners:

* **Top / Right / Bottom / Left Border** -- enable any side and set its **Width** (px), **Style** (Solid / Dashed / Dotted), and **Color**.
* **Border Radius (px)** -- round the image corners; large values produce a circle.

The Image block has no font controls (it has no text) and no Background Color -- the Style sub-tab hides those rows. See [Block Styles](../../reference/styles/block-styles.md) for the full set of controls.

The standard **Visibility** sub-tab is also available -- bind a condition to show or hide the image based on data. See [Conditional Visibility](../visibility/conditional-visibility.md).

---

---
url: /how-to/blocks/navbar.md
---
# How to Add a Navigation Bar

> **Type:** How-to | **Audience:** End-user | **Goal:** Configure a navbar with links, a title, and a logo

## Adding a Navbar Block

1. Hover the gap between two rows and click the `+` button to add a row — usually a full-width row at the top of the view.
2. Click an empty column inside the row, then pick **Navbar** in the **Add block** dialog.
3. Click the new block to open its settings in the sidebar.

## Adding Links

Scroll the sidebar to the **Navigation Links** section and click **Manage Links**. A dialog opens where you can add and reorder links.

1. Inside the dialog, click **Add** to create a new link. The link expands into an editable card.
2. Fill in the link fields:
   * **Label** — the text shown to the user. Required.
   * **Link Type** — pick **Interface** to navigate to another view inside this interface, or **External URL** to open an external address.
   * For **Interface** links: pick the destination from the **Target Interface** dropdown and optionally add **Parameters** (key-value pairs passed to the target view).
   * For **External URL** links: enter the address in the **URL** field. The URL field supports the Data Picker.
3. Drag the grip handle on the left of each link card to reorder links.

## Styling Links

Each link card has a **Variant** dropdown that controls the link's visual style. The options are the same as on the Button block: **Default**, **Link**, **Destructive**, **Outline**, **Secondary**, **Ghost**, and **Custom**.

Leave the dropdown on **Navbar default** to keep the classic navbar look. Note that picking **Ghost** explicitly is not the same as **Navbar default** — an explicit variant styles the link entirely on its own.

### Custom colors

Pick **Custom** to choose the colors yourself:

1. Set **Text Color** with the color picker. Required.
2. Set **Background Color**. Required — or check **Transparent** for no background.
3. Optionally check **Enable** next to **Hover Background Color** and pick the background color shown while hovering.

### Same style for every link

Set up one link the way you want, then click **Apply to all links**. This copies that link's Variant and custom colors onto every other link. The button appears when the navbar has more than one link.

## Brand: Title and Logo

Both the title and the logo are configured inside the **Brand** section at the top of the sidebar.

### Title

Turn on **Show title** to display a title in the navbar.

* **Title Text** — the title string.
* **Font Size (px)** — between 12 and 48.
* **Font Weight** — **Normal**, **Medium**, **Semibold**, or **Bold**.
* **Title Color** — the title's color (color picker).

### Logo

Turn on **Show logo** to display a logo image.

* **Image URL** — the logo image URL.
* **Alt Text** — alternative text for screen readers and for when the image fails to load.
* **Width (px)** — between 16 and 200.
* **Height (px)** — between 16 and 200.

## Layout

The **Layout** section controls how items are arranged inside the navbar.

* **Layout Direction** — **Horizontal** (links in a row) or **Vertical** (links stacked).
* **Alignment** — **Left**, **Center**, **Right**, or **Space Between**.
* **Spacing (px)** — gap between items, 0 to 50.

## Accessibility

* **Aria Label** — screen-reader name for the navigation region. Default placeholder: "Navigation menu".

---

---
url: /how-to/blocks/table.md
---
# How to Configure Tables

> **Type:** How-to | **Audience:** End-user | **Goal:** Set up table data source, columns, and actions

## Adding a Table Block

1. Hover the gap between two rows and click the `+` button to add a row -- a full-width layout works best for tables.
2. Click an empty column inside the row, then pick **Table** in the **Add block** dialog.
3. Click the new block to open its settings in the sidebar.

## Top-Level Configuration

The Block Settings sidebar's **Configuration** sub-tab contains the table-wide fields, in this order:

| Setting | Description |
|---|---|
| **Table Title** | Optional title shown above the table. Plain text: the Data Picker is not available here, and a typed placeholder shows as written. |
| **Title Alignment** | **Left**, **Center**, or **Right**. |
| **Default Cell Alignment** | **Left**, **Center**, or **Right** -- the default horizontal alignment for every cell unless a column overrides it. |
| **Target Array** | The data source. Bind it to a single array via the Data Picker (for example `{{resource.items}}`). Required. |
| **Empty table text** | Message shown when the Target Array is empty (max 255 characters). Supports the Data Picker. |
| **Sum label** | Optional text for the Sum row, for example `Total`. Supports the Data Picker. It renders in the first visible column that has no sum of its own. |
| **Allow export** | Switch, off by default. When on, an **Export** menu renders above the table, from which a reader downloads the table as a CSV file or copies it to the clipboard. See [Let a Reader Export the Table](#let-a-reader-export-the-table). |
| **Manage Columns** | Button that opens the column editor (see below). |

## Managing Columns

Clicking **Manage Columns** opens a dialog with two panels:

* **Left panel** -- the column list with a per-column **...** menu (Copy / Delete) and a drag handle to reorder. The bottom **Add** button opens a dropdown with **Add value column**, **Add action column**, and **Add subrow** (subrow is disabled if the table already has one -- only one is allowed).
* **Right panel** -- the settings for the selected column, organised into tabs: **General**, **Styling**, **Sorting**, **Sum** (value columns only), and **Conditional**. The General tab also shows a **Column Overview** with summary cards for Styling, Sorting, and Conditional that double as shortcuts to those tabs.

Each column has an internal identifier (`key`) that the builder generates automatically -- it is never edited from the UI.

### Value Column (General tab)

| Field | Description |
|---|---|
| **Header** | Column header text. Supports the Data Picker. Required. |
| **Value(s)** | Path to the field within each row item (for example `name` or `price`). Supports the Data Picker. The resolved value renders as sanitised HTML. Required. |

### Link a Cell

1. Open the value column's **General** tab.
2. Write an `a` tag under **Value(s)** and put the Data Picker fields inside it, for example `<a href="{{website}}">{{name}}</a>`.
3. Switch to Preview mode and click a cell to check the link.

Each row resolves its own link, and every link opens in a new tab. A row whose URL resolves empty, or to a bare `#`, shows the text without a link, so rows with no website still show the name.

### Action Column (General tab)

An action column renders one button per configured action, repeated for each row. A button shows an icon, a text label, or both.

| Field | Description |
|---|---|
| **Header** | Column header text. Supports the Data Picker. |
| **Actions** | The list of action buttons for each row. Click **Add Action** to append; each action is its own collapsible block. |

Each action has:

| Setting | Description |
|---|---|
| **Icon** | Pick from grouped **Actions**, **Communication**, **Files**, and **Status** icons, including navigation, messaging, file, and state symbols. Required unless the action has a **Label**; the **No icon** choice appears only while the Label holds text. |
| **Custom icon** | Custom image URL. Shown when Icon is **Custom** and supports the Data Picker. |
| **Label** | Optional button text. Supports the Data Picker and resolves per row, so each row can show its own text. Shown after you pick an Action Type. |
| **Icon position** | **Before the text** (default) or **After the text**. Shown only when the action has both an Icon and a Label. |
| **Action Type** | **Go to view** (navigate within the interface), **Go to URL** (open a URL), or **Send request** (send a POST without leaving the table). |
| **View Name** | Destination view dropdown. Shown when Action Type is **Go to view**. |
| **Params** | Key/value pairs passed to the destination view. Shown when Action Type is **Go to view**. |
| **URL** | Destination URL. Shown when Action Type is **Go to URL**. Supports the Data Picker. |
| **Request URL** | Absolute HTTP or HTTPS endpoint. Shown when Action Type is **Send request**. Supports the Data Picker for per-row values. |
| **Body Data** | Optional JSON payload. Configure it as JSON or key-value pairs and use the Data Picker for row values. Include the row's identifier because OneClick metadata identifies the view resource, not the row. Leave empty to send no configured body. |
| **Omit OneClick metadata envelope** | Leave off to send Body Data alongside OneClick metadata. Turn on to send only Body Data to an endpoint that expects a bare payload. |
| **Disabled** | Data Picker expression evaluated per row. A row resolving to `true`, `yes`, or `1` starts with a muted, unclickable button; any other value keeps it enabled. |
| **Disable button** | Choose **Never**, **After click**, or **After successful response**. |
| **Disable scope** | When disabling is enabled, affect only the clicked button or the same configured action on every row. |
| **Disabled appearance** | Choose **Neutral**, **Success**, or **Destructive** for the clicked button's disabled state. Other rows use Muted. |
| **Refresh after success** | Reload the view after a successful request and restore its scroll position. Redirect responses navigate instead. |
| **Require confirmation** | Shown when Action Type is **Send request**. Turn on to ask the reader before the request is sent. |
| **Title**, **Description** | The dialog's question and its optional explanation. Both support the Data Picker and resolve per row. |
| **Confirm Button Label**, **Confirm Button Variant** | The confirming choice. Defaults to "Confirm" and **Default**. |
| **Cancel Button Label**, **Cancel Button Variant** | The cancelling choice. Defaults to "Cancel" and **Outline**. |

### Label a Row Action

1. Add an action column, click **Add Action**, and pick an **Action Type**. The **Label** field appears after the type is set.
2. Write the button text under **Label**. Use the Data Picker for per-row text, for example `Open {{order_name}}`.
3. Optional: set **Icon position** to **After the text** when the icon belongs on the right. Only the icon moves; the text keeps its place.
4. Optional: for a text-only button, open the **Icon** picker and choose **No icon**. The choice is offered only while the Label holds text, and clearing the Label writes the **View** icon back.

Labels work on all three action types. On a **Send request** action the progress, success, and failure icons replace the icon only — the text stays in place while the request runs.

A Label that resolves empty on some rows leaves those rows icon-only. Without an Icon, such a row shows a warning instead of the button, because there is nothing left to render. Either widen the Data Picker path or keep an Icon for the rows that have no text.

The label is presentation only. It becomes the button's accessible name, but the request payload is unchanged: OneClick metadata still sends `button_name` as the action column's header.

### Send a Request from a Table Row

1. Add an action column, click **Add Action**, and set **Action Type** to **Send request**.
2. Enter an absolute HTTP or HTTPS **Request URL**. Use the Data Picker to insert values from the current row.
3. Optional: configure valid JSON under **Body Data**. Include the row identifier because OneClick metadata identifies the view resource, not the table row.
4. Enable **Omit OneClick metadata envelope** only when the endpoint expects the Body Data as a bare payload.
5. Optional: bind **Disabled** to a Data Picker value when some rows must start disabled. A row whose value resolves to `true`, `yes`, or `1` renders a muted button that cannot be clicked; any other value keeps the button enabled. Combined with **Refresh after success**, an endpoint that flags the row as disabled in the refreshed data keeps it disabled even after a page reload.
6. Configure **Disable button**, **Disable scope**, and **Disabled appearance** when duplicate requests must be prevented.
7. Enable **Refresh after success** when the view should reload after a successful response.
8. Optional: turn on **Require confirmation** when an accidental click must not send the request. See [Confirm a Request Action](#confirm-a-request-action) below.
9. Test the action in the Test view. Request actions are disabled in Preview and work only in the Test and published views.

A Request action sends a POST through the Interface Builder backend. The clicked icon shows progress, then brief success or error feedback. Response messages appear as toasts; a response containing a redirect opens its target view. See [HTTP Response Format](../../reference/data-binding/http-response-format.md).

OneClick-level and system headers are included automatically; Request actions do not support per-action headers. Protect the endpoint as described in [Securing Your Endpoint](../../explanation/securing-your-endpoint.md).

### Confirm a Request Action

Use a confirmation when a click deletes, sends, or approves something. Only **Send request** actions offer it; **Go to view** and **Go to URL** open something the reader can leave again.

1. Open the action and turn on **Require confirmation**. The first enable fills in "Are you sure?", **Confirm**, and **Cancel**, so the dialog is usable right away.
2. Write the **Title** as the question the reader answers. Use the Data Picker to name the row: `Delete order {{order_name}}?` asks about that row's own order.
3. Optional: add a **Description** for what the request will do. It also supports the Data Picker and resolves per row.
4. Optional: set **Confirm Button Label** and **Confirm Button Variant** — pick **Destructive** for a delete — and the matching **Cancel** fields.
5. Test the action in the Test view: the dialog must open, and the request must reach your endpoint only after **Confirm**.

The dialog is a gate in front of the request, not a report on it. Confirm sends the request once and the row's icon reports progress, success, or failure as usual. Cancel and Escape send nothing and change nothing — including the **Disable button** state, which starts only after Confirm, so a cancelled dialog leaves the button usable.

A row that the **Disabled** expression pre-disables never opens the dialog. A Title that resolves empty falls back to "Are you sure?", and a Description that resolves empty is left out of the dialog. The **Confirm** and **Cancel** labels are plain text and do not support the Data Picker.

### Subrow Column (General tab)

A subrow column expands nested data as child rows under each row.

| Field | Description |
|---|---|
| **Value(s)** | The path to the nested array inside each row item. Required. |

Subrow columns have no Header, no actions, and no Sorting tab. Only one subrow column is allowed per table.

## Per-Column Styling Tab

| Setting | Description |
|---|---|
| **Width** | Optional column width -- a number (pixels) or a percentage. Leave empty for **Auto**. |
| **Cell Alignment** | Override the table's Default Cell Alignment for this column (Left / Center / Right). |
| **Cell Padding** | Switch. When on, four pixel inputs (**Top / Right / Bottom / Left**) appear and override the table-level padding for this column. |

## Per-Column Sorting Tab

Subrow columns do not have this tab.

| Setting | Description |
|---|---|
| **Allow sorting** | Switch that lets users sort by this column. |
| **Sort by this column** | Checkbox. Makes this the default sort column when the table loads. Shown when Allow sorting is on. |
| **Sort direction** | **Ascending** or **Descending** -- the default sort order. Shown when Sort by this column is on. |
| **Custom sort value** | Switch. When on, a **Sort value** Data Picker appears. Use this to sort by a different field than the one displayed (for example sort by a raw number while displaying a formatted currency). |

## Per-Column Sum Tab

Value columns only. An enabled sum adds one cell to the **Sum row** at the bottom of the table. The total covers every row of the Target Array, so sorting never changes it, and a table with no rows shows no Sum row.

Every field on this tab has an info icon beside its label. Hover it, or reach it with the keyboard, to read what the field does without leaving the builder.

### Total a Column

1. Select the value column in **Manage Columns** and open the **Sum** tab.
2. Turn **Show sum** on.
3. Bind **Sum value** to the raw source field of the row -- for example the number behind a formatted price. Non-numeric values are skipped, so a field holding `"1 200 €"` totals to nothing.
4. Leave **Format** at **Plain number**, or pick **Currency**.
5. Close the dialog and check the table's bottom row.

### Format the Total as Currency

1. Set **Format** to **Currency**.
2. Fill in **Locale** -- for example `fi-FI` for space grouping, a decimal comma, and a trailing symbol, or `en-US` for comma grouping, a decimal point, and a leading symbol. The Locale never decides which currency is shown, only how it is written.
3. Fill in **Currency** with the ISO 4217 code -- for example `EUR` or `SEK`.

An empty or unknown Locale or Currency renders no total at all. If the Sum row cell stays blank, check these two fields first.

### Wrap the Total in Text

1. Write **Prefix** for text before the total, and **Suffix** for text after it.
2. Add the spacing yourself: `Total ` needs the trailing space, and ` / month` needs the leading space.

Both apply in the plain format and in the currency format, and both accept Data Picker values. Switching **Format** back to **Plain number** clears the Locale and the Currency, but keeps the Prefix and the Suffix.

### Name the Sum Row

Set the table-level **Sum label** in the Configuration sub-tab -- the column tabs have no label field. The label renders in the first visible column that has no sum, action columns included. When every visible column has a sum, the label has nowhere to go and is left out.

## Per-Column Hover Card Tab

Value columns only. The tab has one optional field, **Hover card**: content that opens when a reader hovers a cell's value with the pointer. See [Hover Card Tab](../../reference/block-types/table.md#hover-card-tab-per-column) for the rules.

### Add a Hover Card to a Column

1. Open the value column's **Hover card** tab.
2. Write the card under **Hover card**. Put the Data Picker fields of the row item inside it, for example `<b>{{owner}}</b><br><a href="{{profile_url}}">Profile</a>`. HTML is allowed.
3. Switch to Preview mode and hover a cell's value.

Each row resolves its own card. A row whose card or value resolves to nothing shows no underline and no card. The card opens for a pointer only, and table export does not include it.

## Per-Column Conditional Tab

| Setting | Description |
|---|---|
| **Enable conditional visibility** | Turns visibility rules on or off for this column. |
| **Condition** | A Data Picker expression evaluated at render time. The column is hidden when the value is empty or `"false"`. |

## Let a Reader Export the Table

1. Select the Table block and open the **Configuration** sub-tab.
2. Turn **Allow export** on.

An **Export** menu now renders on its own right-aligned row between the Table Title and the table. It offers the reader two ways out:

* **Download CSV** writes a `<table-title>-<YYYY-MM-DD>.csv` file in the browser.
* **Copy to clipboard** puts the same table on the clipboard, tab separated, ready to paste into Excel or Google Sheets.

Both carry every row of the Target Array in the sorting the reader sees, and the visible value columns only. Action columns, the subrow column, a column hidden by its Conditional tab, the Cell hover cards and the Sum row are all left out. Nothing is requested from the server: the export is built from the table already on screen.

The menu stays visible while the Target Array is empty, but is disabled. For the exact file format, see [Table export](../../reference/block-types/table.md#table-export) in the reference.

## Borders and Padding

Open the block's **Style** sub-tab to configure the table's borders and the table-only padding control:

* **Top / Right / Bottom / Left Border** -- the standard outer-frame borders, each with Width / Style / Color.
* **Row border** -- lines between rows, same controls.
* **Cell border** -- lines between cells, same controls.
* **Global Cell Padding** -- switch. When on, four pixel inputs (Top / Right / Bottom / Left) apply to every cell unless a column overrides them via its own Styling > Cell Padding.

## Style and Visibility

The Table block uses the standard **Style** sub-tab (background, borders, radius, plus the table-specific borders and padding above) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../layout/block-styles.md) and [Conditional Visibility](../visibility/conditional-visibility.md).

For the full per-field reference, see the [Table block reference](../../reference/block-types/table.md).

---

---
url: /how-to/layout/areas.md
---
# Using Areas to Group Rows

> **Type:** How-to | **Audience:** Interface builder user | **Goal:** Group rows into named areas, control their visibility, and repeat them for each item in your data

## What is an Area?

An area is a named group of rows in your view. Areas let you:

* Visually organise sections of a view on the canvas (each area has a colour).
* Show or hide a whole section at once with a single condition.
* **Repeat** a whole section for every item in a list -- for example, render one card per deal, one row per attachment.

Each area has:

* A **Name** for identification.
* A list of **Rows** it contains (you pick them from the row selector).
* A **Color** for visual distinction on the canvas.
* Optional **Conditional Visibility** settings.
* Optional **Loop** settings.

## Creating an Area

1. Click the **Areas** button (top-right of the canvas, the badge shows how many areas the view already has).
2. Add a new area from the list and give it a **Name** that describes the section (for example, `Header`, `Body`, `Line items`, `Summary`).
3. Build up the row range:
   * Click numbered row buttons in the **Rows** visual selector to toggle them in or out. Rows already owned by another area appear in that area's colour and are disabled (areas cannot overlap).
   * Use the **Add Row N (above/below)** quick-action buttons that appear for adjacent unowned rows.

The area appears as a coloured overlay around the selected rows, with a labelled badge above the first row. Clicking that badge selects the area and opens **Area Settings**.

## Switching Between Areas

When the view has more than one area, the top of **Area Settings** shows a dropdown next to the **Area Settings** title. Open it to jump straight to another area; the canvas scrolls to the area's first row.

## Area Colours

Pick a colour from the swatches in **Area Settings** to tell areas apart on the canvas. The colour only affects the builder -- end users of the view never see it. The eight available colours, in order, are:

* **Blue** (default)
* **Green**
* **Purple**
* **Orange**
* **Red**
* **Teal**
* **Pink**
* **Gray**

## Conditional Visibility

You can show or hide a whole area based on data.

1. Open **Area Settings** by clicking the area's badge on the canvas.
2. Toggle **Enable conditional visibility** on.
3. In **Condition**, use the Data Picker to build an expression. The area is hidden when the expression evaluates to an empty string or `"false"`; any other value shows it.
4. Pick a **When hidden** mode:
   * **Hide (keep space)** -- rows become invisible but keep their vertical space in the layout.
   * **Remove** *(Recommended)* -- rows are removed entirely; no gap is left.

## Looping an Area

A loop makes the whole area repeat -- once per item in a list, or a fixed number of times. This is how you render "one row per record" in a view.

1. Open **Area Settings** and scroll to the **Loop** section.
2. Toggle **Enable loop** on.
3. Pick a **Loop mode**:
   * **Array** -- repeat once for each item in a data array.
   * **Count** -- repeat a fixed number of times.

### Array mode

Use Array mode when you have a list of records (for example, deals, products, line items) and want the area to appear once per record.

1. Set **Loop mode** to **Array**.
2. Fill **Target array** with the Data Picker -- pick an array from your data source (for example, `deals` or an API response field).

The rows inside the area are rendered once for each item in the array. Inside the area, Data Picker placeholders resolve against the current iteration's item, so a placeholder like `{{item.title}}` shows a different title in each repetition.

If the target array is empty, the area renders nothing (every row inside is hidden).

### Count mode

Use Count mode when you want the area to repeat a known number of times regardless of whether there is a matching list.

1. Set **Loop mode** to **Count**.
2. Fill **Loop count** with the Data Picker -- pick a number from your data, or type a literal number.

The rows inside the area are rendered that many times.

### Iteration index

Inside a looping area you can reference the current iteration number (starting at **1**) via the Data Picker's **loop item** tab -- the icon is a repeat / loop symbol and the tab only appears inside a looping area. Use it to number items, conditionally style the first or last one, or drive other logic.

### Iteration cap

A single looping area is capped at **1,000** iterations. If the target array or count would produce more, the extras are dropped and a warning is written to the browser console. If you hit the cap, reduce the list length or count in your data source.

### Forms inside a looping area

If the looped rows contain form inputs, each iteration renders its own copy of every input. The first iteration keeps the original field names; later iterations submit under `_loop_1`, `_loop_2`, … suffixes. The submission also carries an `oc_loop` array — one object per iteration — so your endpoint has one predictable place to read the looped values. See [Form Submission Types](../../reference/data-binding/form-submission-types.md#forms-inside-a-looping-area) for the exact payload shapes.

## Preventing Overlap

Areas cannot overlap. The row selector disables buttons for rows already owned by another area, and the **Add Row N** quick-actions only show for adjacent unowned rows. Resize or delete the conflicting area before adding it to a new one.

## Deleting an Area

Click **Delete Area** at the bottom of **Area Settings**. This removes the area grouping only -- the rows themselves stay on the canvas.

---

---
url: /how-to/layout/block-styles.md
---
# Styling Individual Blocks

> **Type:** How-to | **Audience:** End-user | **Goal:** Customize a single block's appearance

## Opening the Style Sub-tab

1. Select a block on the canvas.
2. In the Block Settings panel, switch to the **Style** sub-tab (next to **Configuration** and **Visibility**).

> Badge and Alert blocks use variant-based styling, so their **Style** sub-tab shows an info card explaining that custom block styles are not applied. See the [Badge](../../reference/block-types/badge.md) and [Alert](../../reference/block-types/alert.md) reference pages for the variants they offer instead.

## Background Color

1. Click the **Background Color** swatch and pick a colour.
2. Tick the **Transparent** checkbox to clear the background.

The **Image**, **Avatar**, and **Divider** blocks omit the Background Color row entirely -- the Style sub-tab simply does not render it for them.

## Font Settings

Text-based blocks (Title, Paragraph, Button, Input, HTML, Table, Hover Card, Chart, Navbar) have font controls:

| Setting | Description |
|---|---|
| **Font Options** | A toggle group with **Bold**, **Italic**, and **Underline**. |
| **Font Size (px)** | Text size in pixels. |
| **Font Color** | Pick a colour, or tick **Transparent** to clear the colour. |

The **Image**, **Avatar**, and **Divider** blocks have no text, so the font controls are hidden.

## Borders

Each block has four independent border sides: **Top Border**, **Right Border**, **Bottom Border**, and **Left Border**.

1. Turn a side on with its switch. The width / style / colour fields appear underneath.
2. Configure:
   * **Width (px)** -- border thickness in pixels. New blocks default to `1`, so toggling a side on draws a visible border immediately.
   * **Style** -- pick **Solid**, **Dashed**, or **Dotted**.
   * **Color** -- a colour picker.

### All borders

Turn the **All borders** switch on (above the four side switches) to drive all four sides from a single Width / Style / Color card. The four per-side switches and their cards are hidden while All borders is on; turning it back off restores them with their previous values. Tables (which have extra Row / Cell border switches) do not show the All borders option.

## Table Borders and Padding

The Table block adds three controls inside its **Borders** section on top of the four side borders:

* **Row border** -- lines between rows (same Width / Style / Color controls).
* **Cell border** -- lines between cells (same controls).
* **Global Cell Padding** -- when on, four pixel inputs (**Top / Right / Bottom / Left**) apply to every cell unless a column overrides them via its own Styling > Cell Padding.

## Border Radius

**Border Radius (px)** rounds the block's corners. A value of `0` leaves them square; large values produce circular shapes (useful for Avatar and Image).

## Padding

Padding adds space between the block's content and its outer edge -- once a border is drawn, padding is the distance between the border and the text. Each side has its own pixel input: **Top (Px)**, **Right (Px)**, **Bottom (Px)**, **Left (Px)**. Defaults to `0` on every side.

Turn the **All padding** switch on to drive all four sides from a single **Padding (px)** input. The four per-side inputs are hidden while All padding is on; turning it back off restores them with their previous values.

## Overriding Global Styles

When the view has **Enable Global Styles** turned on with a font size or font colour set, every block inherits those values by default.

To override a global value on a specific block:

1. In the block's **Style** sub-tab, look for a `Global: <value>` badge next to **Font Size (px)** or **Font Color** -- for example `Global: 16px`, or for the colour a small swatch followed by the hex code.
2. A **Use custom style** switch sits beneath the badge. Turn it on, and the block's own input becomes editable.
3. Type the per-block value.

When the switch is off, the block uses the global value and its own input is disabled. The same **Use custom style** label is used for both Font Size and Font Color overrides; the switch's effect is local to the field it sits beside.

See [Using Global Styles](global-styles.md) for the dialog itself and the per-row gap overrides.

---

---
url: /how-to/layout/global-styles.md
---
# Using Global Styles

> **Type:** How-to | **Audience:** End-user | **Goal:** Apply consistent styling across the whole view

## Opening Global Styles

1. Click the **View settings** tab in the right panel.
2. Click the **Global Styles** button. The badge next to the button shows the current state -- **Off**, **On (no values set)**, or **On (N/4 set)**.
3. The **Global Styles** dialog opens.

## Configuring Styles

The dialog has a master switch at the top:

* **Enable Global Styles** -- when off, the rest of the dialog is dimmed and none of the values apply. The values you set are kept, so you can re-enable later without losing them.

Below the switch, four fields set the view-wide defaults. Leave any field empty (the placeholder reads `Not set`) to skip that default. The badge on the dialog tracks how many of the four are configured.

| Setting | Description |
|---|---|
| **Font Size (px)** | Default text size, applied to every block. |
| **Font Color** | Default text colour. Set via the colour picker or by typing a hex value; click **Clear** to reset. |
| **Row Gap (px)** | Vertical spacing between rows. |
| **Column Gap (px)** | Horizontal spacing between columns inside a row. |

## Apply to All Views

Click **Apply to all interfaces** at the bottom of the dialog to copy the current Global Styles to every other view in this interface. This overwrites their existing Global Styles and is disabled until **Enable Global Styles** is on.

## Load from the Main View

On non-main views, **Load from main interface** appears below **Apply to all interfaces**. Click it to copy Global Styles from the main view into the one you are editing. The current values are replaced.

## Overriding Global Styles on a Single Block

Individual blocks can opt out of the global font size and font colour:

1. Select a block and open its **Style** sub-tab.
2. When a global value is active, a `Global: <value>` badge appears next to **Font Size (px)** or **Font Color** -- for example `Global: 14px`, or for the colour a small swatch followed by the hex code.
3. A **Use custom style** switch shows up next to the badge. Turn it on, and the block's own input becomes editable so you can override the global value just for this block.

The **Use custom style** label is the same for both fields; the switch's effect is local to the field it sits beside.

## Overriding Global Gaps on a Row

Rows can opt out of the global row gap and column gap from **Row Settings**:

* **Exclude from global row gap** -- only appears when **Row Gap** is set globally. Detaches this row from the global vertical spacing.
* **Exclude from global column gap** -- only appears when **Column Gap** is set globally. Detaches this row's columns from the global horizontal spacing.

---

---
url: /how-to/layout/rows-and-columns.md
---
# Managing Rows and Columns

> **Type:** How-to | **Audience:** End-user | **Goal:** Control layout structure

## Adding a Row

Hover the gap between two rows on the canvas (or above the first row) — a small `+` button appears. Click it to open the **Add row** dialog and pick a layout:

| Layout | Description |
|---|---|
| **Full width** | Single column at 100% width |
| **Two columns** | Two equal columns, 50% each |
| **Three columns** | Three equal columns, 33% each |
| **Sidebar left** | 25% on the left, 75% on the right |
| **Sidebar right** | 75% on the left, 25% on the right |
| **Form** | Adds a Form Start + Form End marker pair (hidden when you are already inside a form) |

If you need a row with more than three equal columns, start with one of the layouts above and use **Add column** (see [Adding More Columns to a Row](#adding-more-columns-to-a-row) below).

## Reordering Rows

Drag a row up or down on the canvas to reorder it. Areas and form boundaries adjust automatically as the rows move.

## Opening Column Settings

Each column has a small indicator bar above it that shows the column number and width. Click the indicator bar to select the column and open **Column Settings** in the right sidebar. You can also open the column's **"…" menu** on the right side of the indicator bar and pick **Settings**.

## Column Width

In **Column Settings**, the **Width** control has three modes:

1. **Auto** — the column sizes itself automatically.
2. **%** — a percentage of the row's width (1 to 100).
3. **px** — a fixed width in pixels (minimum 10).

Pick the mode from the Width dropdown, then type in the value.

## Column Padding

Every column has its own inner padding, set from Column Settings:

* **Padding Top** (px)
* **Padding Bottom** (px)
* **Padding Left** (px)
* **Padding Right** (px)

## Column Alignment

Two dropdowns in Column Settings control where inside the column its block sits:

* **Horizontal Align** — **Left**, **Center**, or **Right**.
* **Vertical Align** — **Top**, **Middle**, or **Bottom**.

When the row has multiple columns, click **Apply style to all columns** at the bottom of Column Settings to copy this column's padding, width, and alignment onto the other columns in the row.

## Adding More Columns to a Row

Two ways to add a column to an existing row:

* **From the row's "…" menu** — open the row's dropdown menu (the three-dot button on the row label) and pick **Add column**. A new column is appended to the row.
* **From a column's "…" menu** — open a column indicator bar's dropdown menu and pick **Add column left** or **Add column right** to insert the new column relative to the selected one.

Existing columns keep their widths; the new column is added at Auto width, which you can adjust from its Column Settings.

## Row Padding

Rows have their own padding too. Open the row's **"…" menu** (the three-dot button on the row label) and choose **Settings** to open **Row Settings**. You can also click the row label directly. The four **Padding Top / Bottom / Left / Right** fields apply around all columns in the row.

## Moving Blocks Between Columns

Drag a block from one column onto another column to move it. The original column becomes empty and the destination column shows the moved block.

---

---
url: /how-to/data/data-picker.md
---
# Using the Data Picker

> **Type:** How-to | **Audience:** End-user | **Goal:** Insert dynamic data into block settings

This guide covers the everyday picker workflow. For the full breakdown of every tab, type filter, and badge — see the [Data Picker reference](../../reference/data-binding/data-picker.md).

## Inserting Your First Placeholder

1. Click into any block setting that supports the Data Picker — for example a Title block's **Text** field.
2. The picker opens as a tooltip beside the field.
3. Pick the tab whose data you want (Deal, Organization, Person, User, Custom, Search Params, Variable, Functions, Context, or — inside a looping area — Loop item).
4. Click a field in the tree. A blue badge appears in the field as a single unit; the placeholder it represents (for example `{{deal.title}}`) is what gets resolved at render time.

On a [floating window button](../../explanation/floating-window-buttons.md) the **Deal**, **Organization** and **Person** tabs are not in the strip at all, because that button's views get no Pipedrive record.

## Combining Static Text and Placeholders

You can mix plain text with badges in the same field. Type freely before, between, and after badges — the picker treats text as text and badges as atomic units.

A typical Paragraph **Value** might read:

```
Deal: {{deal.title}} — {{deal.value}} {{deal.currency}}
```

At render time the three placeholders resolve to live values from the deal record (for example `Deal: Legendary 1995 — 3193 EUR`).

## Removing a Placeholder

Three ways:

* Click the small **×** on the badge.
* Place the cursor after the badge and press **Backspace** — the whole badge disappears in one keystroke.
* Select across the badge and type — the badge is replaced by whatever you type.

## Editing Complex Expressions in the Larger Dialog

Once a field has more than one or two placeholders — or when you start mixing in functions like `if`, `formatCurrency`, or `daysBetween` — the inline picker gets cramped. Click the **expand** icon at the right edge of the Data Picker input to open the same field in a larger dialog. Toggle **Show result** to preview the rendered value (resolved against the active sample data) and **Show whitespace** to make spaces visible. For the **HTML** block specifically, **Show result** renders the compiled output as actual HTML (using the same sanitiser as the live view) so you can see the visual result without switching to Preview mode — see [How to Use the HTML Block](../blocks/html.md#previewing-without-leaving-the-dialog).

The dialog ignores clicks outside, so you can keep clicking around the canvas without losing your edits — only the minimize icon (top right) closes it.

**Show whitespace** is useful when something looks "off" in the rendered output and you suspect a stray or missing space — for example a placeholder that touches the next word, or two spaces between values. Switch the toggle on to see every space in the field as a small dot. The toggle is a **global** preference that applies to every Data Picker field in the builder and is remembered across reloads, unlike **Show result** which is set per field.

## Working Inside a Looping Area

When the field is inside an [area with looping enabled](../layout/areas.md#looping-an-area), the picker grows an extra **Loop item** tab (a repeat icon). Open it to:

* pick a field of the current iteration's array item (the `index` field is shown last in the list) — placeholders resolve per repetition, so `{{deal.products.name}}` reads a different product on each loop;
* pick `index` — the iteration number, starting at **1**.

If the field is **not** inside a looping area, the Loop item tab does not appear.

## Type-Filtered Contexts

Some block settings only accept a specific data type. The picker greys out fields that do not match:

* **Table > Target Array** and **Area > Loop > Target array** accept only arrays.
* **Visibility > Condition** accepts any value but is most useful with strings or booleans.
* Most text-based settings exclude objects from the clickable set — clicking an object's badge only expands its children.

You do not choose the filter manually — the surrounding setting decides it for you.

## Reusing the Last-Opened Tab

The picker remembers which tab you opened last across fields. If you spend a session inserting Deal fields, the next picker you open also lands on the Deal tab. Switch tabs once and that becomes the new default. Useful when you are building a row of similar inputs.

---

---
url: /how-to/data/external-data-source.md
---
# Configuring an External Data Source

> **Type:** How-to | **Audience:** Advanced end-user | **Goal:** Connect to external APIs

## Opening the URL Configuration Dialog

1. Open the **View settings** tab in the right panel.
2. Click the **Configure URL** button (next to **View URL**, with the active method shown as a `POST` / `GET` badge). The **URL Configuration** dialog opens.

The dialog is divided into cards, in this order: **View end-point configuration**, **Query Parameters**, and **Manage Headers**. Click **Save** in the top-right to apply changes, or **Cancel** to discard them.

## HTTP Method

In the **View end-point configuration** card, pick **GET** or **POST** with the toggle buttons next to **HTTP Method** (default: **GET**).

* **POST** -- sends a request body with deal/person/organization context.
* **GET** -- appends parameters to the URL.

## End-point URL

Enter the full URL of the external API endpoint in the **End-point URL** field. This is the URL the view calls to fetch data when it opens. The field supports the Data Picker, so you can build the URL from variables.

## URL Active

Turn on the **URL Active** switch to enable the external data source. The helper text reads *"When disabled, no fetch will be made on view load."* When off, no request is made and the **Custom** tab in the Data Picker remains empty.

## Omit oneclick metadata

The **Omit oneclick metadata** switch tells Interface Builder not to add `event_id`, `resource_id`, or other OC-specific fields to the request body. Turn this on for APIs that reject unknown fields, such as the Pipedrive API v2.

## Query Parameters

In the **Query Parameters** card, click **Add Parameter** (or **Add Your First Parameter** when the list is empty) to append a row.

* Each row has a **Key** input and a **Value** input. Values support the Data Picker.
* The **Trash** icon at the end of the row removes that parameter.
* Keys must be 1--255 characters, values 1--512 characters. Duplicate keys are flagged with `Duplicate key not allowed`.

## Manage Headers

In the **Manage Headers** card, click **Add Header** (the empty state shows *"No headers configured yet"*). Each header has:

* **Key** -- the header name. Must contain only letters, numbers, and hyphens, cannot start or end with a hyphen, and cannot start with `x-oc-` (reserved for system headers).
* **Value** -- the header value. Supports the Data Picker, so you can use dynamic values such as `{{variable.api_key}}`.

::: info OneClick-level headers are merged in automatically
If the OneClick button this interface is attached to has its **Headers** toggle enabled (configured outside the builder, on Pipedrive's **Edit a Button** page), every header listed there is sent with this request. You only need to set per-call headers here for values that differ between requests. See [OneClick-Level Headers](../../explanation/architecture.md#oneclick-level-headers) for the merge order and the reserved `x-oc-*` keys.
:::

## Using the Data

Once the URL is active, the external API response fields appear in the Data Picker under the **Custom** tab.

1. Open any Data Picker field.
2. Switch to the **Custom** tab.
3. Browse the response fields and click to insert chips that compile to placeholders like `{{custom.field_name}}`.

The data is fetched at render time using the configured method, headers, and parameters. The response is parsed and made available as selectable fields.

## How the Response Reaches the View

When the view opens, the builder calls your data source URL and then waits for your response. The view stays in a loading state until the response arrives, and renders as soon as it does. The total wait is capped at roughly **20 seconds**.

If nothing arrives in that window, the user sees a `Request timed out. No custom data received.` toast. If the data source URL returns an HTTP status outside 2xx, the user sees `Data loading failed (status 500)` (or whichever status came back).

For the exact request shape your endpoint receives — body, headers, system metadata — see the [View Data Source reference](../../reference/data-binding/view-data-source.md). For the parallel-fetch state machine and the differences between Test, Preview, and live render, see [External Data Flow](../../explanation/external-data-flow.md).

## Responding with a Message View

Sometimes the "data" you have for the user is a message, not records -- the record cannot be found, the session expired, or a step is still missing. Return a message-view response instead of real data:

```json
{
  "oneclick_data": {
    "error_message": {
      "title": "Account not found",
      "message": "We could not find that account. <a href=\"/accounts\">Choose another</a>."
    }
  }
}
```

The view shows a full-page message view with your title and message, plus **Go Back** and **Retry** buttons. Use this instead of a toast when the user cannot proceed -- they cannot miss a full-page card. The object form also accepts optional `hideRetry: true` and `hideBack: true` flags to hide the corresponding button.

If you only need a single-line message, use the string form. It gets the title "Error":

```json
{
  "oneclick_data": {
    "error_message": "Something went wrong"
  }
}
```

### Lists and variants

To list several items, send `message` as an array of strings. The message view shows them as a bullet list. Add `variant` to change the colours and icon -- `destructive` (default), `warning`, `info`, `success` or `default`:

```json
{
  "oneclick_data": {
    "error_message": {
      "title": "A few things before we continue",
      "message": ["Add a delivery address", "Choose payment terms"],
      "variant": "info"
    }
  }
}
```

### `message_view` for messages that are not errors

When the message is not an error -- for example a `success` or `info` note -- send it as `message_view` instead of `error_message`. The fields and the view are the same; only the name is neutral. `message_view` takes the object form only:

```json
{
  "oneclick_data": {
    "message_view": {
      "title": "Almost there",
      "message": "Customer created. Add a contact person and press Retry.",
      "variant": "success"
    }
  }
}
```

* `variant` changes the look only. The buttons stay **Go Back** and **Retry**, and the response is still not a success response.
* A missing `variant` is `destructive`, as with `error_message`.
* If a response carries both fields, `error_message` wins and `message_view` is ignored.

Both fields support a small HTML subset in the message text. See the [Messages & Toasts reference](../../reference/data-binding/messaging.md) for the allowed tags and link behaviour, and [HTTP Response Format → `message_view`](../../reference/data-binding/http-response-format.md#message-view) for all rules.

## Responding with a Redirect

If the data source should divert the user to another view instead of rendering, return a redirect:

```json
{
  "oneclick_data": {
    "redirect_view": {
      "id": "target-view-id",
      "params": { "deal_id": "123" }
    }
  }
}
```

The view shows a "Redirecting..." toast and navigates to the target view. If the target ID does not exist, the view falls back to a full-page message view with the message *"View with ID ... was not found"*.

See [HTTP Response Format](../../reference/data-binding/http-response-format.md) for the full list of accepted shapes.

---

---
url: /how-to/data/messages-and-toasts.md
---
# Sending Messages and Toasts from Your Backend

> **Type:** How-to | **Audience:** Interface builder user | **Goal:** Decide exactly what your API should return so the user sees the right message in the right place

Interface Builder shows user-visible messages in three places:

1. **Toast** — a short notification that pops up in a corner of the view.
2. **Inline alert** — a coloured box that replaces the form after submission.
3. **Full-page message view** — takes over the view and offers Retry / Go Back buttons.

You decide which one appears by combining the button's settings with the shape of the response your API returns.

## Do I need `oneclick_data`?

No — not for a plain toast. **A toast can come from several simpler shapes**; the `oneclick_data` envelope is only required when you want:

* a **redirect** (navigate the user to another view) on a URL button or a form submit, or
* a **full-page message view** (on a view data source or on a form submission error).

For a plain toast — success or error — a top-level response with a `message` is enough. For URL buttons, even a plain text body (not JSON) works.

## Two-minute recipes

Pick the row that matches your situation.

| I want… | Button setup | Return from API |
|---|---|---|
| A success toast after form submit | Form Submit, **After submission = Wait for response** | `{ "message": "Saved." }` |
| A coloured toast with a title | same | `{ "message": "Profile is up to date.", "title": "Saved", "variant": "success" }` |
| Replace the form with a "thank you" screen | same + **Show message after submission** ON | same shape as above |
| Navigate to another view after submit | Form Submit, **After submission = Wait for response** | `{ "view_id": "receipt-view" }` |
| Show a toast, then navigate | same | `{ "oneclick_data": { "message": "Done.", "redirect_view": { "id": "receipt-view" } } }` |
| Error toast on failed submit | same + **non-2xx** HTTP status | `{ "message": "Email already in use." }` |
| Full-page error after failed submit (view with a data source) | same + **non-2xx** HTTP status | `{ "oneclick_data": { "error_message": { "title": "Blocked", "message": "…" } } }` |
| Quick toast after URL button click | URL Button | plain string body: `"Added to cart"` — **or** `{ "message": "Added to cart" }` |
| Redirect after URL button click | URL Button | `{ "oneclick_data": { "redirect_view": { "id": "next" } } }` |
| Toast then redirect after URL button click | URL Button + **Wait page transition** ON | Stream interim toasts via the polling endpoint, then return `{ "oneclick_data": { "redirect_view": { "id": "next" } } }`. URL buttons drop a sibling `message` next to `redirect_view`. |
| Full-page error on view data source | View with a data source | `{ "oneclick_data": { "error_message": { "title": "…", "message": "…" } } }` |

The rest of the page explains each case in detail.

***

## Form submit responses

For form submits the submit button's **After submission** setting decides what the builder does with your response.

### After submission = Wait for response

All the shapes below are accepted. Return the simplest one that fits.

**Just a toast** — return a JSON body:

```json
{ "message": "Profile saved" }
```

**Coloured toast** — add a variant:

```json
{ "message": "Profile saved", "variant": "success" }
```

`variant` can be `default`, `destructive`, `info`, `success`, or `warning`.

**Toast with a title** — add a title:

```json
{ "message": "Profile is up to date.", "title": "Saved", "variant": "success" }
```

* With **Show message after submission** off → shown as a toast where `title` is the bold first line and `message` is the description.
* With **Show message after submission** on → the form is replaced by an inline alert containing the title and message. The view scrolls to it automatically.

**Just a navigation** — no message, just send the user to another view:

```json
{ "view_id": "target-view" }
```

**Toast plus navigation** — return the `oneclick_data` envelope. This is the only shape that carries both:

```json
{
  "oneclick_data": {
    "message": "Saved.",
    "redirect_view": { "id": "receipt", "params": { "order_id": "4321" } }
  }
}
```

### After submission = Select view

The button navigates on its own once the server replies. You usually need no body at all — HTTP 2xx is enough. If you want a toast to flash just before the navigation, return one of these:

```json
{ "message": "Saved." }
```

```json
{ "success": "Saved." }
```

```json
{ "oneclick_data": { "message": "Saved." } }
```

All three produce a success toast and then the navigation.

### Submit errors

Return any non-2xx HTTP status. The accepted bodies are:

| Body | What the user sees |
|---|---|
| `{ "message": "…" }` | Error toast with the message |
| `{ "oneclick_data": { "message": "…" } }` | Error toast with the message, plus a trailing "Something went wrong" toast (the body has no top-level `message`, so the unconditional fallback toast also fires) |
| `{ "oneclick_data": { "message": "…", "redirect_view": {…} } }` | Error toast, then navigation |
| `{ "oneclick_data": { "error_message": "…" } }` | Full-page message view replaces the view, plus a trailing "Something went wrong" toast in the corner |
| `{ "oneclick_data": { "error_message": { "title": "…", "message": "…", "hideRetry": false, "hideBack": false } } }` | Full-page message view with your title and message, plus a trailing "Something went wrong" toast in the corner |
| Anything else | Generic "Something went wrong" toast |

The submit button re-enables on error unless you turned on **Disable form after submission**.

***

## URL button responses

URL buttons accept any of these. Two of the shapes only render their toast when **Wait page transition** is enabled on the button — see [URL button quirks](#url-button-quirks) below.

**A plain text body** (not JSON) — shortest path:

```
"Added to cart"
```

Shown as a success toast. You may include inline HTML inside the string (see [HTML support](#html-support)).

**JSON with a top-level `message`** — still no envelope needed:

```json
{ "message": "Added to cart" }
```

Also shown as a success toast.

**Envelope with a message**:

```json
{ "oneclick_data": { "message": "Added to cart" } }
```

Renders a success toast **only when Wait page transition is on**. If the button does not use Wait page transition (the default), this body is silently dropped — the user sees no toast. Prefer the top-level `{ "message": "…" }` shape for plain toasts and reach for the envelope only when you also need a redirect or are already streaming interim updates through the polling endpoint.

**Envelope with a redirect** — the envelope is *required* for this:

```json
{
  "oneclick_data": {
    "redirect_view": { "id": "receipt-view", "params": { "order_id": "4321" } }
  }
}
```

Silent navigation.

**Envelope with both** — only the redirect runs:

```json
{
  "oneclick_data": {
    "message": "Payment successful",
    "redirect_view": { "id": "receipt-view" }
  }
}
```

URL buttons navigate as soon as a `redirect_view` is present and **silently drop** the sibling `message`. To show a message and then navigate, enable **Wait page transition** on the button and stream the toast through the polling endpoint before returning the final response with `redirect_view`. (Form submits behave differently — they show both the toast and then navigate; see [Form submit responses](#form-submit-responses).)

**Errors**: any non-2xx status becomes an error toast. The message comes from the body if it is a plain string or a `{ "message": "…" }` object; otherwise the generic failure message is shown. The button re-enables so the user can try again.

### URL button quirks

URL buttons handle the response in two stages: an immediate handler for the very first response, plus an optional polling loop that runs only when **Wait page transition** is on. Because of that split, the envelope `{ "oneclick_data": { "message": "…" } }` only surfaces in the polling-aware path:

* **Wait page transition off** (the default): only the immediate handler runs. Plain string bodies and top-level `{ "message": "…" }` produce a toast; envelope-only `oneclick_data.message` is silently dropped.
* **Wait page transition on**: the button polls for interim updates (each one becomes a `toast.info`) and at the end shows the final response's `oneclick_data.message` as a `toast.success`. If your final (immediate) response carries both a `message` and a `redirect_view`, the message is dropped — only the redirect runs. Polled responses can carry both, in which case the polled message still shows as `toast.info` just before the redirect.

URL buttons never render `title` or `variant` — the toast is always a success toast (or, on errors, an error toast). Those fields only take effect on form submits.

***

## View data source error

When a view has a data source URL, the response fills the Data Picker's Custom tab. If you need to show an error instead of data — for example "Account not found" — return this shape (and the envelope **is** required):

```json
{
  "oneclick_data": {
    "error_message": {
      "title": "Account not found",
      "message": "We could not find that account. <a href=\"/accounts\">Choose another</a>."
    }
  }
}
```

The view shows a full-page message view with your title and message plus **Retry** and **Go Back** buttons. Add `"hideRetry": true` or `"hideBack": true` to hide either button.

To list several things the user must fix, send `message` as an array of strings. The message view shows them as a bullet list. Add `variant` to change the colours and icon of the message view — `destructive` (default), `warning`, `info`, `success` or `default`:

```json
{
  "oneclick_data": {
    "error_message": {
      "title": "A few things before we continue",
      "message": ["Add a delivery address", "Choose payment terms"],
      "variant": "info"
    }
  }
}
```

`variant` changes the look only. The buttons stay **Go Back** and **Retry**, and the response still counts as an error.

When the message view is not an error, send it as `message_view` instead of `error_message`. The fields and the view are the same; the name just reads better for a `success` or `info` note. `message_view` takes the object form only:

```json
{
  "oneclick_data": {
    "message_view": {
      "title": "Almost there",
      "message": "Customer created. Add a contact person and press Retry.",
      "variant": "success"
    }
  }
}
```

If you only need a single-line message, the string form also works:

```json
{ "oneclick_data": { "error_message": "Something went wrong" } }
```

The same message view also appears when a form submit on this view returns `oneclick_data.error_message` or `oneclick_data.message_view`.

***

## title and variant belong at the top level

::: warning Common mistake
The `oneclick_data` envelope **does not carry `title` or `variant`** — its allowed fields are only `message`, `redirect_view`, `error_message`, `message_view`, and `event_id`. Putting `title` or `variant` inside `oneclick_data` is silently ignored. (The `variant` inside the `error_message` or `message_view` object is a different field: it sets the look of the full-page message view.)
:::

If you write:

```json
{ "oneclick_data": { "message": "Done", "title": "Saved", "variant": "success" } }
```

the `title` and `variant` are silently ignored.

Put them at the top level instead:

```json
{ "message": "Done", "title": "Saved", "variant": "success" }
```

::: warning URL-button toasts ignore title and variant
This top-level shape is only read on form submits with **Wait for response**. URL buttons do not support titles or variants — the toast always renders as a success toast regardless.
:::

***

## HTML support

Every `message` and `title` — whether at the top level or inside `oneclick_data` — passes through a narrow HTML allowlist before rendering. You can use a small subset:

```
<b> / <strong>   bold
<i> / <em>       italic
<u>              underline
<br>             line break
<code>           inline monospace
<a href="…">     link (opens in a new tab)
<p>              paragraph
<div>            generic wrapper
<ul> / <ol> / <li>   lists
```

Anything else is stripped. Links are sanitised: only `https:`, `http:`, `mailto:`, and `tel:` URLs survive; `javascript:` and other schemes are removed. A link left with no URL, an empty one, or a bare `#` shows as plain text. Event-handler attributes (`onclick`, `onerror`, …) are stripped from every tag.

Full rules are in the [Messages & Toasts reference](../../reference/data-binding/messaging.md).

***

## Picking a variant

Set `variant` to match the nature of the message. Variants only take effect in form-submit responses — URL buttons and `oneclick_data.message` always render as success toasts.

| Variant | Use when |
|---|---|
| `success` | Operation completed normally |
| `info` | Neutral informational message |
| `warning` | Non-fatal problem the user should know about |
| `destructive` | Error the user needs to fix |
| `default` | Same as `success` — use when the colour does not matter |

***

## Quick reference

| Situation | Minimal response | Optional/fancier response |
|---|---|---|
| Form submit (Wait for response), plain toast | `{ "message": "…" }` | `{ "message": "…", "variant": "…" }` |
| Form submit (Wait for response), toast with title | `{ "message": "…", "title": "…" }` | add `"variant"` |
| Form submit (Wait for response), replace form | same as above + **Show message after submission** on | |
| Form submit (Wait for response), navigate | `{ "view_id": "…" }` | `{ "oneclick_data": { "redirect_view": {…} } }` |
| Form submit (Wait for response), toast + navigate | `{ "oneclick_data": { "message": "…", "redirect_view": {…} } }` | — |
| Form submit (Select view), toast before navigation | `{ "message": "…" }` or `{ "success": "…" }` | `{ "oneclick_data": { "message": "…" } }` |
| Form submit error | non-2xx + `{ "message": "…" }` | non-2xx + `{ "oneclick_data": { "error_message": {…} } }` for a full-page message view |
| URL button, plain toast | `"…"` (plain string body) or `{ "message": "…" }` | `{ "oneclick_data": { "message": "…" } }` only with **Wait page transition** on |
| URL button, redirect only | `{ "oneclick_data": { "redirect_view": {…} } }` | — |
| URL button, toast then redirect | **Wait page transition** on; stream toasts via the polling endpoint, then return `{ "oneclick_data": { "redirect_view": {…} } }` | — (a sibling `message` next to `redirect_view` is dropped) |
| View data source error (full-page message view) | `{ "oneclick_data": { "error_message": "…" } }` | `{ "oneclick_data": { "error_message": { "title": "…", "message": "…" } } }` |

***

## See also

* [HTTP Response Format](../../reference/data-binding/http-response-format.md) — every response shape the builder accepts.
* [Messages & Toasts reference](../../reference/data-binding/messaging.md) — exact HTML allowlist and link sanitisation rules.
* [Configuring Form Submission](../forms/form-submission.md) — the submit button settings that pair with these responses.

---

---
url: /how-to/data/search-params.md
---
# Using Search Parameters

> **Type:** How-to | **Audience:** End-user | **Goal:** Pass and use URL parameters

## What are Search Params?

Search params are URL query parameters available inside the interface at render time. Use them to pass data between views, between buttons, or from external sources via the URL.

## Passing Params

### Via Action Button

1. Add a **Button** block and set **Button Type** to **Action Button**.
2. Set **Action Type** to **go to view** and pick the target view from the **View Name** dropdown.
3. Click **Handle params** under **Parameters** and add key / value pairs.
4. Values support the Data Picker, so you can pass dynamic data like `{{deal.id}}`.

### Via Navbar Link

1. Add a **Navbar** block, click **Manage Links**, and add or edit a link.
2. Set **Link Type** to **Interface** and pick the target view from **Target Interface**.
3. In the link's **Parameters** section, click **Add Parameter** to append key / value rows. Values support the Data Picker.

### Via Table Action Column

A Table action column's per-action settings include a **Params** key / value editor. Each row's data plus those params are forwarded as search parameters when the action is clicked.

### Via Form Submission

There are two ways a form can pass values as search params on the navigation that follows submission.

**Wait for response or JSON / Multipart-Form-Data with Select view**

1. Configure a **Form Submit Button** with **After submission** set to **Select view** (and Form Type **JSON** or **Multipart/Form-Data**).
2. Optionally add explicit **Parameters** rows -- key / value pairs sent alongside.
3. Turn on **Use input values as search params** to also forward every form input value as a search parameter on the navigation. Each input's internal `name` becomes the parameter key, and the user-entered value becomes the value.

**Open view with form data**

1. Set **Form Type** to **Open view with form data** on the submit button.
2. The Submit URL and After submission settings hide; submission no longer makes an HTTP request.
3. On submit, every form input value is forwarded to the chosen view as a URL search parameter and the navigation runs immediately. Useful for multi-step wizards or filter views.

### Via URL Button

URL Buttons that open a custom URL or another OneClick interface let you append query parameters to the request:

1. Click the **Button URL** button on the URL Button settings to open the **URL Configuration** dialog.
2. In the **Query Parameters** card click **Add Parameter** and fill in key / value pairs. Values support the Data Picker.
3. The pairs are appended to the target URL when the button is clicked.

## Accessing in Data Picker

1. Open any Data Picker field.
2. Switch to the **searchparams** tab (icon-only -- the link icon, with tooltip `searchparams`).
3. Click a parameter to insert it. The chip compiles to a `{{searchparams.<key>}}` placeholder at render time.

The list inside the tab shows every search parameter currently present on the URL plus any that have been declared as expected by buttons elsewhere in the interface (so you can bind to them before they actually arrive).

---

---
url: /how-to/data/variables.md
---
# Managing Interface Variables

> **Type:** How-to | **Audience:** End-user | **Goal:** Create, use, and manage variables

## Variables Page

Open the **Variables** tab from the home screen. The page header reads **Environment Variables** and lists every variable defined for the current interface, with a stats line showing how many are confidential and how many are Pipedrive fields.

## Creating a Variable

The **Add Variable** button in the top-right is a dropdown with two options:

* **Normal** -- a key-value pair you fill in yourself (e.g. an API base URL or token).
* **Pipedrive Field** -- a variable that resolves to the value of a chosen Pipedrive field on the current resource.

### Normal variable

Pick **Normal** to open the **Add New Variable** dialog and fill in:

* **Key** -- a unique identifier (referenced in the Data Picker as `{{variable.key}}`). Required.
* **Value** -- the variable's content. Required. The field uses a password-style input with a show/hide toggle.
* **Confidential** -- toggle on to mask the value in the builder UI and restrict editing/deletion to its creator. (All variable values are encrypted at rest, regardless of this toggle.)

Click **Create Variable** to save.

### Pipedrive Field variable

Pick **Pipedrive Field** to open the **Add Pipedrive Field Variable** dialog and fill in:

1. **Resource Type** -- choose **Deal**, **Person**, or **Organization**.
2. **Pipedrive Field** -- pick a field from the searchable list.
3. **Variable Name** -- defaults to the field's display name. Edit if you want a shorter key.

The dialog also shows the resolved **Field code** as a preview. Click **Create Variable** to save. The variable's value is resolved at render time from the current deal/person/organization context.

## Confidential Variables

All variable values are encrypted at rest in the database. The **Confidential** toggle adds two extra protections on top of that:

* The value is masked (`••••••••••••`) in the variables list. Only the creator can reveal it with the eye icon. Other users see the mask with no eye icon, and the copy button is not shown for confidential variables.
* Only the creator can edit or delete the variable. Other users see the row but the action icons are disabled.

The variable still works the same way at render time: the encrypted value is decrypted server-side and used in placeholders. Use confidential variables for API keys, tokens, and other sensitive data.

## Using in Data Picker

1. Open any Data Picker field in the builder.
2. Switch to the **Variable** tab (the icon-only tab in the picker's top bar).
3. Click a variable to insert it as a tag. The compiled syntax is `{{variable.your_key}}`.

Variables are resolved server-side at render time, so confidential values are never exposed in the client.

## Editing and Deleting

Hover a variable card to reveal the action icons on the right:

* **Edit (pencil)** -- modify the key, value, or confidential flag.
* **Delete (trash)** -- removes the variable after a confirmation dialog.

**Permissions:** only the user who created a confidential variable can edit or delete it. Non-confidential variables can be modified by any user with access to the interface.

## Variables and snapshot restore

A [snapshot](../views/snapshots.md) holds every variable of the interface, confidential values included. The values stay encrypted in the snapshot. A restore returns the variables to the state of the snapshot, with the same creator rule as editing:

* **Your own confidential variables** are restored like all other variables.
* **Confidential variables of other admins** stay as they are. The restore does not change their value and does not delete them, also when the snapshot does not have them. The restore preview lists their keys in a separate line (for example *"2 confidential variables of other admins stay as they are: api\_token, slack\_webhook\_token."*) and does not count them in the **Variables** totals.
* If the snapshot has a variable with the same id or the same key as such a kept variable (the key match ignores case), the restore skips the snapshot variable. So each key is on one variable after the restore.

---

---
url: /how-to/views/creating-a-view.md
---
# Creating a New View

> **Type:** How-to | **Audience:** End-user | **Goal:** Add views to an interface

## Interface Views Page

Open the views list for an interface from the interface management page (the **Interface Domain > Interface Views** breadcrumb). The page shows every view in the interface as a card with its name, description, row count, and the **Start** badge on whichever card is the main view.

## Creating a New View

1. Click **Create New** in the top-right of the **Your Views** section.
2. The **Create new view** dialog opens. Fill in:
   * **Name** -- a unique, descriptive name. The name is used in navigation references (action buttons, navbar links, form-after-submit selectors) and in the view-selector dropdowns inside the builder. Choose clear names like `Customer details`, `Order summary`, or `Edit form`.
   * **Description** -- optional context shown on the view card.
   * **Default view** -- when on, this view becomes the interface's main view (see [Main View](#main-view) below). The first view of an interface is forced to be the default and the toggle is disabled.
3. Click **Create**. The view is created with an empty canvas and the builder opens automatically.

## Editing the View in the Builder

Click **Edit** on a view card (or open a view from the breadcrumbs) to start working on it in the builder. From there you can:

* Add rows and blocks.
* Configure data bindings via the Data Picker.
* Set Global Styles for view-wide font, colour, and gap defaults.
* Configure Areas to group rows for shared visibility or looping.

Each view has its own independent layout, rows, blocks, and settings. Edits auto-save -- there is no separate save or publish step. See [Saving](publishing.md) for the auto-save and validation rules that apply.

## Card Actions

Each view card has four action buttons:

| Button | What it does |
|---|---|
| **Edit** | Opens the view in the builder. |
| **Settings** | Opens the **Edit view** dialog. Same fields as **Create new view** plus a read-only **ID** -- use this dialog to rename, edit the description, or change which view is the main view. |
| **Copy** (clipboard icon) | Duplicates the view inside the same interface. The copy is never the main view. |
| **Delete** (trash icon) | Removes the view after a confirmation prompt. |

## Main View

The main view is the one that opens when a user clicks the OneClick button in Pipedrive. In the views list it is highlighted with a green border and a **Start** badge (star icon) on the card preview.

To change which view is the main view:

1. Click **Settings** on the view card you want to promote.
2. In the **Edit view** dialog, turn on the **Default view** switch.
3. Save.

Only one view can be the main view at a time -- enabling **Default view** on a different card automatically clears it on the previous main view. Other views are reached through navigation actions: Action Buttons, Navbar links, Table action columns, and form submissions. See [Navigating Between Views](navigation.md) for setup details.

---

---
url: /how-to/views/managing-interface-views.md
---
# Managing Interface Views

> **Type:** How-to | **Audience:** Interface builder user | **Goal:** Browse, copy, and delete the views in your interface

Interface Views is the top-level list of all views under a single interface (for example, a deal-details panel, a product form, a summary page). This page covers the tools for managing that list from the home screen.

## The Interface Views list

Open the Interface Views page from the home screen. The list shows one card per view. Each card contains:

* A **preview area** with an abstract miniature of the view's layout. Hovering reveals an **Open Editor** overlay you can click to jump straight into the builder.
* A **Start** badge in the top-left of the preview when the view is the interface's default view.
* An **Error** badge instead, if the view's saved data fails to parse.
* The view **name** and **description**.
* Stats: the **row count** and an **Interface** label.
* Action buttons:
  * **Edit** -- the primary call-to-action; opens the view in the builder.
  * **Settings** -- opens the view's settings dialog (rename, edit description, mark as default, etc.).
  * **Copy view** -- icon button with a tooltip; duplicates the view.
  * **Delete view** -- icon button with a tooltip; removes the view.

## Copying a view

Click the **Copy view** icon on any card to duplicate it. The new view appears instantly as `"<original> (Copy)"` and contains a full snapshot of every row, block, area, and data source.

Use this when you want to iterate on a view without breaking the production version, or when you need several similar views that differ only slightly.

## Deleting a view

1. Click the **Delete view** icon on a card.
2. The card switches to an inline confirmation: **"Delete this view?"** with **Cancel** and **Delete** buttons.
3. Click **Delete** to remove the view, or **Cancel** to back out.

This action cannot be undone from the views list. If you took a [snapshot](./snapshots.md) before the delete, restore that snapshot to get the view back with its original id. The restore returns all views and variables to the state of the snapshot, and you can undo it.

---

---
url: /how-to/views/snapshots.md
---
# Snapshots

> **Type:** How-to | **Audience:** Interface builder user | **Goal:** Take a copy of an interface and return the interface to it

A snapshot is a copy of all the views and all the variables of one interface. Take a snapshot before a big change. If the change breaks something, restore the snapshot and the interface is back in the state of the snapshot. A snapshot does not hold the OneClick settings of the interface (URL, token, headers, fields, visibility).

Open the **Snapshots** tab on the home screen, next to **Views** and **Variables**.

## Taking a snapshot

1. Click **Take snapshot**.
2. Optionally type a **Name** and a **Description**. An empty name saves the snapshot as `Snapshot <yyyy-MM-dd HH:mm>`.
3. Click **Take snapshot** in the dialog.

The snapshot holds each view and each variable as a whole: for a view, for example its layout, sample data, data source URL and method, additional data, active flag, default view flag, name and description; for a variable, its key, value, type, resource, confidential flag and creator. Confidential values stay encrypted in the snapshot. The content of a snapshot never changes after you take it.

## The snapshot list

The list shows the snapshots of the current interface, newest first. Each row shows:

* The **name** and a **Manual** or **Auto** badge. An Auto snapshot is the one a restore takes automatically (see [Undoing a restore](#undoing-a-restore)).
* The **description**, truncated to one line. Hover it to see the full text.
* The creation time and the user who took the snapshot.
* The size, for example `4 views · 5 variables`.
* **Restore**, **Edit snapshot** (pencil) and **Delete snapshot** (trash).

## Restoring a snapshot

A restore returns all the views and variables of the interface to the state of the snapshot:

* Views and variables made after the snapshot are removed.
* Views and variables deleted after the snapshot come back, with their original ids. References to a restored view from other views keep working.
* Views and variables changed after the snapshot change back.
* Confidential variables of other admins stay as they are. See [Variables and snapshot restore](../data/variables.md#variables-and-snapshot-restore).

1. Click **Restore** on the snapshot row. A summary card opens above the list, titled **Restoring to \<snapshot time>**.

2. Check the counts. For views and for variables, the card shows how many **Will be removed**, **Will be restored** and **Will change back**. A red line lists the views that the restore deletes. If confidential variables of other admins stay as they are, a separate line lists their keys.

3. Click **Continue**, or **Cancel** to close the card without changes.

4. The dialog **This replaces the current state** opens. Type the name of the interface exactly as shown, with the same upper and lower case letters.

5. Click **Restore now**. **Restore now** stays disabled until the name matches. Click **Back** to return to the summary card.

After the restore, a toast confirms it and the **Views** and **Variables** tabs show the restored data.

A restore is all or nothing. If it fails, nothing changes and one of these toasts appears:

| Toast | Cause |
|---|---|
| **Restore failed. No changes were made.** | The restore failed. The summary card stays open, so you can try again. |
| **Snapshot no longer exists. No changes were made.** | Somebody deleted the snapshot in another session. The list refreshes. |
| **Button no longer exists.** | The interface was deleted. The app returns to the OneClick settings. |

## Undoing a restore

Before every restore, a snapshot named `Before restore: <snapshot name>` is taken automatically. It has the **Auto** badge and holds the state that the restore replaced. To undo a restore, restore that Auto snapshot.

## Editing and deleting a snapshot

* **Edit snapshot** (pencil) changes the name and the description. The copied views and variables do not change. The name cannot be empty.
* **Delete snapshot** (trash) asks for confirmation and then deletes the snapshot permanently. This cannot be undone.

Any admin can edit, delete and restore any snapshot of the interface, also Auto snapshots and snapshots taken by other admins. When the interface is deleted, its snapshots are deleted too.

---

---
url: /how-to/views/navigation.md
---
# Navigating Between Views

> **Type:** How-to | **Audience:** End-user | **Goal:** Set up view navigation

## Action Button

The Action Button is the primary way to navigate between views.

1. Add a **Button** block to your view.
2. Set **Button Type** to **Action Button**.
3. Choose an **Action Type**:
   * **go to view** -- navigates to a selected view. A **View Name** dropdown lists every view in the interface.
   * **back** -- returns to the previous view.
4. Optionally click **Handle params** under **Parameters** to add key/value pairs that get forwarded to the target view. Values support the Data Picker.

## Navbar Links

The **Navbar** block supports interface-type links for view navigation:

1. Add a **Navbar** block to your view.
2. Click **Manage Links** in Block Settings to open the link manager dialog.
3. Click **Add** and configure the new link:
   * **Label** -- the clickable text shown on the navbar.
   * **Link Type** -- pick **Interface** for in-interface navigation (or **External URL** for an outside link).
   * **Target Interface** -- the destination view dropdown. Shown when **Link Type** is **Interface**.
   * **Parameters** -- key/value pairs passed to the target view. Click **Add Parameter** to add rows.

## Table Actions

Table blocks can include row action columns that navigate to views. Configure a column as an action column, add an action with **Action Type = Go to view**, pick a **View Name**, and optionally add **Params** -- the action will navigate to the chosen view with those params, alongside the row's data, when a user clicks the icon.

## Form After Submit

When a form is submitted, you can navigate to a different view:

1. Set the submit button's **After submission** to **Select view**.
2. Pick the target view from the **View ID** dropdown.
3. Optionally add **Parameters** -- key/value pairs passed alongside the navigation.
4. Turn on **Use input values as search params** to automatically forward every form field value as a URL search parameter on the navigation.

Alternatively, set **Form Type** to **Open view with form data** to skip the HTTP submission entirely. The submit button hides its Submit URL and After submission settings, forwards every form input value as a search parameter to the chosen view, and navigates immediately when the user clicks submit.

## Passing Parameters

All navigation methods support passing parameters:

* **Action Button** -- click **Handle params** under **Parameters** and add key / value entries.
* **Table action column** -- each action has its own **Params** key / value editor.
* **Navbar links** -- each link has its own **Parameters** section inside the Manage Links dialog.
* **Form Submit Button** (After submission = **Select view**) -- use **Parameters** for explicit pairs and / or **Use input values as search params** to forward every form field.

The target view receives these as URL search parameters, accessible from the Data Picker's `searchparams` tab (icon-only) and compiled to `{{searchparams.key}}` placeholders at render time.

---

---
url: /how-to/views/publishing.md
---
# Saving

> **Type:** How-to | **Audience:** End-user | **Goal:** Understand how saves reach end users and which validation rules have to pass

## Auto-Save

Interface Builder saves automatically. After you stop editing for a brief moment, the change is written to the server -- there is no save button and no publish step. You do not push a view live; it **is** live. The moment a save completes, anyone opening the view in Pipedrive sees your latest edits.

::: warning Every save is immediately live
Preview and Test modes inside the builder render against the same saved data — they do **not** isolate changes from end users. Anyone opening the OneClick button while you're editing sees your in-progress edits. See [External Data Flow](../../explanation/external-data-flow.md) for what each mode does and does not call.

For risk-free experimentation, copy the OneClick button in Pipedrive and edit the copy's interface, then point users at the new button when the changes are ready.
:::

## Validation

Before each save the builder runs a validation pass over the whole view -- rows, blocks, forms, and every setting. If something is wrong, an **Action required** card appears on the canvas with a quick-fix button, and the save is blocked until you resolve the issue. This means a broken view never reaches end users.

The card icon, title, description, and quick-fix button vary by issue. For incomplete forms the card title is **Missing input field** (with an **Add input** button) or **Missing submit button** (with an **Add submit button** button); other issues surface as inline errors next to the affected field in Block Settings.

## Common Validation Errors

These messages come straight from the validation layer. Each one blocks save until fixed.

| Error | Cause | Fix |
|---|---|---|
| **Form requires at least one submit button** | A form has no submit button. | Add a Button block with **Button Type = Form Submit Button** and pick this form in the **Form** dropdown. |
| **Form requires at least one input field** | A form has no Input blocks. | Add at least one Input block between Form Start and Form End. |
| **Form start requires a corresponding form end** | A `Form Start` row exists without a matching `Form End`. | Add the `Form End` row, or delete the orphan `Form Start`. |
| **Input field must be inside a form** | An Input block sits outside any form. | Move it between a `Form Start` and `Form End` row. |
| **Input name must be unique** | Two Input blocks share the same internal name (usually from copy-paste). | Delete one and re-add it so the builder generates a unique name. |
| **Submit button requires a form to exist** / **Reset button requires a form to exist** | A Form Submit or Form Reset Button points at a Form Identifier that does not exist. | Create a form with that identifier or pick an existing form. |
| **URL is required** | A URL Button or external Navbar link, or a Submit URL on a JSON / Multipart form, has no URL set. | Fill the missing URL field. |
| **You can't use the file input type because the form doesn't submit anything -- it opens a new view with the input values as search parameters.** | A form with file inputs uses **Open view with form data** as its Form Type. | Remove the file input or change **Form Type** to **JSON** or **Multipart/Form-Data**. |

## Testing a Live View

Once a save completes, the view is live. To test it the way users see it:

* Use **Test mode** inside the builder (the **Test** button in the top bar) to run the view with real records.
* Or open the OneClick button in Pipedrive to see exactly what users see.

Either way verifies:

* Layout and styling.
* Data Picker placeholders resolve correctly.
* Form submissions work.
* View navigation behaves as expected.
* Conditional visibility rules behave as expected.

## Main View

An interface can contain more than one view. The **main view** is the one that opens when a user clicks the OneClick button in Pipedrive. It is highlighted in the views list with a green border and a **Start** badge (star icon) on the card preview.

To change which view is the main view, click the **Settings** button on a view card to open the **Interface Settings** dialog, then turn on the **Default view** switch. Only one view can be the main view at a time -- enabling **Default view** on a different card automatically clears it on the previous main view. Users reach the other views through navigation (Action Buttons, Navbar links, or form submissions).

---

---
url: /how-to/views/testing-a-view.md
---
# Testing a View with Real Data

> **Type:** How-to | **Audience:** Interface builder user | **Goal:** Render your view against live Pipedrive records and external data sources

The builder's **Test** mode renders your view with real data while you are editing it. Use it to verify that placeholders resolve, forms submit correctly, and conditional visibility behaves as expected -- before anyone else opens the view.

Interface Builder has no separate publish step. Every edit you make is auto-saved and goes live immediately for anyone who opens the view in Pipedrive, so Test mode is the safest place to experiment.

## Opening Test Mode

1. Open the view in the builder.
2. Click the **Test** button in the top bar (next to **Preview** / **Sample data**).

The builder switches to Test mode: a single toolbar runs along the top of the canvas, with the rendered view below it.

The back arrow on the left returns to the builder.

## Picking a Pipedrive Record

The toolbar shows the active resource as a button labelled `<Resource> #<ID>` (for example, `Deal #1995`). Click it to open the **Pipedrive resource** dialog and pick a different record.

1. Pick a resource type -- **deal**, **person**, or **organization**.
2. Pick a specific record from the list.
3. Close the dialog.

The preview reloads with that record's data. Every Data Picker placeholder bound to a Pipedrive field (for example `{{deal.title}}`) resolves to the real value.

A [floating window button](../../explanation/floating-window-buttons.md) has no record to pick, so its Test and Preview toolbars do not show the resource button at all.

## Tweaking the External Data Source

If your view has a Data Source URL configured, click the URL button on the toolbar (Link icon, label is the path of the configured URL). The **View parameter** dialog opens and lets you tweak the request without editing the saved view configuration:

* **URL path** -- override the path the test calls.
* **Query parameters** -- add, edit, or remove key/value pairs. Duplicate keys collapse into a single row whose value reads `(multiple)`.

Closing the dialog re-runs the request and re-renders the view.

## Reviewing the Backend Response

Click **Review received data** (eye icon, green button) to see the JSON your data source actually returned, along with the HTTP status. Use this when placeholders look empty or wrong -- it tells you whether the backend sent what you expected. The dialog is empty until a backend response arrives -- it never falls back to your saved Sample data. If your view has no data source configured, switch to **Preview** to see how Sample data renders.

## Manual vs Automatic Reload

The **Automatically update on change** switch on the right of the toolbar controls when reloads happen.

* **On** (default) -- the preview reloads automatically whenever you change the resource, the URL path, or any query parameter.
* **Off** -- changes are buffered. Click the **Test** action button to fetch the data and re-render manually. Useful when you are making many small edits.

Your preference is stored in browser localStorage (`autoloadEnabled`), so it persists across sessions.

## What Test Mode Is Not

* It does **not** gate your edits. There is no publish step -- whatever you have saved in the builder is already what users see. Test mode is just a convenient way to render the same view with real records while you keep editing.
* It does **not** replace real end-user validation -- the preview runs in the builder, not in the Pipedrive panel where your users actually see the view.

## Troubleshooting

* **Toast `Request timed out. No custom data received.`** -- your Data Source URL backend did not respond within ~20 seconds. Check your backend logs.
* **Toast `Data loading failed (status 500)`** -- your Data Source URL returned a non-2xx status. The status code is shown in the toast.
* **Placeholders show literal text** -- the data needed to resolve them is missing. Check that you selected a Pipedrive record, or that your Data Source URL returned the fields you expect. Use **Review received data** to confirm what arrived.

See [External Data Source](../data/external-data-source.md) for configuring the URL that Test mode calls.

---

---
url: /how-to/visibility/conditional-visibility.md
---
# Conditional Visibility

> **Type:** How-to | **Audience:** End-user | **Goal:** Show or hide blocks, rows, and areas based on data

## Block Visibility

To conditionally show or hide a single block:

1. Select the block in the builder.
2. In Block Settings, switch to the **Visibility** sub-tab (next to **Configuration** and **Style**).
3. Toggle **Enable conditional visibility** on.
4. In the **Condition** field, insert a Data Picker tag for the value that should drive visibility.
5. Under **When hidden**, pick:
   * **Hide (keep space)** -- the block becomes invisible but its column keeps the same space.
   * **Remove** -- the block is removed from the layout.
6. When the mode is **Remove** and the row has more than one column, choose how the freed column space is handled:
   * **Keep original sizes** -- the empty space stays at the end of the row.
   * **Redistribute space** *(Recommended)* -- the remaining blocks share the freed space.

## Row Visibility

To conditionally show or hide an entire row:

1. Open Row Settings -- click the row's column-header on the canvas, or pick **Settings** from the row's "..." menu.
2. Scroll to the **Conditional Visibility** section.
3. Toggle **Enable conditional visibility** on.
4. In the **Condition** field, insert a Data Picker tag.
5. Under **When hidden**, pick:
   * **Hide (keep space)** -- the row is invisible but retains its vertical space.
   * **Remove** *(Recommended)* -- the row is removed entirely so the layout closes up.

## Area Visibility

Areas support the same visibility rules. When an area is hidden, every row inside it disappears together.

1. Click the area's coloured **badge** on the canvas to open Area Settings.
2. Toggle **Enable conditional visibility** on.
3. Insert a Data Picker tag in the **Condition** field.
4. Pick **Hide (keep space)** or **Remove** *(Recommended)*.

See the [Areas reference](../../reference/layout/areas.md) for full details on what areas can do.

## Writing Conditions

The condition is evaluated at render time. The element is hidden when the value is **empty** or equals `"false"`. Any other value shows the element.

Examples (the compiled syntax behind a Data Picker tag is shown):

| Condition | Shows when... |
|---|---|
| `{{deal.value}}` | The deal has a value set (non-empty) |
| `{{user.id}}` | A user ID exists (always true for logged-in users) |
| `{{deal.status}}` | The deal status field is not empty |
| `{{custom.is_premium}}` | The custom data source returns a truthy `is_premium` field |
| `{{variable.show_section}}` | The interface variable `show_section` is not empty or `"false"` |

Use the Data Picker to build conditions: click the Condition field, switch to the relevant tab (Deal, Variable, Custom, ...), and click the field. The tag is inserted as a blue chip; the curly-brace syntax above is what it compiles to at render time.

## Empty Condition Warning

If you turn **Enable conditional visibility** on but leave the **Condition** field empty, the element will never appear at runtime — an empty condition resolves to "hidden" (see the [Visibility System explanation](../../explanation/visibility-system.md#how-conditions-are-evaluated)). The builder flags this state on three surfaces so it doesn't ship by accident:

* An **Always hidden** banner appears under the Condition field in the visibility settings panel.
* The block, row, or area's eye indicator on the canvas turns red and switches to a warning triangle.
* An area badge with this state takes a red background regardless of its chosen colour.

The data still saves — the warning is purely a builder-time signal. Either fill in a condition or turn the toggle off to clear the warning.

## Hide vs Remove

The two modes affect how the layout reacts when the element is hidden:

* **Hide (keep space)** -- the element becomes invisible but its slot is reserved. The surrounding layout doesn't shift, so nothing jumps when the condition flips. Use this when you need a stable layout.
* **Remove** -- the element is taken out of the layout entirely. Surrounding content reflows to fill the gap.

For blocks inside a multi-column row, the **Remove** mode adds a second choice -- **Keep original sizes** leaves an empty slot, **Redistribute space** *(Recommended)* lets the remaining blocks expand to fill the freed column.

---

---
url: /how-to/forms/creating-a-form.md
---
# How to Create a Form

> **Type:** How-to | **Audience:** End-user | **Goal:** Set up a form structure on the canvas

## Add the Form

1. Hover the gap between two rows on the canvas (or above the first row). A small `+` button appears.
2. Click `+` to open the **Add row** dialog.
3. Pick **Form** from the layout list.

The dialog closes and two new marker rows appear on the canvas:

* **Form Start** — marks the beginning of the form (shown with a left-edge accent and a row label).
* **Form End** — marks the end of the form (shown with a left-edge accent and a row label).

The **Form** option is hidden in the **Add row** dialog when you are already inside a form — forms cannot be nested.

## Set the Form Identifier

1. Click either the **Form Start** or **Form End** row to open the **Form Settings** tab in the sidebar.
2. Enter a unique name in the **Form Identifier** field — for example, `contact-form`.
3. The identifier appears as a badge next to **Form Start** on the canvas and is used by Submit and Reset buttons to target this form.

## Adjust Form Padding (Optional)

In the **Form Settings** tab you can set inner padding for the rendered form:

* **Padding Top** (px)
* **Padding Bottom** (px)
* **Padding Left** (px)
* **Padding Right** (px)

## Add Rows Inside the Form

Hover the area between the Form Start and Form End markers, then click the `+` button that appears to open **Add row**. Pick any layout (Full, Two Column, etc.) — note that the **Form** option is hidden inside an existing form. Rows added in this area become part of the form.

## Place Input Fields

Click an empty column inside the form to open **Add block**, then pick **Input**. The dialog only allows the **Input** block when the surrounding row is inside a form. For details on input types and settings, see [Input Field Types](input-field-types.md).

## Validation Warnings

While you build, the canvas highlights warnings when the form is incomplete. Each warning includes a quick action button to fix the problem:

* **Missing input field** — the form has no input blocks between Form Start and Form End. Add at least one Input block.
* **Missing submit button** — no button anywhere in the view targets this form's Form Identifier. Add a Button block, set its **Button Type** to **Form Submit Button**, and pick this form from the **Form** dropdown.

---

---
url: /how-to/forms/form-submission.md
---
# Configuring Form Submission

> **Type:** How-to | **Audience:** Interface builder user | **Goal:** Set up how the form sends data and what the user sees after they submit

A submit button's settings live in the **Configuration** sub-tab of the Block Settings sidebar. Open them by selecting a **Form Submit Button** on the canvas.

## Pointing the Button at a Form

The **Form** dropdown lists every form on the view (each `Form Start` row). Pick the one this submit button should send.

## Form Type

Set **Form Type** to control how data is sent:

* **JSON** (default) -- sends form data as a JSON payload. Requires a Submit URL.
* **Multipart/Form-Data** -- sends as multipart form data. Use this when the form includes file uploads. Requires a Submit URL.
* **Open view with form data** -- passes form data to another view as URL search parameters without making any HTTP request. The Submit URL and After submission settings are hidden in this mode; submission always opens a target view.

Full request shapes for each type: [Form Submission Types reference](../../reference/data-binding/form-submission-types.md).

## Submit URL

For **JSON** and **Multipart/Form-Data**, click the **Submit URL** button to open the **URL Configuration** dialog. The dialog has three cards:

* **Button end-point configuration** -- the End-point URL the form posts to (supports the Data Picker), a **URL Active** toggle, and an **Omit oneclick metadata** switch (turn this on for APIs that reject extra fields like `event_id` or `resource_id`, e.g. Pipedrive API v2).
* **Query Parameters** -- key/value pairs appended to the Submit URL. Click **Add Parameter** to add a row; values support the Data Picker.
* **Manage Headers** -- custom HTTP headers sent with the request. Click **Add Header** to add a row. Header keys must contain only letters, numbers, and hyphens, cannot start or end with a hyphen, and cannot start with `x-oc-` (reserved for system headers). Header values support the Data Picker, so you can use dynamic values like `{{variable.api_key}}`.

::: info OneClick-level headers are merged in automatically
If the OneClick button this interface is attached to has its **Headers** toggle enabled (configured outside the builder, on Pipedrive's **Edit a Button** page), every header listed there is sent with the form submit request. Use the per-call headers here only for values that differ between forms. See [OneClick-Level Headers](../../explanation/architecture.md#oneclick-level-headers) for the merge order and the reserved `x-oc-*` keys.
:::

The Submit URL button shows a method badge (always `POST` for submit buttons) and a green ✓ when a URL is set; it turns red if the Submit URL is missing.

## After Submission

For **JSON** and **Multipart/Form-Data**, the **After submission** dropdown picks what happens once the request is sent:

### Select view

Navigates the user to another view as soon as the request finishes.

* **View ID** -- the target view dropdown.
* **Parameters** -- key/value pairs passed to the target view.
* **Use input values as search params** -- a design-time hint. When on, the form's inputs are listed under **Expected Parameters from Views** in the target view's URL Configuration dialog. Form input values are forwarded on the navigation regardless of this switch — toggling it off does not remove them from the URL.

### Wait for response

Waits for the server to respond, then reacts to what came back.

* **Timeout (s)** -- how long to wait, between **10** and **60** seconds (default 10). The fetch is aborted if the response does not arrive in time.
* **Form State** > **Disable form after submission** -- when on, the submit button stays disabled after the response returns. Useful when the submit is final and you do not want the user to try again.
* **User Feedback** > **Show message after submission** -- when on and the response contains a message, replaces the whole form with an inline alert instead of showing a toast. See the [Post-submit message](#post-submit-message) section below.

What you return from the server decides what the user sees next. See [HTTP Response Format](../../reference/data-binding/http-response-format.md) for the response shapes.

## Validation Behavior

The **Validation Behavior** group controls how validation errors and submission errors are surfaced before the request is even attempted. Each toggle has a tooltip explaining what it does.

| Switch | Effect |
|---|---|
| **Show error indicator on submit button** | Adds a red border and a tooltip with the error count to the submit button while there are validation errors on the form. A passive hint before the user clicks. |
| **Scroll to first error field** | When the user clicks submit on an invalid form, smoothly scrolls and focuses the first invalid field. The strongest way to draw attention to a long form's validation issue. |
| **Show error toast on submit** | Pops a toast with the number of invalid fields (for example `3 fields have errors`). The toast does not say *which* fields -- combine it with **Scroll to first error field** to make that obvious. |

Combine **Scroll to first error field** with **Show error toast on submit** for the strongest feedback: the toast tells the user there *are* errors, the scroll-plus-focus shows *which* one to fix first.

## Submission Feedback

### While the submit is in flight

Once the user clicks submit on a **Wait for response** form, the submit button shows a spinner in place of its label (the label's width is preserved so the layout does not jump) and the whole form switches to a `progress` cursor so the user cannot mistake the state for idle. The submit button and every descendant input stay in that state until the response returns -- on success or error -- or the submission throws. A thrown network or JSON-parse error resets the state so the button never gets stuck.

**Select view** forms behave the same way up to the point of navigation; the spinner is visible until the browser leaves the page.

### Backend error response feedback

When the backend returns `oneclick_data.error_message` or `oneclick_data.message_view` (see [HTTP Response Format](../../reference/data-binding/http-response-format.md#error-responses)), two things happen:

1. A full-page message view replaces the rendered content with the message's `title` and `message`, plus **Go Back** and **Retry** buttons. `message` can be an array, shown as a bullet list, and `variant` sets the colours and the icon. You can suppress either button by returning `hideRetry: true` or `hideBack: true` on the object.
2. On error responses, an additional toast also appears with the response's top-level `message` (or `Something went wrong` when none was supplied).

### Post-submit message

When **After submission** is set to **Wait for response** and the backend returns a message, how it is shown depends on **Show message after submission**:

| Show message after submission | Response has `title`? | User sees |
|--|--|--|
| Off | No | Toast with `message` |
| Off | Yes | Toast with `title` as primary text, `message` as description |
| On | No | Inline alert replacing the form, `message` only |
| On | Yes | Inline alert replacing the form, `title` + `message` |

When the inline alert appears, the view smoothly scrolls to it so the user does not miss the new content even if they were at the bottom of a long form.

The message and title can include a small amount of inline HTML -- bold, italic, line breaks, links, and inline code. See [Messages & Toasts](../data/messages-and-toasts.md) for how to format messages your backend returns.

---

---
url: /how-to/forms/form-validation.md
---
# Form Validation

> **Type:** How-to | **Audience:** End-user | **Goal:** Understand validation rules

## Required Fields

1. Select an input field inside your form.
2. Toggle **Required** on in the input settings.
3. When enabled, the form cannot be submitted until the user fills in this field.

::: warning Hidden inputs ignore Required
The Required toggle is forced off when the input type is Hidden — there is no way to require a hidden field.
:::

### Required from data

Use data when some records need the field and others do not.

1. Click the ⇄ button beside the **Required** label. A Data Picker field replaces the switch.
2. Bind the field to a value, for example {{deal.must\_fill}}.
3. The field is required when the value is `true`, `yes` or `1`. Case and surrounding spaces do not matter.

Any other value leaves the field optional. This includes an empty value, `no`, `0`, `false` and a value that does not resolve, so an empty Data Picker field shows no warning. The value comes from the view data (Sample data, Received data, variables, System context). It does not read other inputs in the same form.

Click ⇄ again to go back to the switch. The switch keeps its earlier position, and the Data Picker value is kept too.

**Disabled** has the same choice and follows the same rule. A disabled field sends its **Default Value** when the form is submitted, and its validation (Required, Pattern, bounds) does not run.

## Pattern Validation

Use regex patterns to enforce custom input formats:

1. Select a text-based input field (**Text**, **Textarea**, **Email**, **Number**, **URL**, or **Date** type).
2. Enter a regex expression in the **Pattern** field (e.g., `^\d{3}-\d{4}$` for a phone format like `123-4567`). The field accepts a literal regex, or a Data Picker placeholder (e.g. `{{validation_rules.email_pattern}}`) that resolves to one at submit time.
3. Once Pattern has a value, a **Pattern Error** field appears underneath. Set it to override the default error message shown when the input does not match. Pattern Error also supports the Data Picker, so the message can be localised or context-dependent.

If no custom error message is set, a default validation error is shown.

When the **value** a user submits is itself a Data Picker placeholder (e.g. a prefilled field bound to a template variable), the regex check is skipped -- the resolved value is trusted to be validated by the backend.

## Number Min/Max Validation

For **Number** type inputs, bound the accepted range:

1. Select a **Number** input field.
2. Set **Min** and/or **Max** to the desired bounds. Both accept either a literal number or a Data Picker placeholder that resolves to one (e.g. `{{user.min_age}}`).
3. Once Min has a value, a **Min Error** field appears; once Max has a value, a **Max Error** field appears. Use these to customise the messages shown when the submitted value falls outside the bounds.

Bounds are enforced at submit. If the value is below **Min** or above **Max**, the form does not submit and the error message appears next to the field. Changing the input **Type** away from **Number** clears all four fields (Min, Max, Min Error, Max Error) automatically.

## Built-in Type Validation

Certain input types have automatic validation:

* **Email** -- validates email address format.
* **URL** -- validates URL format.
* **Number** -- only accepts numeric input.

No extra configuration is needed -- these validate automatically on form submission.

## File Type Limits

Set **Accepted file types** on a File input to take only some kinds of file. Write one comma-separated list of extensions and MIME types:

```
.pdf, .docx, image/*
```

* A bare word such as `pdf` reads as `.pdf`. Case does not matter, and extra commas are ignored.
* An entry that is neither an extension nor a MIME type, such as `*.pdf` or `image/`, shows an error under the field.
* An empty list accepts every file.

The file dialog offers only the listed types. The drop zone hint starts with the list, such as `.pdf, .png, image/* · One file · max 10 MB`; after three types it shows `+N more`. While a user drags a file of another type over the drop zone, the zone turns red and reads `File type not accepted (.pdf, .png)`. During a drag the browser shows only the file's MIME type, so the warning needs a MIME type for every entry: it never comes while the list holds an extension whose MIME type the field does not know.

A file of another type can still arrive, for example by a drop. It joins the selection, its row turns red, and the form does not submit until the user removes it. The message names the file and the list:

```
File "setup.exe" is not an accepted type (.pdf, .png)
```

This is a check in the browser only. The server does not read the list, so do not rely on it to keep a file type out of your endpoint.

## File Size Limits

A file input is guarded in two places -- your own limits in the browser, and the server's budget -- and they fail with different messages.

### 1. Your own limits, in the browser

You set up to three limits on the field. Each one has its own message, so the user is told which limit they passed and by how much. The form does not submit until the selection clears all three.

**Max File Size (MB)** applies to **each file on its own**, never to the selection added up -- three 5 MB files pass a 10 MB limit. An oversized file also turns its own row in the field red as soon as it is picked, and the message names the file:

```
File "contract.pdf" is 12.4 MB, which exceeds the 10 MB limit
```

**Max Total Size (MB)** applies to the selection added up. Only a field with **Allow multiple files** on has it:

```
The selected files total 12.4 MB, which exceeds the 10 MB limit
```

**Max Number of Files** caps how many files the field takes. It too belongs to a multi-file field alone, and it is the only limit that stops a user attaching hundreds of tiny files:

```
14 files selected, which exceeds the limit of 10 files
```

The range you may set for the two size limits depends on the surrounding form's **Form Type**: **JSON** forms allow up to **10 MB**, **Multipart/Form-Data** forms allow up to **100 MB**. The count may go up to **25** on JSON forms and **50** on Multipart/Form-Data, and arrives pre-filled with **10**. The label inside Block Settings shows the active ceiling for each, and the size fields arrive pre-filled with it -- lower a number yourself if you want a tighter check.

When a selection breaks more than one limit at once, the user reads the file type message first, then the per-file size message, then the count, then the total size. A file of the wrong type must go whatever its size, and the two per-file messages are the ones that name a file, so they say what to drop.

### 2. The submission budget, on the server

Setting your own limits low enough does *not* guarantee the submission goes through. The server never sees them; it weighs every file field of the submission together against one budget of its own, so files that each passed check 1 can still be refused as a group. The user gets an error toast naming both numbers, and the form is never sent:

```
The submission carries 12.6 MB of files, more than the 10 MB this form accepts. Send fewer or smaller files.
```

To stay clear of it, keep the whole form's uploads under the budget for its **Form Type**, and move a form that needs more than 10 MB onto **Multipart/Form-Data**. The numbers, the reason they differ, and the one case that fails without this message are in [File Size Limits](../../reference/data-binding/form-submission-types.md#file-size-limits).

::: warning No file inputs in "Open view with form data"
A form whose **Form Type** is **Open view with form data** *cannot* contain a file input -- the builder shows a clear validation error if you try.
:::

## Builder Validation Warnings

The builder itself validates form structure and shows **Action required** cards directly on the canvas inside an empty form:

* **Missing input field** -- with an **Add input** quick-fix button. Add an input block between the `Form Start` and `Form End` rows.
* **Missing submit button** -- with an **Add submit button** quick-fix button. Add a button anywhere in the view, set **Button Type** to **Form Submit Button**, and select this form in the **Form** dropdown.

Each card includes a one-click action button that drops the missing block in the right place.

Other validation rules block save until they are resolved -- see [Saving](../views/publishing.md) for the full list (duplicate input names, submit/reset buttons that point at a non-existent form, file inputs in `Open view with form data` forms, missing URLs).

## Unique Input Names

Each input has a **Name** field (the first row in Block Settings) that becomes the field key when the form is submitted. The builder generates an initial name like `Input` and appends a numeric suffix on duplicates -- a second input becomes `Input_2`, a third becomes `Input_3`, and so on.

You can rename inputs from the **Name** field whenever you want to make the submitted JSON more readable.

::: warning Input names must be unique
If two inputs end up sharing a name (typically by manual editing), the builder flags an `Input name must be unique` validation error and blocks save until you change one.
:::

---

---
url: /how-to/forms/input-field-types.md
---
# Input Field Types and Configuration

> **Type:** How-to | **Audience:** End-user | **Goal:** Configure all input types

## Adding an Input Field

1. Make sure you have a row inside a form. If you do not, see [Creating a Form](creating-a-form.md) first.
2. Click an empty column inside that row to open the **Add block** dialog.
3. Pick **Input** from the list. (The **Input** entry is only enabled when the row sits between a `Form Start` and a `Form End`.)
4. Click the new block to open its settings in the sidebar.
5. Choose the input **Type** from the dropdown.

***

## Basic Types

* **Text** -- standard single-line text input.
* **Textarea** -- multi-line text input.
* **Email** -- text input with email format validation.
* **Number** -- numeric-only input.
* **URL** -- text input with URL format validation.
* **Date** -- date picker.
* **Hidden** -- invisible field, useful for passing data without user interaction. Hidden inputs can never be **Required** or **Disabled**: a change to Hidden turns both switches off and sets both settings back to a switch.
* **File** -- file upload field. See [File Input](#file-input) below for the form-type rules.

### Textarea Input

For **Textarea** type inputs, configure:

* **Rows** -- the number of visible text rows (1--20, default 3).
* **Max Length** -- the maximum number of characters the user can enter. Leave blank for no limit.

### File Input

The rendered field is a row that reads **Drop a file here** (or **Drop files here**), with a **Browse** button on the right. The user either drops files onto the row or clicks anywhere on it to open the file dialog. Under the title, a hint lists the limits you set, such as `One file · max 10 MB` -- a limit you leave empty is left out of the hint. A dropped file goes through the same checks as a picked one.

A single-file input refuses a drop of several files at once: the row turns red and reads **Only one file allowed. Drop a single file.** as soon as the files are dragged over it, and a drop selects nothing. Once a file is selected, the row is hidden; the user removes the file with **X** to choose another.

For **File** type inputs:

* The maximum upload size is **Max File Size (MB)**. It applies to **one file at a time**, not to the selection as a whole. The allowed range depends on the surrounding form's **Form Type**: **JSON** forms allow up to **10 MB**, **Multipart/Form-Data** forms allow up to **100 MB**. The label inside Block Settings shows the active limit, and the field arrives pre-filled with it -- lower the number yourself if you want a tighter check. Switching the form type lowers a value that is too high for the new type, but never raises one you set yourself.
* **Accepted file types** limits the field to the kinds of file you list, such as `.pdf, .png, image/*`. Leave it empty to accept every file. The file dialog offers only the listed types. A file of another type still joins the selection, but its row turns red and the form does not submit until the user removes it. See [File Type Limits](./form-validation.md#file-type-limits).
* A form whose **Form Type** is **Open view with form data** *cannot* contain a file input -- that mode forwards values as URL search parameters and cannot carry files. The builder shows a clear error if you try.

#### Accepting several files

Turn **Allow multiple files** on to let one field carry more than one file. The setting appears on the **File** type only and is off by default.

The field then behaves like this:

1. The row reads **Drop files here**, its hint shows the limits (`Up to 10 files · 100 MB total · 10 MB each`), and the file dialog lets the user select several at once.
2. Each selected file gets a row showing its name and size. When **Max File Size (MB)** is set, the row shows `size / limit`, and a file over the limit turns red. A file that is not one of the **Accepted file types** turns red too.
3. Under the rows, a running summary reads `3 files · 12.4 MB / 100 MB` -- the count, the size of the selection so far, and the total-size limit when one is set. It turns red as soon as the selection breaks **Max Number of Files** or **Max Total Size (MB)**; a file that is too large or of another type turns its own row red instead.
4. The **X** on a row removes that one file; the rest stay selected.
5. Under the summary, a slimmer row reads **Add files** -- dropping or picking again *adds* to the selection instead of replacing it. A file that is already in the list is skipped.

**Which limits to set.** A multi-file field has three:

| Setting | Set it to |
|---|---|
| **Max File Size (MB)** | The largest single file the endpoint can handle. |
| **Max Total Size (MB)** | What the endpoint can take in one request. Keep it at or under the budget for the form type, or the server refuses the submission even though the field accepted it. |
| **Max Number of Files** | How many attachments the field is for. Pre-filled with 10; the highest you may set is 25 on JSON forms and 50 on Multipart/Form-Data. |

Each limit has its own message, so the user is told which one they passed rather than being left to guess. Put a form meant for several sizeable files on **Multipart/Form-Data**. See [File Size Limits](../../reference/data-binding/form-submission-types.md#file-size-limits).

**Before you turn it on for a live field:** the setting changes what the endpoint receives, so update the integration first. See [File Fields](../../reference/data-binding/form-submission-types.md#file-fields).

***

## Selection Types

Selection inputs let users choose from a list of options:

* **Checkbox** -- multiple selections with checkboxes.
* **Radio** -- single selection with radio buttons.
* **Single Select** -- dropdown for a single selection.
* **Multi Select** -- dropdown for multiple selections.

Each selection type has an **Options Type** dropdown with two values: **Static** or **Dynamic**.

### Static Options

1. Set **Options Type** to **Static**.
2. Click **Manage options** to open the editor and add rows. Each row has:
   * **Label** -- text shown to the user. Required.
   * **Value** -- value submitted when this option is selected. Required.
3. Use the editor's **Add Option** button to append rows; click **Save Options** to commit.

Both Label and Value must be at least 1 character long.

### Dynamic Options

1. Set **Options Type** to **Dynamic**.
2. Fill the fields:
   * **Labels Delimiter** -- character used to split the resolved labels string. Default: `,`.
   * **Values Delimiter** -- character used to split the resolved values string. Default: `,`.
   * **Labels** -- Data Picker expression that resolves to the option labels.
   * **Values** -- Data Picker expression that resolves to the option values.

A warning banner inside Block Settings reminds you that if your data contains the delimiter character, the options may be split incorrectly.

***

## Default Values

Use the **Default Value** field to pre-fill the input. The field supports the Data Picker, so you can bind the default to any resource field or variable. Help text under the field changes per Type to describe what is expected (for example `YYYY-MM-DD format` for Date, `Coerced to a number` for Number).

For selection inputs with **Static** options, the **Default Value** field gains a small swap button next to its label. The button toggles between two modes:

* A **dropdown** of the static options (the selection's stored value is the option's `value`).
* A **plain-text input** that supports template variables -- type the option's `value` directly, optionally as a Data Picker expression. For multi-value selections (Checkbox / Multi Select) separate values with commas.

## Labels and Help Text

* **Label** -- text label displayed above the input field.
* **Help text** -- smaller hint text shown below the input. Supports the Data Picker.
* **Placeholder** -- hint text shown inside the empty input. Available on **Text**, **Textarea**, **Email**, **Number**, **URL**, **Single Select**, and **Multi Select** only -- Checkbox, Radio, Date, File, and Hidden inputs hide the Placeholder field. Supports the Data Picker.

## Validation Settings

* **Required** -- toggle to make the field mandatory. Click the ⇄ button beside the label to take the value from data instead: see [Required from data](form-validation.md#required-from-data). Hidden inputs cannot be Required.
* **Pattern** -- regex pattern for custom validation. Available on Text, Textarea, Email, Number, URL, and Date. Must be a valid regular expression.
* **Pattern Error** -- custom error message shown when pattern validation fails. Only appears once Pattern has a value.
* **Disabled** -- toggle to make the field read-only. A disabled field sends its **Default Value** and skips its validation. Click the ⇄ button beside the label to take the value from data instead; the same `true` / `yes` / `1` rule applies as for Required. Hidden inputs cannot be Disabled.

For numeric bounds (**Min**, **Max**, **Min Error**, **Max Error**) and file size limits, see [Form Validation](form-validation.md).

## Style and Visibility

The Input block uses the standard **Style** sub-tab (background, font, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../layout/block-styles.md) and [Conditional Visibility](../visibility/conditional-visibility.md).

---

---
url: /reference/block-types/alert.md
---
# Alert Block

> **Type:** Reference | **Audience:** Interface builder user

The Alert block shows a colored notification banner with a title and description. Use it to draw attention to messages, warnings, or errors inside a view.

## Settings

| Setting | Description |
|---|---|
| **Variant** | The color and icon style. Pick from **Default**, **Destructive**, **Info**, **Success**, **Warning**. In dynamic mode, bind the variant to data instead. |
| **Title** | The alert's title text. Supports the Data Picker. |
| **Description** | The alert's body text. Supports the Data Picker. |

### Variant modes

Variant has two modes — switch between them with the mode selector at the top of the Variant section:

* **Static** — pick a specific variant (Default, Destructive, Info, Success, Warning).
* **Dynamic** — bind the variant name to data via the Data Picker. The resolved value must match one of the static variant names; anything else falls back to the default style.

## Style and Visibility

The Alert block also has the standard **Block Style** section (background, text, borders, radius) and **Conditional Visibility** section available to every block.

---

---
url: /reference/block-types/avatar.md
---
# Avatar Block

> **Type:** Reference | **Audience:** Interface builder user

The Avatar block shows a circular profile image with a text fallback. When the image cannot be loaded, the block shows initials extracted from the fallback text instead.

## Settings

| Setting | Description |
|---|---|
| **Image URL** | The URL of the image to display. Supports the Data Picker. |
| **Fallback Name** | Text shown when the image cannot load. Initials come from the first two words -- for example `John Doe` becomes `JD`. A single-word value uses just the first letter. An empty value renders as `?`. Supports the Data Picker. |
| **Size** | Pick **Small (32px)**, **Medium (40px)** (default), or **Large (56px)**. |

## Style and Visibility

The Avatar block uses the standard **Style** sub-tab (background, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/badge.md
---
# Badge Block

> **Type:** Reference | **Audience:** Interface builder user

The Badge block renders a small status label. Use it for tags, statuses, or categories inside your view.

## Settings

| Setting | Description |
|---|---|
| **Variant** | The badge's color style. Pick from the list below. In Data mode, bind the variant name to data. |
| **Text** | The badge's label. Supports the Data Picker. |

### Variant modes

The Variant field has two tabs:

* **Select** -- pick a specific variant from a dropdown.
* **Data** -- bind the variant name to data via the Data Picker. The resolved value must match one of the variant identifiers below; anything else falls back to the default style.

### Variants

| Display label | Identifier (Data mode) |
|---|---|
| **Default** | `default` |
| **Destructive** | `destructive` |
| **Info** | `info` |
| **Success** | `success` |
| **Warning** | `warning` |
| **Secondary** | `secondary` |
| **Outline** | `outline` |
| **Pink** | `pink` |
| **Violet** | `violet` |
| **Light Blue** | `lightBlue` |
| **Disabled** | `disabled` |

## Style and Visibility

The Badge block uses variant-based styling, so the **Style** sub-tab does not apply -- it shows an info message that custom block styles are not applied to badge components. The standard **Visibility** sub-tab works the same as for every other block. See [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/button.md
---
# Button Block

> **Type:** Reference | **Audience:** Interface builder user

The Button block renders a clickable button. What happens on click depends on the **Button Type** you pick: open a URL, navigate to another view, submit a form, or reset a form.

## Common Settings

These appear for every button regardless of type.

| Setting | Description |
|---|---|
| **Button Type** | Determines what the button does. Options: URL Button, Action Button, Form Submit Button, Form Reset Button. A brand-new button has no type until you pick one. |
| **Button Variant** | The visual style of the button. See the list below. |
| **Button Size** | Small, Default, or Large. |
| **Icon before text** | Optional glyph shown to the left of the button's text. See Icons below. |
| **Icon after text** | Optional glyph shown to the right of the button's text. Unavailable while **Show text** is off. See Icons below. |
| **Show text** | On by default. Turn it off for an icon-only button. Unavailable until you have picked an icon. See Icons below. |
| **Block name** | The button's visible label. Edit it in the name input at the top of the Block Configuration sidebar; on the canvas it is shown read-only. It is plain text: the Data Picker does not apply to it, and it is not resolved from data at render time. |
| **Require confirmation** | Off by default. Turn it on to ask the user before the button's action runs. See Confirmation below. |

### Button Variant

| Variant | Appearance |
|---|---|
| **Default** | Primary filled button. |
| **Destructive** | Red/danger style. |
| **Outline** | Outlined, no fill. |
| **Secondary** | Muted secondary fill. |
| **Ghost** | Transparent background; visible on hover. |
| **Link** | Styled as a text link. |
| **Custom** | Your own colors (see below). |

When you pick **Custom**, four color fields appear:

* **Background color**
* **Text color**
* **Hover background color**
* **Hover text color**

### Button Size

* **Small**
* **Default**
* **Large**

### Icons

A button has two icon slots, **Icon before text** and **Icon after text**. Both sit with Button Size and Button Variant, and both are available on every Button Type — including a button whose type you have not picked yet.

The slots are independent, and **Show text** can hide the text, so five arrangements are reachable:

| Arrangement | How |
|---|---|
| Text only | Leave both slots on **No icon**. This is how every button behaved before the slots existed. |
| Icon + text | Fill **Icon before text**. |
| Text + icon | Fill **Icon after text**. |
| Icon + text + icon | Fill both. |
| Icon only | Fill **Icon before text**, then turn **Show text** off. |

Pick a glyph from the shared catalogue, grouped by meaning: **Actions**, **Navigation**, **Communication**, **Files** and **Status**. Each glyph is shown next to its name in the list. Choose **No icon** to clear a slot.

Notes:

* The glyph is chosen once, in the builder. It does not come from your data, so it cannot change per row or per Area loop iteration, and it cannot be an image URL.
* There is no size or colour setting. A glyph is always 16 px and always takes the button's text colour, so every Button Variant works — the Custom variant's **Text color** reaches the glyph too.
* Icons look the same in the Preview view, the Test view and the published view, and a copied button keeps them.

### Icon-only buttons

Turn **Show text** off to keep the glyph and drop the text. The button becomes a square: its height is the one **Button Size** already gives it, and its width now matches, so an icon-only button lines up with the text buttons beside it. It keeps its corner radius and its **Button Variant** colours, so a Destructive icon-only button still reads as destructive.

Nothing is lost by hiding the text:

* The block name becomes the button's accessible name, so a screen reader announces it.
* The block name also appears as a tooltip when the user hovers the button.
* The block name still reaches your service as the button name in the URL Button metadata, exactly as it does with the text shown.

Two rules keep an icon-only button usable, and the builder applies both:

* **Show text** is unavailable until you have picked an icon, with a note saying so — a button with neither text nor a glyph would be empty.
* **Icon after text** is unavailable while the text is hidden — an icon-only button carries one glyph. If that glyph was in the **Icon after text** slot when you turned **Show text** off, it moves to **Icon before text** for you.

On a **Form Submit Button** with **Show error indicator on submit** enabled, the error message wins the hover: while the form has validation errors the tooltip reports the number of invalid fields instead of the button's name. The error count badge and the loading spinner appear as they do on a button with text, and the accessible name stays in place the whole time.

***

## Confirmation

A confirmation is an optional gate in front of the button's action: the click opens a modal dialog, and the action runs only after the user confirms it. The **Confirmation** section sits at the bottom of the Block Configuration sidebar and is available on every Button Type, including a button whose type you have not picked yet.

| Setting | Description |
|---|---|
| **Require confirmation** | Off by default. Turn it on to gate the button. Turning it off again keeps the texts you wrote, so you can try the button without the gate and put it back. |
| **Title** | The dialog's question. Required, and prefilled with "Are you sure?" on the first enable. Supports the Data Picker. |
| **Description** | Optional explanation below the question. Supports the Data Picker and keeps its line breaks. An empty description leaves the dialog with the question alone. |
| **Confirm Button Label** | The confirming choice's text. Required, prefilled with "Confirm". |
| **Confirm Button Variant** | The confirming choice's appearance. On the first enable it copies the button's own **Button Variant**, so a Destructive button opens a dialog with a Destructive Confirm. A **Custom** button falls back to **Default**. |
| **Cancel Button Label** | The cancelling choice's text. Required, prefilled with "Cancel". |
| **Cancel Button Variant** | The cancelling choice's appearance. Defaults to **Outline**. |

The two variant dropdowns offer **Default**, **Destructive**, **Outline**, **Secondary**, **Ghost**, and **Link**. **Custom** is not offered: it paints both choices from the block's single style object, which would make them identical.

### Behaviour

The dialog is a gate in front of the action, not a report on it. Confirming closes the dialog and runs the action; whatever the action normally shows — a toast, a redirect, an inline alert — follows as usual.

**Cancel** and **Escape** close the dialog and change nothing. Nothing is sent, no form is submitted or cleared, and no navigation happens.

The **Title** and the **Description** resolve from data like any other Data Picker field, and a button inside an Area loop resolves them once per iteration, so each rendered copy asks about its own record. A Title that resolves empty falls back to "Are you sure?"; a Confirm or Cancel label that resolves empty falls back to "Confirm" and "Cancel". The Confirm and Cancel labels are plain text and have no Data Picker.

### Per Button Type

| Button Type | What the confirmation gates |
|---|---|
| **URL Button** | The POST to the URL. The request is sent once, after Confirm. |
| **Action Button** | The navigation. Cancel leaves the reader on the current view. |
| **Form Submit Button** | The submission. See the ordering note below. |
| **Form Reset Button** | The reset. Cancel leaves the typed values in place. |

On a **Form Submit Button** the dialog opens *before* the form is validated, so a user can confirm and then be shown "field required". Fix the field and confirm again. The submission itself is unchanged: validation, the error toast, the error indicator, and the After submission action all run after the confirmation, exactly as they do without it.

Pressing **Enter** in a text input of a gated form opens the dialog instead of submitting: the form intercepts the key and clicks the Submit Button for you, so the gate cannot be bypassed. Shift+Enter and Enter in a textarea keep their normal meaning.

***

## URL Button

Choose **Button Type = URL Button** when clicking the button should open a URL or call your API.

| Setting | Description |
|---|---|
| **Button Identifier** | Optional free-text identifier used when you want to track or reference this specific button. |
| **Button URL** | Pick **Use view base url** to append a path to the view's base URL, or **Use custom url** to specify a full URL. |
| **Path** | Path appended to the view base URL. Shown when Button URL = Use view base url. |
| **Custom URL** | Full target URL. Shown when Button URL = Use custom url. Supports the Data Picker. |
| **Button Body Data** | Request body sent with the call. Supports the Data Picker. |
| **Headers** | Key/value pairs of custom HTTP headers. Header keys may only contain letters, numbers, and hyphens, and must not start with `x-oc-`. |
| **Query parameters** | Key/value pairs appended to the URL. |
| **Wait page transition** | When on, the builder keeps listening for progress updates from your backend after the click. Use this when the action takes a while. |
| **Page Transition Timeout** | How long to keep listening when Wait page transition is on, in seconds. |

***

## Action Button

Choose **Button Type = Action Button** for navigation between views inside the same interface.

| Setting | Description |
|---|---|
| **Action Type** | Pick **go to view** to navigate to a specific view, or **back** to return to the previous view. |
| **View Name** | Dropdown of every view in the interface. Shown when Action Type = go to view. |
| **Parameters** | Optional key/value pairs passed to the target view as search parameters. |

***

## Form Submit Button

Choose **Button Type = Form Submit Button** to submit a form.

| Setting | Description |
|---|---|
| **Form** | Dropdown listing every form in the view (by its Form Identifier). Pick the one this button should submit. |
| **Form Type** | How the form data is packaged and sent. See the three options below. |
| **Submit URL** | The endpoint that receives the submission. Required for **JSON** and **Multipart/Form-Data**. |
| **Headers** | Key/value pairs of custom HTTP headers. |
| **Query parameters** | Key/value pairs appended to the Submit URL. |

### Form Type options

| Option | When to use |
|---|---|
| **JSON** *(default)* | Standard API that expects a JSON body. |
| **Multipart/Form-Data** | The form includes file uploads. |
| **Open view with form data** | Do not call an API at all — navigate to another view and pass all input values as URL search parameters. |

### After submission

Right below Submit URL, the **After submission** setting decides what happens once the data is sent.

**Select view** — navigate to a specific view after sending.

| Setting | Description |
|---|---|
| **View ID** | The view to navigate to after submission. |
| **Parameters** | Key/value pairs passed to the target view. |
| **Use input fields as search params** | When on, every input value from the form is automatically forwarded as a URL parameter. |

**Wait for response** — wait for the server to reply, then act on the response.

| Setting | Description |
|---|---|
| **Timeout (s)** | How long to wait, 10 to 60 seconds. |
| **Disable form after submission** | When on, the submit button stays disabled after a successful response so the user cannot re-submit. |
| **Show message after submission** | When on, a server-provided message replaces the form with an inline alert instead of showing as a toast. |

### Validation feedback

Three toggles control how validation errors on the form are surfaced when the user clicks submit:

| Toggle | What it does |
|---|---|
| **Show error toast on submit** | Shows a toast with the number of invalid fields. |
| **Scroll to first error field** | Smoothly scrolls and focuses the first invalid field. |
| **Show error indicator on submit button** | Shows a small error badge on the button while there are validation errors. |

***

## Form Reset Button

Choose **Button Type = Form Reset Button** when the button should clear the form's fields back to their default values.

| Setting | Description |
|---|---|
| **Form** | Dropdown listing every form in the view. Pick the one to reset. |

***

## Style and Visibility

The Button block also has the standard **Block Style** section (background, text, borders, size) and **Conditional Visibility** section available to every block.

---

---
url: /reference/block-types/chart.md
---
# Chart Block

> **Type:** Reference | **Audience:** Interface builder user

The Chart block renders a bar, line, area, or pie chart from an array in your data.

## Settings

| Setting | Description |
|---|---|
| **Chart Type** | Pick **Bar**, **Line**, **Area**, or **Pie** (default: Bar). |
| **Data Source** | Bind to an array using the Data Picker. Each item in the array becomes a data point. |
| **Data Keys** | Property names to plot, comma-separated. One name for a single series (for example `amount`), multiple for a multi-series chart (for example `desktop,mobile`). Default: `value`. |
| **Name Key** | The property used for the category label on the X axis or pie segment (for example `customer` or `name`). Default: `name`. |
| **Height** | Chart height in pixels, between 100 and 800 (default: 300). |
| **Show Grid** | Show background grid lines. On by default. |
| **Show Tooltip** | Show a tooltip when hovering a data point. On by default. |
| **Show Legend** | Show a legend below the chart. Off by default. |

## Data Shape

**Data Source** must resolve to an array of objects. Each object needs:

* A property whose name matches **Name Key** -- this is the category label.
* One or more properties whose names match the entries in **Data Keys** -- these are the numeric values plotted.

Single-series example (matches the chart above):

```json
[
  { "customer": "Acme Corporation Ltd", "amount": 12500 },
  { "customer": "Nordic Solutions AB", "amount": 2400 },
  { "customer": "TechVenture GmbH", "amount": 8750 },
  { "customer": "Greenfield Industries", "amount": 15000 }
]
```

With **Name Key** = `customer` and **Data Keys** = `amount`, this renders one bar per customer.

Multi-series example:

```json
[
  { "name": "Jan", "desktop": 186, "mobile": 80 },
  { "name": "Feb", "desktop": 305, "mobile": 200 }
]
```

With **Name Key** = `name` and **Data Keys** = `desktop,mobile`, the same data renders as a two-series chart with one bar (or line/area) per series per month.

## Style and Visibility

The Chart block uses the standard **Style** sub-tab (background, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/divider.md
---
# Divider Block

> **Type:** Reference | **Audience:** Interface builder user

The Divider block renders a horizontal separator line. Use it to break content into sections.

## Settings

| Setting | Description |
|---|---|
| **Name** | Internal name shown on the canvas block label and used in builder error messages. Does not appear in the rendered output. |
| **Height** | The thickness of the line in pixels. Default: 1. |

## Default Appearance

Dividers default to a light gray colour (`#E2E8F0`). The line colour comes from the block's **Background Color** setting in the Style sub-tab — change that to recolour the divider.

## Style and Visibility

The Divider block uses the standard **Style** sub-tab (Background Color, per-side **Border** with **Width / Style** of Solid / Dashed / Dotted / **Color**, plus **Border Radius (px)**) and **Visibility** sub-tab in Block Settings, the same as every other block. The Divider block has no font controls — those rows are hidden from its Style sub-tab. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/hover-card.md
---
# Hover Card Block

> **Type:** Reference | **Audience:** Interface builder user

The Hover Card block shows a popup card when the user hovers over a trigger. The trigger can be text, an icon, or both.

## Settings

| Setting | Description |
|---|---|
| **Trigger Type** | Pick **Text Only**, **Icon Only**, or **Text + Icon** -- what the user hovers over (default: Text Only). |
| **Trigger Text** | The trigger's visible text. Shown when Trigger Type is **Text Only** or **Text + Icon**. Supports the Data Picker. |
| **Icon Type** | Pick **Warning (Triangle)**, **Info (Exclamation)**, or **Question (Help)** (default: Question (Help)). Shown when Trigger Type is **Icon Only** or **Text + Icon**. |
| **Icon Color** | Pick **Gray** (default), **Red**, **Yellow**, **Blue**, or **Green**. |
| **Content** | The body of the popup card. Supports the Data Picker. |
| **Width** | Popup width in pixels, between 100 and 600 (default: 320). |
| **Alignment** | **Start**, **Center** (default), or **End** -- horizontal alignment of the popup relative to the trigger. |

## Style and Visibility

The Hover Card block uses the standard **Style** sub-tab (background, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/html.md
---
# HTML Block

> **Type:** Reference | **Audience:** Interface builder user

The HTML block renders custom HTML markup directly inside the view. Use it when you need layouts or styling that the other blocks cannot produce on their own.

## Settings

| Setting | Description |
|---|---|
| **HTML** | The HTML markup to render. Supports the Data Picker -- Data Picker chips inserted into the markup are replaced with their resolved values at render time. Must contain at least one character. |
| **Full width** | Off by default: the block is as wide as its content, so a percentage width in the markup (`width:100%`, `width:33%`) is measured against that content. On: the block fills its column, and percentage widths are measured against the column. Turn it on for markup that should stretch across the row, such as cards that share a row equally. |

The same block in Preview mode renders as plain HTML with the chips replaced by the deal's data:

## Input normalisation

Pasted content (e.g. from ChatGPT or a word processor) is normalised before it is saved:

* Smart quotes (`"`, `"`, `'`, `'`) → straight quotes (`"`, `'`)
* En and em dashes (`–`, `—`) → hyphens (`-`)
* Non-breaking spaces → regular spaces
* Zero-width characters and Windows line endings (`\r\n`) are stripped

Valid HTML entities such as `&amp;` are left intact. The normalisation is silent and only affects the saved value — the builder's editor view keeps the original characters until the page reloads.

## Restrictions

* `<script>` tags are rejected by the builder. Saving fails with the message `HTML should not contain script tags`.
* The rendered HTML is run through a sanitizer (DOMPurify): every tag or attribute that is not on the allow lists below is stripped silently. Inline styles via the `style` attribute are kept.
* Every `a` opens in a new tab: `target="_blank"` and `rel="noopener noreferrer"` are set on render and overwrite any `target` in the markup. `javascript:` URLs are removed from `href`. An `a` with an empty `href` or a bare `#` stays in the output; Table block cells and server message text render such a link as plain text.

### Allowed tags

| Group | Tags |
|---|---|
| Text | `p`, `br`, `hr`, `strong`, `b`, `em`, `i`, `u`, `s`, `strike`, `del`, `ins`, `sub`, `sup`, `small`, `mark`, `abbr`, `code`, `pre`, `blockquote`, `span`, `div` |
| Headings | `h1`, `h2`, `h3`, `h4`, `h5`, `h6` |
| Lists | `ul`, `ol`, `li`, `dl`, `dt`, `dd` |
| Tables | `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, `caption`, `colgroup`, `col` |
| Links and media | `a`, `img`, `figure`, `figcaption` |
| Disclosure | `details`, `summary` |

### Allowed attributes

`href`, `src`, `alt`, `title`, `width`, `height`, `colspan`, `rowspan`, `style`

## Style and Visibility

The HTML block uses the standard **Style** sub-tab (background, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/image.md
---
# Image Block

> **Type:** Reference | **Audience:** Interface builder user

The Image block shows an image from a URL. The URL can be static (typed in by you) or dynamic (resolved from data via the Data Picker).

## Settings

| Setting | Description |
|---|---|
| **Name** | Internal name shown on the canvas block label and used in builder error messages. Does not appear in the rendered output. |
| **Url** | The URL of the image. Supports the Data Picker. |
| **Width** | Optional image width in pixels. When empty, the image uses its natural width constrained by the column. |
| **Height** | Optional image height in pixels. When empty, the image uses its natural height. |

## Render Behaviour

* The rendered `<img>` element always uses the alt text `Picture`. The alt is not exposed as a setting.
* An empty or unresolved **Url** still renders the `<img>` element, but with no `src` — the browser shows it as a broken-image placeholder. Use a `useDefault()` fallback in the Data Picker when the source field may be missing.

## Style and Visibility

The Image block uses the standard **Style** sub-tab (border per side with **Width / Style** of Solid / Dashed / Dotted / **Color**, plus **Border Radius (px)**) and **Visibility** sub-tab in Block Settings, the same as every other block. The Image block does not expose font controls or a Background Color — those rows are hidden from its Style sub-tab. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/input.md
---
# Input Block

> **Type:** Reference | **Audience:** Interface builder user

The Input block renders a form field. It must be placed inside a form -- between a **Form Start** and **Form End** row on the canvas. Every input has a **Label**, a **Type**, and whatever extra settings its Type requires.

## Common Settings

These appear for every input regardless of Type, in this order in the Block Settings sidebar:

| Setting | Description |
|---|---|
| **Label** | The visible text shown above the field. |
| **Type** | Picks the kind of input -- Text, Email, Number, etc. See the list below. |
| **Placeholder** | Hint text shown inside the empty field. Available on **Text**, **Textarea**, **Email**, **Number**, **URL**, **Single Select**, and **Multi Select** only. Supports the Data Picker. |
| **Help text** | Smaller hint text shown below the field (max 128 characters). Supports the Data Picker. |
| **Default Value** | A pre-filled value shown to the user. Supports the Data Picker. The help text under the field changes per Type to describe what's expected (for example `YYYY-MM-DD format` for Date, `Coerced to a number` for Number). |
| **Required** | When on, the form cannot be submitted until this field is filled. The ⇄ button beside the label swaps the switch for a Data Picker field: the field is required when the value is `true`, `yes` or `1` (trimmed, case-insensitive), and optional for any other value, including empty. Hidden fields cannot be Required. |
| **Disabled** | When on, the field is read-only. It sends its **Default Value** on submit and skips its validation. The ⇄ button offers the same Data Picker choice and rule as Required. Hidden fields cannot be Disabled; a change to Hidden turns both settings off and back to a switch. |

## Input Types

### Basic Types

| Type | What the user sees |
|---|---|
| **Text** | Single-line text box. |
| **Textarea** | Multi-line text box. |
| **Email** | Text box with built-in email validation. |
| **Number** | Numeric-only text box. |
| **URL** | Text box with built-in URL validation. |
| **Date** | Date picker. |
| **File** | File upload row: the user drops files onto it or clicks it to open the file dialog. A single-file input refuses a drop of several files. |
| **Hidden** | No UI -- the value is included in the submission but never shown to the user. Useful for pre-filling context data. |

#### Extra settings on basic types

| Setting | Applies to | Description |
|---|---|---|
| **Pattern** | Text, Textarea, Email, Number, URL, Date | Regex pattern that the value must match. Supports the Data Picker. |
| **Pattern Error** | Same as above (only shown after Pattern has a value) | Custom error message shown when the pattern fails. Supports the Data Picker. |
| **Min** | Number | Minimum accepted value. Supports the Data Picker. |
| **Max** | Number | Maximum accepted value. Supports the Data Picker. |
| **Min Error** | Number (only shown after Min has a value) | Custom error message when the value is below Min. |
| **Max Error** | Number (only shown after Max has a value) | Custom error message when the value is above Max. |
| **Allow multiple files** | File | Off by default. On, the input takes several files in one field: the user picks many at once, sees them listed, removes one, and adds more without losing the rest. It also fixes the field's payload shape -- a multi-file input always sends an array, a single-file input always sends an object. See [File Fields](../data-binding/form-submission-types.md#file-fields). |
| **Accepted file types** | File | Empty by default, which accepts every file. One comma-separated list of file extensions (`.pdf`) and MIME types (`application/pdf`, `image/*`); a bare word such as `pdf` reads as `.pdf`, case does not matter, and extra commas are ignored. An entry that is neither form, such as `*.pdf` or `image/`, shows an error under the field. The file dialog offers only these types, and the drop zone hint lists the first three. The drop zone turns red while a file of another MIME type is dragged over it, but never while the list holds an extension whose MIME type the field does not know. A file of another type, such as a dropped one, still joins the selection, but its row turns red and the form does not submit until the user removes it. The list is static: a Data Picker value cannot set it, and the server does not check it. |
| **Max File Size (MB)** | File | Upper size limit for **one file**, weighed against each selected file on its own -- three 5 MB files pass a 10 MB limit. The maximum you can set depends on the surrounding form's Form Type: **JSON** forms allow up to 10 MB, **Multipart/Form-Data** forms allow up to 100 MB, and the label inside Block Settings shows the active one. The builder pre-fills the field with that ceiling, and lowers a value that is too high for the form type when the form type changes -- it never raises one you set yourself. |
| **Max Total Size (MB)** | File, with Allow multiple files on | Upper size limit for **the whole selection added up**. Same ceilings as Max File Size -- 10 MB on JSON forms, 100 MB on Multipart/Form-Data -- and the field arrives pre-filled with the ceiling. |
| **Max Number of Files** | File, with Allow multiple files on | How many files the field accepts at once. Pre-filled with **10** on both form types; the highest you may set is **25** on JSON forms and **50** on Multipart/Form-Data. This is the only setting that stops a user attaching hundreds of tiny files, which a size limit alone lets through. |
| **Rows** | Textarea | Visible rows (1 to 20, default 3). |
| **Max Length** | Textarea | Maximum character count. Leave empty for no limit. |

A **Default Value** of `0` works for Number inputs (it renders as zero, not as an empty field). If you switch a field's Type away from Number, the four numeric settings (Min, Max, Min Error, Max Error) clear automatically. Switching Type away from File clears **Allow multiple files** and **Accepted file types** the same way, and turning **Allow multiple files** off clears **Max Total Size (MB)** and **Max Number of Files** -- they belong to a multi-file field alone.

Switching the surrounding form's Form Type lowers any of the three limits that the new type cannot afford, down to that type's ceiling. It never raises a number you set yourself.

All three limits are browser-side conveniences, not enforced ceilings. The server never reads an input's settings: it weighs every file field of a submission together against one budget of its own and refuses an over-budget submission with `413`. It puts no cap on the file count at all, so **Max Number of Files** narrows what a person can pick through the form and nothing more. See [File Size Limits](../data-binding/form-submission-types.md#file-size-limits) for the numbers the server does enforce.

### Selection Types

| Type | What the user sees |
|---|---|
| **Checkbox** | Multiple-choice checkboxes. |
| **Radio** | Single-choice radio buttons. |
| **Single Select** | Dropdown for a single choice. |
| **Multi Select** | Dropdown for multiple choices. |

Each selection input has:

| Setting | Description |
|---|---|
| **Options Type** | Pick **Static** (you type the options in the builder) or **Dynamic** (options come from data at render time). |

For selection inputs with **Static** options, the **Default Value** field also gains a small swap button next to its label. The button toggles between two modes:

* A **dropdown** of the static options (the selection's stored value is the option's `value`).
* A **plain-text input** that supports template variables -- type the option's `value` directly, optionally as a Data Picker expression. For multi-value selections (Checkbox / Multi Select) separate values with commas.

#### Static options

Click the **Manage options** button and add rows. Each row has:

| Column | Description |
|---|---|
| **Label** | The text shown to the user. |
| **Value** | The value submitted when this option is selected. |

Both columns are required and must be at least 1 character long.

#### Dynamic options

| Setting | Description |
|---|---|
| **Labels Delimiter** | Separator used to split the resolved labels string. Default: `,`. |
| **Values Delimiter** | Separator used to split the resolved values string. Default: `,`. |
| **Labels** | Data Picker expression that resolves to the option labels. |
| **Values** | Data Picker expression that resolves to the option values. |

A warning banner inside Block Settings reminds you that if your data contains the delimiter character, the options may be split incorrectly.

## Form Requirement

An input always needs a surrounding form:

* Place the input between a **Form Start** and **Form End** row.
* The form needs at least one input and at least one **Form Submit Button** pointing at it.
* The **File** type cannot be used in a form whose **Form Type** is **Open view with form data**, because that mode passes values as URL parameters and cannot carry files. The builder shows a clear error if you try.

## Style and Visibility

The Input block uses the standard **Style** sub-tab (background, font, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/navbar.md
---
# Navbar Block

> **Type:** Reference | **Audience:** Interface builder user

The Navbar block renders a navigation menu. It can show a title (brand), a logo, and a list of links. Links can either navigate to another view in the same interface or open an external URL.

## Brand

The **Brand** section at the top of Block Settings groups the title and the logo. Each is hidden by default and revealed by its own switch.

::: tip Renamed
The brand image used to be called the icon. It is now the **Logo**, so that "icon" means one thing in this panel: a catalogue glyph on a link. Nothing about your stored navbars changes.
:::

### Title

Turn on **Show title** to reveal the title fields:

| Setting | Description |
|---|---|
| **Title Text** | The title shown next to the logo. |
| **Font Size (px)** | Font size in pixels, between 12 and 48 (default: 18). |
| **Font Weight** | **Normal**, **Medium**, **Semibold**, or **Bold** (default: Medium). |
| **Title Color** | Text color (default: inherit). |

### Logo

Turn on **Show logo** to reveal the logo fields. The logo is your own image, addressed by URL — it is not one of the catalogue icons a link can carry:

| Setting | Description |
|---|---|
| **Image URL** | The logo image URL. |
| **Alt Text** | Alternative text shown when the image cannot load (default: `Logo`). Also used by screen readers. |
| **Width (px)** | Logo width in pixels, between 16 and 200 (default: 32). |
| **Height (px)** | Logo height in pixels, between 16 and 200 (default: 32). |

## Aria Label

| Setting | Description |
|---|---|
| **Aria Label** | Screen-reader label for the navigation region (default: `Navigation menu`). |

## Layout

| Setting | Description |
|---|---|
| **Layout Direction** | **Horizontal** (links in a row) or **Vertical** (links stacked). |
| **Alignment** | **Left**, **Center**, **Right**, or **Space Between** -- how the links are arranged along the layout direction. |
| **Spacing (px)** | Gap between items, in pixels, 0--50 (default: 8). |

## Navigation Links

Click **Manage Links** to open the link manager dialog. Inside the dialog, click **Add** to append a new link, drag the handle to reorder, and click the trash icon to remove. Each link expands into an accordion with:

| Setting | Description |
|---|---|
| **Label** | The clickable text. Required, even when it is hidden. |
| **Icon before text** | Optional glyph shown to the left of the label. See [Link icons](#link-icons) below. |
| **Icon after text** | Optional glyph shown to the right of the label. Unavailable while **Show text** is off. See [Link icons](#link-icons) below. |
| **Show text** | On by default. Turn it off for a glyph-only link. Unavailable until you have picked an icon. See [Link icons](#link-icons) below. |
| **Link Type** | Pick **Interface** (navigate to another view) or **External URL** (open a URL). |
| **Variant** | The visual style of this link. Default: **Navbar default**. See [Link Variant](#link-variant) below. |
| **Apply to all links** | Copies this link's Variant and its custom colors onto every other link. Shown when the navbar has more than one link. |
| **Target Interface** | Target view dropdown. Shown when Link Type is **Interface**. |
| **Parameters** | Key/value pairs passed as search params to the target view. Shown when Link Type is **Interface**. |
| **URL** | The URL to open. Shown when Link Type is **External URL**. Supports the Data Picker. |

### Link icons

A link has the same two icon slots as the [Button block](button.md#icons), **Icon before text** and **Icon after text**, filled from the same shared catalogue. The slots are independent, and **Show text** can hide the label, so five arrangements are reachable:

| Arrangement | How |
|---|---|
| Text only | Leave both slots on **No icon**. This is how every link behaved before the slots existed. |
| Icon + text | Fill **Icon before text**. |
| Text + icon | Fill **Icon after text**. |
| Icon + text + icon | Fill both. |
| Glyph only | Fill **Icon before text**, then turn **Show text** off. |

Notes:

* The glyph is chosen once, in the builder. It does not come from your data.
* There is no size or colour setting. A glyph is always 16 px and always takes the colour of the label beside it: the navbar's own **Text Color** on a **Navbar default** link, the variant's colour on a link with a variant, and the **Text Color** you picked on a **Custom** link.
* A link has no size setting, so the **Button Size** rule of an icon-only button does not apply here.

### Glyph-only links

Turn **Show text** off to keep the glyph and drop the label. The link becomes a square: its horizontal padding shrinks to the vertical padding it already had, so it stays exactly as tall as the labelled links beside it and the navbar keeps a straight edge.

Nothing is lost by hiding the label:

* The label becomes the link's accessible name, so a screen reader announces it.
* The label also appears as a tooltip when the user hovers the link.

Two rules keep a glyph-only link usable, and the builder applies both:

* **Show text** is unavailable until you have picked an icon, with a note saying so — a link with neither a label nor a glyph would be empty.
* **Icon after text** is unavailable while the label is hidden — a glyph-only link carries one glyph. If that glyph was in the **Icon after text** slot when you turned **Show text** off, it moves to **Icon before text** for you.

### Link Variant

Each link can use one of the same variants as the [Button block](button.md#button-variant): **Custom**, **Default**, **Link**, **Destructive**, **Outline**, **Secondary**, or **Ghost**.

The default choice, **Navbar default**, keeps the classic navbar appearance: a borderless ghost look that follows the navbar's own colors. An explicitly chosen variant takes its appearance entirely from that variant instead — so an explicit **Ghost** is not the same as **Navbar default**, even though they look similar.

### Custom variant colors

Picking the **Custom** variant reveals three color fields:

| Setting | Description |
|---|---|
| **Text Color** | The link's text color. Required. |
| **Background Color** | The link's background color. Required. Check **Transparent** to use no background. |
| **Hover Background Color** | Background color while the pointer hovers the link. Off by default; check **Enable** to set it. |

## Style and Visibility

The Navbar block uses the standard **Style** sub-tab (background, font, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/paragraph.md
---
# Paragraph Block

> **Type:** Reference | **Audience:** Interface builder user

The Paragraph block renders body text. Use it for descriptions, instructions, or any longer text that is not a heading.

## Settings

| Setting | Description |
|---|---|
| **Value** | The paragraph text. Supports the Data Picker, so you can mix static text with placeholders like `{{deal.description}}`. |

## Default Appearance

Out of the box, a Paragraph block renders with:

* Font size: 14 pixels
* Font color: black
* Bold / Italic / Underline: off
* Background: transparent
* Border radius: 0

You can change any of these in the block's **Style** sub-tab.

## Style and Visibility

The Paragraph block uses the standard **Style** sub-tab (background, font, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/table.md
---
# Table Block

> **Type:** Reference | **Audience:** Interface builder user

The Table block shows a grid of data sourced from an array. It supports value columns, action columns, sub-row expansion, and per-column sorting.

## Top-Level Settings

Click the table block to open its settings. The Configuration sub-tab shows these fields, in this order:

| Setting | Description |
|---|---|
| **Table Title** | Optional title shown above the table. Plain text: the Data Picker is not available here, and a typed placeholder shows as written. |
| **Title Alignment** | **Left**, **Center**, or **Right** -- how the title is aligned above the table. |
| **Default Cell Alignment** | **Left**, **Center**, or **Right** -- the default horizontal alignment for all cells unless a column overrides it. |
| **Target Array** | The data source. Must resolve to a single array -- for example `{{resource.items}}`. Required. The Data Picker is restricted to array-type fields. |
| **Empty table text** | Message shown when the Target Array is empty (max 255 characters). Supports the Data Picker. |
| **Sum label** | Optional text for the Sum row. Supports the Data Picker. It renders in the first visible column that has no sum of its own, action columns included. When every visible column has a sum, the label has nowhere to go and is left out. |
| **Allow export** | Off by default. When on, an **Export** menu appears on its own right-aligned row between the Table Title and the table, from which the reader downloads the table as a CSV file or copies it to the clipboard. See [Table export](#table-export). |
| **Manage Columns** | Button that opens the column editor (see below). |

## Manage Columns

Clicking **Manage Columns** opens a dialog with two panels:

* **Left panel** -- the column list with a per-column **...** menu (Copy / Delete) and a drag handle to reorder. The bottom **Add** button opens a dropdown with three choices: **Add value column**, **Add action column**, **Add subrow**. The **Add subrow** entry is disabled when the table already contains a subrow column (only one is allowed per table).
* **Right panel** -- the settings for the selected column, organised into tabs: **General**, **Styling**, **Sorting**, **Sum**, **Hover card**, and **Conditional**. The **Sum** and **Hover card** tabs are offered on value columns only. The General tab also shows a **Column Overview** with summary cards for Styling, Sorting, and Conditional; clicking a card jumps to that tab.

## Column Types

Each column is one of three kinds. The fields under **General** depend on the kind.

### Value Column

A value column shows one data field per row.

| Field (General tab) | Description |
|---|---|
| **Header** | The column's header text. Supports the Data Picker. Required. |
| **Value(s)** | The path to the field within each row item (for example `name` or `price`). Supports the Data Picker. Required. |

The resolved value renders as HTML through the same sanitiser and allow lists as the [HTML block](./html.md#restrictions). Links behave differently from the HTML block:

* Every `a` opens in a new tab with `rel="noopener noreferrer"`. A `target` in the markup is overwritten.
* An `a` whose `href` is empty, whitespace, missing or a bare `#` renders as its text only. A `javascript:` URL is removed first, so it renders as text too. An anchor such as `#section` stays a link.

The same rules apply to subrow cells.

### Action Column

An action column renders one button per configured action, repeated for each row. A button shows an icon, a text label, or both.

| Field (General tab) | Description |
|---|---|
| **Header** | The column's header text. Supports the Data Picker. |
| **Actions** | The list of action buttons for each row. Click **Add Action** to append; each action is its own collapsible section (see below). |

Each action inside an action column has:

| Setting | Description |
|---|---|
| **Icon** | Pick from the grouped set: **Actions** (View, Edit, Delete, Add, Copy, Play, Refresh, External link), **Navigation** (Arrow up, Arrow down, Arrow left, Arrow right, Chevron up, Chevron down, Chevron left, Chevron right), **Communication** (Mail, Send, Phone, Message, Bell, User), **Files** (File, Folder, Download, Upload, Image, Attachment, Print, Archive), **Status** (Check, Close, Warning, Info, Clock, Star, Heart, Lock, Unlock), or **Custom** (Custom), the last group in the list. Required unless the action has a **Label**: the picker offers **No icon** only while the Label holds text. Clearing the Label removes that choice and writes the **View** icon back, so an action is never left with neither. |
| **Custom icon** | Custom image URL. Shown when Icon is **Custom** and supports the Data Picker. |
| **Label** | Optional text shown beside the icon. Supports the Data Picker and resolves per row, so two rows can show different texts. An empty resolved label leaves the button icon-only. Shown when Action Type is selected. |
| **Icon position** | Choose **Before the text** (default) or **After the text**. Shown only when the action has both an Icon and a Label. Only the icon moves; the text keeps its place, and the request state icons (spinner, tick, cross) appear at the same position. |
| **Action Type** | Pick **Go to view** (navigate within the interface), **Go to URL** (open a URL), or **Send request** (send a POST without leaving the table). |
| **View Name** | Destination view dropdown. Shown when Action Type is **Go to view**. |
| **Params** | Key/value pairs passed to the destination view. Shown when Action Type is **Go to view**. |
| **URL** | Destination URL. Shown when Action Type is **Go to URL**. Supports the Data Picker. |
| **Request URL** | Absolute HTTP or HTTPS endpoint. Shown when Action Type is **Send request**. Supports the Data Picker for per-row values. |
| **Body Data** | Optional JSON payload, configured as JSON or key-value pairs. Supports per-row Data Picker values. Include the row's identifier because OneClick metadata identifies the view resource, not the row. Empty means no configured body. |
| **Omit OneClick metadata envelope** | Off by default. When off, OneClick sends Body Data alongside its metadata envelope. When on, it sends only Body Data for third-party endpoints that expect a bare payload. |
| **Disabled** | Shown when Action Type is **Send request**. A Data Picker expression evaluated per row. When the resolved value is `true`, `yes`, or `1` (case-insensitive, surrounding spaces ignored), the button starts disabled with the Muted appearance, regardless of **Disabled appearance**. Any other value — including empty — leaves the button enabled. A row disabled this way shows no row-level warnings, so an empty resolved Request URL on such a row is not an error. The value re-resolves on every data refresh, so an endpoint that returns a truthy value keeps the row disabled across page reloads. |
| **Disable button** | For **Send request**, choose **Never** (default), **After click**, or **After successful response**. After-click actions stay disabled even when the request fails; after-success actions can be retried after failure. The spent state survives sorting, but resets on a page reload — including the reload that **Refresh after success** triggers. |
| **Disable scope** | Shown when Disable button is not **Never**. Choose **Clicked button only** (default) or **Same action on all rows**. Same-action scope affects the same action position in this action column; neighboring actions and other columns remain active. Other affected rows use the Muted appearance. |
| **Disabled appearance** | Shown when Disable button is not **Never**. Choose **Neutral** (default), **Success**, or **Destructive** for the clicked button's spent state. |
| **Refresh after success** | Off by default. When on, a successful request reloads the page after a short delay, so the confirmation tick and toast stay visible. The scroll position is restored after the data loads. Failed requests do not reload; redirect responses navigate without reloading. |
| **Require confirmation** | Shown when Action Type is **Send request**. Off by default. When on, the row's button opens a confirmation dialog and sends the request only after the reader confirms it. Cancel and Escape send nothing and leave the button as it was. A disabled button never opens the dialog. |
| **Title**, **Description** | The dialog's question and its optional explanation. Shown when Require confirmation is on. The first enable fills in "Are you sure?". Both accept Data Picker values and resolve per row, so the dialog can name the row: `Delete {{order_name}}?` shows each row's own order. A title that resolves empty falls back to "Are you sure?"; a description that resolves empty is left out of the dialog. |
| **Confirm Button Label**, **Confirm Button Variant** | The label and the appearance of the confirming choice. Defaults to "Confirm" and **Default**. |
| **Cancel Button Label**, **Cancel Button Variant** | The label and the appearance of the cancelling choice. Defaults to "Cancel" and **Outline**. |

Every action needs an Icon or a Label. An action with neither is rejected by the settings panel and renders a warning instead of the button in every row.

A Label that resolves empty on a single row is handled by the Icon: the row falls back to the icon-only button. Without an Icon that row has nothing left to show, so it renders the same row-level warning an empty resolved Request URL renders. Fix it by widening the Data Picker path or by picking an Icon for the rows that have no text.

The resolved Label becomes the button's accessible name. Without a Label, a Request action reads as `Send request: <column header>` as before.

Labels are presentation only. The outgoing request is unchanged: the OneClick metadata still sends `button_name` as the action column's header, falling back to the column key when the header is empty.

### Subrow Column

A subrow column expands nested data as child rows under each row.

| Field (General tab) | Description |
|---|---|
| **Value(s)** | The path to the nested array inside each row item. Required. |

Subrow columns have no Header, no actions, and no Sorting tab. Only one subrow column is allowed per table.

## Styling Tab (per column)

| Setting | Description |
|---|---|
| **Width** | Optional column width -- a number (pixels) or a percentage. Leave empty for **Auto**. |
| **Cell Alignment** | Override the table's Default Cell Alignment for this column (Left / Center / Right). |
| **Cell Padding** | Switch. When on, four pixel inputs (**Top / Right / Bottom / Left**) appear and override the table-level padding for this column. |

## Sorting Tab (per column)

Subrow columns do not have this tab.

| Setting | Description |
|---|---|
| **Allow sorting** | Switch that lets users sort by this column. |
| **Sort by this column** | Checkbox. Makes this the default sort column when the table loads. Shown when Allow sorting is on. |
| **Sort direction** | **Ascending** or **Descending** -- the default sort order. Shown when Sort by this column is on. |
| **Custom sort value** | Switch. When on, a **Sort value** Data Picker appears. Use this to sort by a different field than the one displayed -- for example sort by a raw number while displaying a formatted currency. |

## Sum Tab (per column)

Value columns only. Action and subrow columns have no Sum tab.

An enabled sum adds one cell to the **Sum row**, a footer row at the bottom of the table. The total covers every row of the Target Array. Sorting reorders rows only, so it never changes a total. A table with no rows shows no Sum row.

Every field on this tab carries an info icon beside its label. Hover it, or reach it with the keyboard, for the same explanation given here.

| Setting | Description |
|---|---|
| **Show sum** | Switch. Adds a Sum row cell under this column. Turning it off clears the tab's other fields. |
| **Sum value** | The field each row is totalled from. Supports the Data Picker. Point it at the raw source value, not the formatted cell -- non-numeric values are skipped. Required when Show sum is on. Shown when Show sum is on. |
| **Format** | **Plain number** (default) or **Currency**. Plain renders the total as it is, with no rounding. Currency renders it through the Locale and the Currency below. Shown when Show sum is on. |
| **Locale** | The locale of the currency format, for example `fi-FI`. It decides the digit grouping, the decimal separator, and the place of the symbol. Supports the Data Picker. Required in the currency format. Shown when Format is **Currency**. |
| **Currency** | The ISO 4217 code of the currency format, for example `EUR`. Supports the Data Picker. Required in the currency format. Shown when Format is **Currency**. |
| **Prefix** | Optional text before the finished total, in both formats. Supports the Data Picker. No space is added -- write `Total ` with the trailing space. Shown when Show sum is on. |
| **Suffix** | Optional text after the finished total, in both formats. Supports the Data Picker. No space is added -- write ` / month` with the leading space. Shown when Show sum is on. |

A currency format the browser cannot honour -- an empty or unknown Locale or Currency -- renders no total at all, and the Prefix and the Suffix then have nothing to wrap. Switching Format back to **Plain number** clears the Locale and the Currency, but keeps the Prefix and the Suffix.

## Hover Card Tab (per column)

Value columns only. Action and subrow columns have no Hover card tab.

A **Cell hover card** is extra content that opens when a reader hovers a cell's value with the pointer. The field resolves per row, so each row's card says something about that row.

| Setting | Description |
|---|---|
| **Hover card** | Optional. The card content. Supports the Data Picker and compiler functions, and spans several lines. HTML is allowed. |

How the card renders:

* A row whose card has content shows the cell value with a dotted underline. Hover the value to open the card. The card stays open while the pointer is over it, so the reader can click a link in it.
* A row whose card resolves to nothing shows no underline and no card. A row whose cell value resolves to nothing shows no card either: the card hangs on the value's text. To show a card on such a row, give the value a text such as a dash.
* The content renders as sanitised HTML, with the same rules as a cell: every link opens in a new tab, and an empty link renders as its text.
* The card has a fixed maximum width. It opens above the value. When there is no room above, it opens below. It moves sideways to stay on the screen.
* The card opens for a pointer only. A touch or a keyboard does not open it, so do not put information there that a reader cannot do without. Put that in a column of its own.
* [Table export](#table-export) does not include the card.

## Conditional Tab (per column)

| Setting | Description |
|---|---|
| **Enable conditional visibility** | Turns visibility rules on or off for this column. |
| **Condition** | A Data Picker expression evaluated at render time. The column is hidden when the value is empty or `"false"`. |

## Table export

**Allow export** is off by default, so a table built before the setting existed shows no Export control. With it on, an **Export** menu renders on its own right-aligned row after the Table Title and before the table. It stays visible while the Target Array has no rows, but is disabled: there is nothing to export.

**Download CSV** writes the file in the browser. No request leaves the page.

What the file carries:

* Every row of the Target Array, in the sorting the reader sees. Sorting the table and exporting again writes the rows in the new order.
* The visible value columns only, in the order they render. A column hidden by its Conditional tab is left out, and so are action columns, the subrow column, the Cell hover cards and the Sum row.
* Each cell as its resolved display text: HTML markup removed, entities decoded, visible line breaks kept. A link exports as its text; the URL is not written. A missing value writes an empty cell. Text that is not renderable markup, such as `a < b`, exports as the literal text even though the table renders a parse error for it.

How the file is written:

* A comma delimiter, CRLF rows and UTF-8 with a BOM, so Excel opens it in the right encoding.
* A value carrying a comma, a quote or a line break is quoted, and a quote inside it is doubled.
* A header or a cell that opens with `=`, `+`, `-` or `@` is written with a leading apostrophe, so the spreadsheet reads it as text and never runs it as a formula. A negative number therefore reads as text in the exported file.
* The file is named `<table-title>-<YYYY-MM-DD>.csv`, with the title reduced to letters, digits and dashes and the date read from the reader's own clock. A table with no title exports as `table-export-<YYYY-MM-DD>.csv`.

### Copy to clipboard

**Copy to clipboard** puts the same rows and the same columns on the clipboard, tab separated, ready to paste into Excel or Google Sheets. Nothing is downloaded and no request leaves the page.

What differs from the file:

* Tabs separate the cells. A value carrying a tab, a quote or a line break is quoted, and a quote inside it is doubled. A comma no longer forces quoting.
* No BOM is written, because the clipboard carries text and not bytes, and no row terminator ends the last row, which would paste an empty row.

Everything else is the same: the row order on screen, the visible value columns, the resolved display text, the line breaks, the empty cells and the leading apostrophe on a cell that opens with `=`, `+`, `-` or `@`.

The clipboard is written with the browser Clipboard API. A view rendered inside an iframe may have no clipboard permission, and a hidden textarea then copies the text instead. Either way the menu closes, and the reader sees `Copied <count> rows to clipboard`, counting the data rows and not the header. When no way to copy works, the menu closes and an error message says the copy failed.

## Validation

* **Target Array** must reference exactly one array. The builder shows an error if the field is empty, contains a non-array value, or references multiple arrays.
* **Value(s)** is required on value and subrow columns; **Header** is required on value columns.
* **Custom sort value** requires a non-empty **Sort value** path.
* **Show sum** requires a non-empty **Sum value** path.
* The currency **Format** requires a non-empty **Locale** and a non-empty **Currency**.
* A **Request URL** must resolve to an absolute HTTP or HTTPS URL on each row.
* Non-empty **Body Data** must resolve to valid JSON on each row.
* **Column key** values must be unique across all value columns in the table.

## Borders and Padding

Open the block's **Style** sub-tab to configure borders and padding. The Table block adds three extra controls on top of the standard block borders:

* **Row border** -- enable/disable, width (px), style, and color for the lines between rows.
* **Cell border** -- enable/disable, width (px), style, and color for the lines between cells.
* **Global Cell Padding** -- switch. When on, four pixel inputs (Top / Right / Bottom / Left) apply to every cell unless a column overrides them via its own Styling > Cell Padding.

The regular block border (Top, Right, Bottom, Left) still applies to the outer table frame. See [Block Styles](../styles/block-styles.md) for the standard border controls.

## Style and Visibility

The Table block uses the standard **Style** sub-tab (background, borders, radius, plus the table-specific borders and padding above) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/block-types/title.md
---
# Title Block

> **Type:** Reference | **Audience:** Interface builder user

The Title block renders a large heading. Use it for page titles, section headings, and anywhere you need prominent text.

## Settings

| Setting | Description |
|---|---|
| **Text** | The heading text. Supports the Data Picker, so you can mix static text with placeholders like `{{deal.title}}`. |

## Default Appearance

Out of the box, a Title block renders with:

* Font size: 22 pixels
* Font color: black
* Bold / Italic / Underline: off
* Background: transparent
* Border radius: 0

You can change any of these in the block's **Style** sub-tab.

## Style and Visibility

The Title block uses the standard **Style** sub-tab (background, font, borders, radius) and **Visibility** sub-tab in Block Settings, the same as every other block. See [Block Styles](../styles/block-styles.md) and [Conditional Visibility](../../how-to/visibility/conditional-visibility.md).

---

---
url: /reference/data-binding/data-picker.md
---
# Data Picker

> **Type:** Reference | **Audience:** Interface builder user

The Data Picker is the tool you use to insert dynamic data into any block setting. It opens as a tooltip next to the field you click into. Every field in the builder that says "supports the Data Picker" opens this picker.

## Tabs

The picker shows up to ten tabs at the top, each a different data source:

| Tab | What you find there |
|---|---|
| **Deal** | The current Pipedrive deal's fields (title, value, owner, and so on). |
| **Organization** | The current organization's fields. |
| **Person** | The current person's fields. |
| **User** | The logged-in Pipedrive user's details. |
| **Custom** | Any data returned from the view's **View URL** call. |
| **Search Params** | URL parameters passed into the view (from a button, a form, or a navbar link). |
| **Variable** | Interface-level variables you have defined. |
| **Functions** | Built-in functions and helper keywords. |
| **Loop item** | The current iteration's data. Appears only when the field sits inside a [looping area](../../how-to/layout/areas.md#looping-an-area). |
| **Context** | The four **System context** values that say where the view runs — `resource_id`, `resource`, `company_id` and `user_id` — plus one **View reference** per view of the same button. |

Not every tab is available in every context — for example, the **Custom** tab does not appear when you are configuring the View URL itself. The picker remembers which tab you opened last.

On a [floating window button](../../explanation/floating-window-buttons.md) the **Deal**, **Organization** and **Person** tabs are gone and the **Context** tab offers only `company_id`, `user_id` and the View references, because that button's views get no Pipedrive record.

## Browsing Fields

For the resource tabs (Deal, Organization, Person, User, Custom, Search Params), the picker shows an expandable tree. Each field can be:

* **Clicked** to insert its placeholder into the input — for example `{{deal.title}}`.
* **Expanded** if it is a nested object, so you can drill down. For example the deal owner is an object: expand **Creator** (`owner_id`), then click **Name**, to insert `{{deal.owner_id.name}}`.
* **Searched** for by name, using the **Search…** box at the top of the tab.

Object fields are expand-only by default — clicking the badge body itself does not insert the whole object, only the chevron expands its children.

### Example values on the Pipedrive tabs

The **Deal**, **Organization** and **Person** tabs show, beside each key, what that key holds in the **Preview record** — the record the Preview and the **Show result** line already run against. The picker names that record at the top of the tab, for example *Example values from Deal #42*. You change the record in the Preview or in the Test view, and the picker follows; no key and no saved placeholder changes with it.

The record is fetched when you open one of those tabs, so opening a view costs nothing until you do.

A long value is cut on the screen at 40 characters, and hovering it shows the whole of it. **Double-click a value to copy the whole of it to the clipboard**, cut or not — the clipboard never gets the shortened text. An item count such as *8 items*, and the dash of a key that is empty on the record, are drawn in place of a value rather than being one, so they copy nothing.

One record does not reach every tab. A chosen deal reaches its organization and its person; a chosen person reaches its organization only. A tab the record does not reach lists its keys as it always does, and says so once at the top instead of showing an empty column. The same line reports a record that could not be loaded — the default **Deal #1** usually does not exist — and the keys stay selectable.

The **User** tab never shows a value, because those keys are filled from the user who runs the view. Inside the **Deal**, **Organization** and **Person** trees, the owner (`owner_id`) — and, on a deal, the creator (`creator_user_id`) — shows the user the fetched record points at, and never the placeholder user the tree's shape is built from.

The **Variable** tab shows a flat list of the view's variables. Confidential variables are hidden unless the current context is allowed to see them.

A variable that is not confidential shows its value beside its key, the same way every other example value is shown. A confidential variable never shows its value here, not even to the person who created it — open the variables page to read it.

## Context Tab

The **Context** tab offers the values that describe *where* a view runs rather than the data it shows. It holds two kinds: the four **System context** values, and one **View reference** per view of the same button.

### System context

Four values that identify the run:

| Value | What it resolves to |
|---|---|
| `resource_id` | The id of the record the view was opened for. In the builder it follows the Pipedrive resource selector. |
| `resource` | The type of that record — `deal`, `organization` or `person`. |
| `company_id` | The Pipedrive company id of the signed-in user. |
| `user_id` | The id of the signed-in user. While you build, this is your own id; every end user later sends theirs. |

Each one is shown with the value this run would actually send, beside its key, so you can see what you are picking before you pick it. `resource_id` and `resource` follow the Pipedrive resource selector, and `company_id` and `user_id` come from your own session.

They carry the same names the URL Button sends in its metadata envelope, because they are the same four values. The tab is most useful in the **View URL**, where a fetch has to be scoped to this company, this user and this record.

::: warning A receiving service must not authorize on these values
A System context value picked into a URL or a header passes through the browser, so a user can change it before the request leaves. The `company_id` and `user_id` of the URL Button's metadata envelope are written by the server and cannot be. Use the envelope, not these values, to decide who may see what.
:::

### View references

Below the four System context values, the tab lists every view of the button you are editing. Each entry is `view_` plus the view's own name, so a view called `main` reads as `view_main` and a view called `Asiakas tiedot` reads as `view_Asiakas tiedot`. The name is shown exactly as the sidebar shows it, spaces and accents included.

Picking one inserts a chip that resolves to **that view's id** — the value you need for a link, a URL parameter or a Request action that points at another view. You no longer have to look the id up by hand.

What a reference stores is the id, never the name:

* **Renaming a view breaks nothing.** The reference still points at the same view, and the chip re-reads the current name — a view renamed from `main` to `asiakastiedot` shows as `view_asiakastiedot` everywhere it is used.
* **Deleting a view is visible.** Every chip pointing at a view that no longer exists turns grey, the same way a chip for a deleted variable does, so you find the broken reference in the builder. In the Preview and in the Test view that reference also resolves to nothing at all, so a test run shows the gap instead of a dead id.

::: tip A deleted view still resolves on the render side
The builder knows every view of the button, so it can tell you a reference is stale. The rendered view does not — it loads only itself — so there a reference always resolves to the id it stores. Fix the grey chips in the builder; do not expect the rendered view to hide them for you.
:::

Only views of the button you are editing are offered. A view of another button would open in the wrong button's context, with that button's Sample data, View URL and variables.

### How the tab behaves

The tab behaves like the resource tabs: it has the same search box — useful on a button with many views — and it is filtered by what the field accepts. A field that takes only a number offers `resource_id`, `company_id` and `user_id`, and a **Target Array** field — which accepts arrays only — does not show the tab at all.

## Functions Tab

The **Functions** tab is laid out as two sections:

* **Keywords** — system text variables (`whitespace`, `emptystring`, `tab`, `newLine`) and system variables (`now`).
* **Functions** — helper functions grouped by category: **Text Processing**, **Mathematics**, **Logic & Comparison**, **Data Validation**, **Date & Time**, **Data Manipulation**.

Hover any function badge to see its description and usage tooltip on the right.

## Loop Item Tab

When the field is inside a looping area, the picker gains an extra **Loop item** tab (a repeat icon). Its content depends on the loop mode:

* **Array mode** — the fields of the current iteration's array item, plus a synthetic `index` field at the end. Click `index` to insert the iteration number (starting at **1**).
* **Count mode** — only the `index` field, since there is no per-item data.

Placeholders inserted from this tab are scoped to the current iteration, so each repetition of the area resolves to a different value.

## Inserting a Field

1. Click into any field that supports the Data Picker.
2. The Data Picker tooltip appears.
3. Pick the tab that has the data you want.
4. Click the field. The placeholder appears inside the input as a small blue "badge".
5. You can keep typing around the badge — text before and after is kept as plain text.

You can insert multiple placeholders into the same field. For example, a Paragraph **Value** can read:

```
Deal: {{deal.title}} - Value: {{deal.value}} {{deal.currency}}
```

At render time each placeholder is replaced with the live value from the matching data source.

## Type Filters

In some contexts, the picker only accepts certain types of fields:

| Filter | What it allows |
|---|---|
| **String** | Text values. |
| **Number** | Numeric values. |
| **Boolean** | True / false. |
| **Object** | Nested structures. |
| **Array** | Lists (for example a Table block's **Target Array** or an Area's **Loop target array**). |

Fields that do not match the active filter are greyed out. Object fields are excluded from the clickable set by default — they always behave as expand-only — unless the surrounding context explicitly accepts objects.

## Expand Dialog

Each Data Picker input has a small expand icon at its right edge that opens a bigger editor in a centred dialog. Use it when you are building a complex expression with multiple placeholders and functions that does not fit comfortably in the small input.

## Working with Inserted Placeholders

Every placeholder and function call you insert shows up as a small badge inside the input, not as raw `{{…}}` text. Badges behave as a single unit:

* Backspace deletes the whole badge.
* Select-and-replace swaps the badge out in one step.
* You can type plain text freely before, between, and after badges.

---

---
url: /reference/data-binding/functions.md
---
# Functions Reference

> **Type:** Reference | **Audience:** Interface builder user

The Data Picker's **Functions** tab exposes 57 helper functions that transform, format, and combine values inside placeholders. They are grouped into six categories below.

The Expand dialog at the right edge of any Data Picker field can preview a function's resolved result while you build the expression.

## Syntax

* Function call: `functionName(param1;param2;param3)`
* Parameters are separated by semicolons (`;`)
* Functions can be nested
* Functions are inserted from the Data Picker's **Functions** tab — you do not type them by hand

## Categories

### Text Processing (16 functions)

| Function | Parameters | Return | Description |
|----------|-----------|--------|-------------|
| `capFirst(text)` | string | string | Capitalizes only the first character. `capFirst(hello)` -> `Hello` |
| `capitalize(text)` | string | string | Capitalizes first letter of each word. `capitalize(hello wORLD)` -> `Hello WORLD` |
| `contains(text;search)` | string, string | boolean | Case-sensitive substring check. `contains(hello world;world)` -> `true` |
| `endsWith(text;suffix)` | string, string | boolean | Checks if string ends with suffix. `endsWith(hello;lo)` -> `true` |
| `first(value)` | array/string | any/string/null | Returns first element of array or first character. `first([1,2,3])` -> `1` |
| `last(value)` | array/string | any/string/null | Returns last element of array or last character. `last([1,2,3])` -> `3` |
| `length(value)` | string/array/object | number | Returns length of string, array, or object keys. `length(hello)` -> `5` |
| `lower(text)` | string | string | Converts to lowercase. `lower(HELLO)` -> `hello` |
| `replace(text;search;replacement)` | string, string, string | string | Replaces first occurrence. `replace(hello world;world;there)` -> `hello there` |
| `replaceAll(text;search;replacement)` | string, string, string | string | Replaces every occurrence. `replaceAll(hello world world;world;there)` -> `hello there there` |
| `slice(value;start;end?)` | string/array, number, number? | string/array/null | Extracts section by index. `slice(hello;1;3)` -> `el` |
| `split(text;delimiter?)` | string, string? | array | Splits a string into an array by the delimiter. With no delimiter the string is split into individual characters. `split(a,b,c;,)` -> `['a','b','c']` |
| `startsWith(text;prefix)` | string, string | boolean | Checks if starts with prefix. `startsWith(hello;he)` -> `true` |
| `stripHtml(html)` | string | string | Removes HTML tags. `stripHtml(<p>Hello <b>world</b></p>)` -> `Hello world` |
| `trim(text)` | string | string | Removes whitespace from both ends. `trim(  hello  )` -> `hello` |
| `upper(text)` | string | string | Converts to uppercase. `upper(hello)` -> `HELLO` |

### Mathematics (5 functions)

| Function | Parameters | Return | Description |
|----------|-----------|--------|-------------|
| `add(values...)` | any\[] (2-10) | string/number/array/object | Concatenates or adds. `add(5;10)` -> `15`, `add(hello;world)` -> `helloworld` |
| `divide(dividend;divisor)` | number, number | number | Divides first by second. `divide(10;2)` -> `5` |
| `multiply(values...)` | number\[] (2-100) | number | Multiplies numbers. `multiply(5;3)` -> `15`, `multiply(2;3;4)` -> `24` |
| `round(value;decimals?)` | number, number? | number | Rounds to nearest integer or decimal places. `round(4.333;2)` -> `4.33` |
| `subtract(minuend;subtrahend)` | number, number | number | Subtracts second from first. `subtract(10;3)` -> `7` |

### Logic & Comparison (12 functions)

| Function | Parameters | Return | Description |
|----------|-----------|--------|-------------|
| `and(values...)` | any\[] (2-100) | boolean | All values must be truthy. `and(true;false;true)` -> `false` |
| `boolean(value)` | any | boolean | Converts any value to `true` or `false`. JavaScript truthiness, except that an empty array and an empty object are `false`. `boolean([])` -> `false`, `boolean([1,2])` -> `true`, `boolean(0)` -> `false` |
| `equals(value1;value2)` | any, any | boolean | Deep equality with strict types. `equals(5;5)` -> `true`, `equals('5';5)` -> `false`, `equals([1,2];[1,2])` -> `true` |
| `gt(value1;value2)` | number/string, number/string | boolean | Greater than (numbers and dates). `gt(5;3)` -> `true` |
| `gte(value1;value2)` | number/string, number/string | boolean | Greater than or equal. `gte(5;5)` -> `true` |
| `if(conditions...;trueValue;falseValue)` | any\[] (3-100) | any | Conditional with AND logic for multiple conditions. `if(true;yes;no)` -> `yes` |
| `lt(value1;value2)` | number/string, number/string | boolean | Less than. `lt(3;5)` -> `true` |
| `lte(value1;value2)` | number/string, number/string | boolean | Less than or equal. `lte(3;3)` -> `true` |
| `not(value)` | any | boolean | Logical NOT (JavaScript truthiness). `not(true)` -> `false`, `not(0)` -> `true` |
| `notEquals(value1;value2)` | any, any | boolean | Inequality with strict types. `notEquals(5;3)` -> `true` |
| `or(values...)` | any\[] (2-100) | boolean | Any value truthy. `or(false;false;true)` -> `true` |
| `switch(input;key1;val1;key2;val2;...default)` | any (3-100) | any | Switch-case matching. `switch(apple;apple;fruit;car;vehicle;unknown)` -> `fruit` |

### Data Validation (5 functions)

| Function | Parameters | Return | Description |
|----------|-----------|--------|-------------|
| `isEmpty(value)` | any | boolean | Checks null, undefined, empty string/array/object. `isEmpty()` -> `true` |
| `isNotEmpty(value)` | any | boolean | Opposite of isEmpty. `isNotEmpty(hello)` -> `true` |
| `isNumber(value)` | any | boolean | Finite number check (excludes NaN, Infinity). `isNumber(123)` -> `true` |
| `isWeekend(date)` | string | boolean | Saturday or Sunday. `isWeekend(2023-01-07)` -> `true` |
| `useDefault(value;defaultValue)` | any, any | any | Returns default if first is empty. `useDefault(;fallback)` -> `fallback` |

### Date & Time (10 functions)

| Function | Parameters | Return | Description |
|----------|-----------|--------|-------------|
| `addDays(date;days)` | string, number | string | Adds days to date. `addDays(2023-01-01;5)` -> `2023-01-06T00:00:00.000Z` |
| `addMonths(date;months)` | string, number | string | Adds months. `addMonths(2023-01-15;3)` -> `2023-04-15T00:00:00.000Z` |
| `addYears(date;years)` | string, number | string | Adds years. `addYears(2023-01-15;2)` -> `2025-01-15T00:00:00.000Z` |
| `daysBetween(startDate;endDate)` | string, string | number | Days between dates. `daysBetween(2023-01-01;2023-01-06)` -> `5` |
| `formatDate(date;format)` | string, string | string | Formats date with locale or pattern. `formatDate(2023-12-25;fi-FI)` -> `25.12.2023` |
| `formatDateTime(date;format)` | string, string | string | Formats date+time. `formatDateTime(2023-12-25T14:30:00;fi-FI)` -> `25.12.2023 14:30` |
| `formatRelative(date;baseDate?;locale?)` | string, string?, string? | string | Relative formatting. `formatRelative(2023-01-01)` -> `yesterday` |
| `subtractDays(date;days)` | string, number | string | Subtracts days. `subtractDays(2023-01-06;5)` -> `2023-01-01T00:00:00.000Z` |
| `subtractMonths(date;months)` | string, number | string | Subtracts months. |
| `subtractYears(date;years)` | string, number | string | Subtracts years. |

### Data Manipulation (9 functions)

| Function | Parameters | Return | Description |
|----------|-----------|--------|-------------|
| `formatCurrency(locale;currency;amount)` | string, string, number | string | Currency formatting. `formatCurrency(fi-FI;EUR;1234.56)` -> `1 234,56 €` |
| `formatList(locale;style;type;items)` | string, string, string, array | string | Locale-sensitive list. Type accepts `and`, `or`, `unit` (also `conjunction`, `disjunction`). `formatList(en-US;long;and;['A','B','C'])` -> `A, B, and C` |
| `get(object;path;defaultValue?)` | object, string, any? | any | Nested property access. `get({"a":{"b":1}};a.b)` -> `1` |
| `join(array;delimiter)` | array, string | string | Joins array elements into a string with the given delimiter. `join(['a','b','c'];, )` -> `a, b, c` |
| `map(array;property)` | array, string | array | Extracts property from objects. `map([{"a":1},{"a":2}];a)` -> `[1,2]` |
| `sort(array;direction;locale?)` | array, string, string? | array | Sorts primitives. Direction: `asc`, `desc`, `natural-asc`, `natural-desc`. Optional locale for natural sort (e.g., `fi-FI`). `sort([3,1,2];asc)` -> `[1,2,3]`, `sort(['img10','img2','img1'];natural-asc)` -> `['img1','img2','img10']` |
| `sortBy(array;key:dir;key:dir?;locale?)` | array, string, string?, string? | array | Sorts objects by key:direction pairs. Default direction `asc`. Supports `natural-asc`/`natural-desc` with locale. `sortBy(list;lastName)`, `sortBy(list;lastName;firstName:desc)`, `sortBy(list;name:natural-asc;fi-FI)` |
| `unique(array)` | array | array | Removes duplicates from primitive arrays. `unique([1,2,2,3])` -> `[1,2,3]` |
| `uniqueBy(array;key1;key2?)` | array, string, string? | array | Removes duplicate objects by key path(s). Supports dot notation and composite keys. `uniqueBy(list;id)`, `uniqueBy(list;firstName;lastName)` |

---

---
url: /reference/data-binding/http-response-format.md
---
# HTTP Response Format

> **Type:** Reference | **Audience:** Interface builder user and the backend developer your view talks to

Two places in an interface call a server: the **Submit URL** on a Form Submit Button, and the **View URL** on a view with a data source. This page lists exactly what the server can return and what each shape does on screen.

For the view data source specifically — the request shape your endpoint receives and the polling behaviour on the builder side — see the [View Data Source reference](view-data-source.md). For the loading sequence and the differences between Test, Preview, and live rendering, see [External Data Flow](../../explanation/external-data-flow.md).

## Overview

| Server call | What it does | Where the response goes |
|---|---|---|
| Form submission | Reacts to a successful or failed submit. | Direct response to the browser. |
| View data source | Feeds live data into the view, or shows a message view. | The builder polls for the response. |

Both places understand the **`oneclick_data`** envelope (for messages and redirects) as well as simpler top-level shapes listed below.

Every message or title that appears to the user passes through an HTML allowlist. See [Messages & Toasts](./messaging.md) for the tags and attributes that survive.

***

## The `oneclick_data` envelope

Wrapping your response in `oneclick_data` gives you a single shape that works for both form submissions and view data sources.

```json
{
  "oneclick_data": {
    "message": "Operation completed successfully",
    "redirect_view": {
      "id": "view-id-string",
      "params": { "key": "value" }
    },
    "event_id": "unique-event-id"
  }
}
```

| Field | Type | What it does |
|---|---|---|
| `message` | string (1–255 chars) | Shown to the user as a success toast. |
| `redirect_view.id` | string | The view to navigate the user to. |
| `redirect_view.params` | object | URL search parameters passed to the target view. |
| `event_id` | string | Short unique event identifier (optional). |
| `error_message` | string or object | Shows the full-page message view instead. See [Error response](#error-response). |
| `message_view` | object | The object form of `error_message` under a neutral name. See [`message_view`](#message-view). |

A success envelope needs `message` or `redirect_view`. An envelope with `error_message` or `message_view` needs neither.

::: warning title and variant live at the top level
`title` and `variant` are not part of `oneclick_data`. For a titled message or a non-success colour (error, warning, info), use the top-level `{ message, title?, variant? }` shape in [Form submission responses](#form-submission-responses). URL buttons do not support titles or variants.
:::

***

## Form submission responses

What you return depends on the submit button's **After submission** setting.

### After submission = Wait for response

The button waits for your response before doing anything. Return one of the shapes below.

**Navigate to another view:**

```json
{ "view_id": "target-view-id" }
```

The user is sent to the view with that ID.

**Show a message:**

```json
{
  "message": "Form submitted successfully",
  "variant": "success"
}
```

* `variant` can be `default`, `destructive`, `info`, `success`, or `warning`.
* Shown as a toast by default (success → green, destructive → red, warning → yellow, info → blue).

**Show a message with a title:**

```json
{
  "message": "Your data has been saved",
  "title": "Success",
  "variant": "success"
}
```

* If the submit button has **Show message after submission** turned off, the title is the toast's primary line and the message is its description.
* If **Show message after submission** is on, the form is replaced with an inline alert carrying the title and message. The view smoothly scrolls to the alert.

**Combine message and redirect:** return the `oneclick_data` envelope described above.

### After submission = Select view

The button navigates to a pre-selected view once the server replies. HTTP 2xx is enough and no body is required. Two optional shapes:

**Plain success confirmation:**

```json
{ "success": "Saved." }
```

Shown as a success toast right before the navigation.

**Message form:**

```json
{ "message": "Saved." }
```

Same effect — toast plus navigation.

### Error responses

Return any HTTP status outside 2xx to trigger the error flow.

| Body | What happens |
|---|---|
| `{ "oneclick_data": { "message": "…", "redirect_view": { … } } }` | Error toast with the message, then navigation if `redirect_view` is present. The trailing "Something went wrong" toast also fires (the body has no top-level `message`). |
| `{ "oneclick_data": { "error_message": "…" } }` | Full-page message view replaces the view, plus a trailing "Something went wrong" toast in the corner. `error_message` can be a plain string or `{ title, message, variant?, hideRetry?, hideBack? }`, where `message` is a string or an array of strings. `message_view` takes the same object and shows the same message view. Plain-string values render with a default title of "Error". |
| `{ "message": "…" }` | Error toast with the message. |
| Anything else | The user sees the generic "Something went wrong". |

The submit button re-enables on error so the user can try again — unless the button has **Disable form after submission** turned on.

***

## URL button responses

URL buttons (buttons with **Button Type = URL Button**) accept any of these three shapes:

1. **A plain string body** (non-JSON) — the shortest way to acknowledge a click.
2. **A JSON object with a top-level `message`** — plain JSON, no envelope needed.
3. **The `oneclick_data` envelope** — required when you also need a redirect.

The first two always render a success toast. The envelope is more nuanced — see [Wait page transition and the envelope](#wait-page-transition-and-the-envelope) below. URL buttons never surface titles or variants, so the same toast style applies no matter which shape you return.

### Plain string response

Return the HTTP body as a raw string instead of JSON:

```
"Item added to cart"
```

The user sees a green success toast containing the string. The text passes through the same HTML allowlist as every other message, so you may include inline HTML like `<b>` and `<a href="…">`. See [Messages & Toasts](./messaging.md) for the full list.

### JSON with a top-level message

If you prefer to return JSON, a top-level `message` alone works:

```json
{ "message": "Item added to cart" }
```

This has the same effect as the plain string — a success toast containing the message.

### Envelope with a redirect

If you need to navigate after the click, the envelope is required:

```json
{
  "oneclick_data": {
    "redirect_view": { "id": "receipt-view", "params": { "order_id": "4321" } }
  }
}
```

The browser navigates to the target view (silent navigation).

If you place a sibling `message` next to `redirect_view` on a URL button, the message is **silently dropped** — only the redirect runs. To show a toast and then navigate, enable **Wait page transition** on the button and stream the toast through the polling endpoint before the final response carries `redirect_view` (see below). Plain strings and `{ "message": "…" }` cannot carry a redirect — use the envelope for that case.

### Wait page transition and the envelope

URL buttons handle the response in two stages: an immediate handler for the very first response, plus an optional polling loop that runs only when **Wait page transition** is on. The `oneclick_data.message` envelope only renders when the polling-aware path is active:

* **Wait page transition off** (the default): only the immediate handler runs. Plain string bodies and top-level `{ "message": "…" }` produce a toast; the envelope-only `{ "oneclick_data": { "message": "…" } }` shape is **silently dropped**.
* **Wait page transition on**: the button polls the server for interim updates (each one becomes a `toast.info`) and at the end shows the final response's `oneclick_data.message` as a `toast.success`. If your final (immediate) response carries both a `message` and a `redirect_view`, the message is dropped — only the redirect runs. Polled responses can carry both, in which case the polled message still shows as `toast.info` just before the redirect.

### Error responses

Any non-2xx status becomes an error toast. The toast text comes from the body if it is a plain string or a `{ message }` object; otherwise the user sees the generic failure message. The button re-enables so the user can try again.

***

## View data source responses

When a view has an external data source, the backend response fills the **Custom** tab in the Data Picker. Return any of the shapes below.

### Regular data (the normal case)

```json
{
  "products": [
    { "id": 1, "name": "Widget", "price": 29.99 },
    { "id": 2, "name": "Gadget", "price": 49.99 }
  ],
  "invoice_total": 79.98
}
```

* Everything in the body becomes available under the **Custom** tab of the Data Picker.
* Nested objects, arrays, strings, numbers, booleans — all work.
* This data is available alongside the Pipedrive data (Deal, Person, Organization).

### Error response

```json
{
  "oneclick_data": {
    "error_message": "Something went wrong"
  }
}
```

or, with a title + message split:

```json
{
  "oneclick_data": {
    "error_message": {
      "title": "Not authorised",
      "message": "Your session has expired. Please sign in again.",
      "hideRetry": false,
      "hideBack": false
    }
  }
}
```

The view shows a full-page message view with **Go Back** and **Retry** buttons instead of rendering blocks. Set `hideRetry: true` or `hideBack: true` to hide either button (both default to `false`).

`message` can also be an array of strings. The message view then shows the items as a bullet list, even when the array has one item:

```json
{
  "oneclick_data": {
    "error_message": {
      "title": "A few things before we continue",
      "message": ["Add a delivery address", "Choose payment terms"],
      "variant": "info"
    }
  }
}
```

| Field | Type | Default | Notes |
|---|---|---|---|
| `title` | string | — | Required. |
| `message` | string or string\[] | — | Required. An array must have at least one item, and no item can be empty. An array is accepted only inside the object form, not as the whole `error_message`. |
| `variant` | `destructive`, `warning`, `info`, `success` or `default` | `destructive` | Sets the colours and the icon of the message view, the same five variants as an Alert. The look only: the response is still an error, so the buttons, the Request action and the form behave the same for every variant. |
| `hideRetry` | boolean | `false` | Hides **Retry**. |
| `hideBack` | boolean | `false` | Hides **Go Back**. |

#### `message_view`

`message_view` is another name for the object form of `error_message`. Use it when the message view is not an error, such as a `success` or `info` note. It takes the same fields and shows the same message view:

```json
{
  "oneclick_data": {
    "message_view": {
      "title": "Almost there",
      "message": "Customer created. Add a contact person and press Retry.",
      "variant": "success"
    }
  }
}
```

* It accepts the object form only. A plain string is invalid.
* A missing `variant` is `destructive`, as with `error_message`.
* The response still counts as not a success, whatever the variant: the buttons, the Request action, `refresh_after_success` and the form behave as they do for `error_message`.
* `message_view` beside `message` or `redirect_view` shows the message view; the toast and the redirect do not happen, as with `error_message`.
* When a response carries both, `error_message` wins and `message_view` is ignored. An invalid `error_message` makes the whole payload invalid, even beside a valid `message_view`.

The icon is fixed per variant and the sender cannot choose it. A payload that breaks these rules, such as an empty array or an unknown `variant`, is invalid `oneclick_data` and is ignored like any other invalid payload.

The same message view also appears when a form submission on this view returns `oneclick_data.error_message` or `oneclick_data.message_view` — the message view takes over the render. Plain-string `error_message` values are shown with a default title of "Error" and the `destructive` variant.

### Redirect response

```json
{
  "oneclick_data": {
    "redirect_view": {
      "id": "target-view-id",
      "params": { "deal_id": "123" }
    }
  }
}
```

The view replaces its content with a centred loading spinner and the text "Redirecting…", then navigates to the target view after a short delay. The text is rendered in-page, not as a toast.

### Timeouts and failures

* **Timeout** — if no response arrives within roughly 20 seconds, the user sees "Request timed out. No custom data received."
* **Non-2xx HTTP status** — the user sees "Data loading failed (status 500)" (or whichever status came back).

Those two messages are built-in — the server cannot customise them. To show a message you control, return the error-response shape above.

***

## See also

* [Form Submission Types](./form-submission-types.md) — how the request is built.
* [Messages & Toasts](./messaging.md) — which HTML tags you can use in `message` and `title`.

---

---
url: /reference/data-binding/form-submission-types.md
---
# Form Submission Types

> **Type:** Reference | **Audience:** Interface builder user and the backend developer your form talks to

A submit button's **Form Type** setting controls how form data leaves the browser. This page lists the three options and exactly how each one packages and delivers the data — useful both when you configure the button and when you hand off the details to whoever writes the endpoint.

## Overview

| Form Type | HTTP request? | Files allowed? | Content-Type | Typical use |
|---|---|---|---|---|
| **JSON** *(default)* | Yes — POST | Yes (base64) | `application/json` | Standard JSON APIs. |
| **Multipart/Form-Data** | Yes — POST | Yes (binary) | `multipart/form-data` | File-storage endpoints and legacy APIs. |
| **Open view with form data** | No | No | n/a | Multi-step flows and filter panels inside the app. |

Pick one, then set the **Submit URL** (required for **JSON** and **Multipart/Form-Data**; ignored for **Open view with form data**).

***

## JSON

**Use when:** the endpoint expects a JSON body.

**How the request reaches the backend:**

* `POST` request to the **Submit URL**.
* Header: `Content-Type: application/json`.
* Body: one JSON object with two top-level keys, `data` and `meta`.
* Files are base64-encoded and embedded inside `data`.

**Body shape:**

```json
{
  "data": {
    "username": "john",
    "email": "john@example.com",
    "profilePhoto": {
      "filename": "photo.jpg",
      "mimetype": "image/jpeg",
      "data": "base64encodedcontent..."
    },
    "attachments": [
      { "filename": "doc1.pdf", "mimetype": "application/pdf", "data": "..." },
      { "filename": "doc2.pdf", "mimetype": "application/pdf", "data": "..." }
    ]
  },
  "meta": {
    "button_id": "btn-1",
    "company_id": 6789,
    "event_id": "abc123",
    "interface_view_id": "view-1",
    "resource": "deal",
    "resource_id": 456,
    "user_id": 12345
  }
}
```

* `data` — every input in the form, keyed by its internal field name.
* A single-file input is one object. A multi-file input — one with **Allow multiple files** turned on — is always an array, including when the person picked one file, so a receiving service never branches on the file count. See [File Fields](#file-fields).
* `meta` — where the submission came from (which view, which button, which Pipedrive resource, which user). `company_id`, `resource_id` and `user_id` are numbers; the rest are strings. `company_id` and `user_id` are added server-side from the authenticated session and overwrite any client-supplied values.
* Any **Query parameters** you add to the submit button are appended to the URL.

**Body shape from a [floating window button](../../explanation/floating-window-buttons.md):** that run has no Pipedrive record, so `resource` and `resource_id` are sent as `null`. Both keys stay in place — the payload shape is the same on both kinds of button, and every other `meta` value is unchanged:

```json
{
  "data": {
    "username": "john",
    "email": "john@example.com"
  },
  "meta": {
    "button_id": "btn-1",
    "company_id": 6789,
    "event_id": "abc123",
    "interface_view_id": "view-1",
    "resource": null,
    "resource_id": null,
    "user_id": 12345
  }
}
```

The values are never faked: a missing record is `null`, never `0` and never `""`.

**With `Omit oneclick metadata` on:** the body is just the inner `data` object — no `meta`, no outer wrapping. Use this for endpoints that reject unknown fields (for example Pipedrive API v2):

```json
{
  "username": "john",
  "email": "john@example.com",
  "profilePhoto": { "filename": "photo.jpg", "mimetype": "image/jpeg", "data": "..." }
}
```

**After submission:** both **Select view** and **Wait for response** are available.

***

## Multipart/Form-Data

**Use when:** the endpoint expects a multipart upload — file-storage APIs, legacy endpoints that cannot parse JSON, or anything that wants files as raw binary instead of base64.

**How the request reaches the backend:**

* `POST` request to the **Submit URL**.
* Header: `Content-Type: multipart/form-data` (the browser adds the correct boundary automatically).
* Every form field is a separate part. The part name starts with `data_` for form inputs and `meta_` for context.

**Parts:**

```
meta_button_id: "btn-1"
meta_company_id: "6789"
meta_event_id: "abc123"
meta_interface_view_id: "view-1"
meta_resource: "deal"
meta_resource_id: "456"
meta_user_id: "12345"

data_username: "john"
data_email: "john@example.com"
data_profilePhoto: (binary, filename="photo.jpg")
data_attachments[0]: (binary, filename="doc1.pdf")
data_attachments[1]: (binary, filename="doc2.pdf")
```

* `data_*` — form input values, keyed by the input's internal field name.
* `meta_*` — the same context as the `meta` object in JSON mode (`company_id` and `user_id` are added server-side from the authenticated session). Multipart is a text transport, so every value arrives as a string.
* Single-file inputs land at `data_<field>`. Multi-file inputs — those with **Allow multiple files** turned on — are always indexed: `data_<field>[0]`, `data_<field>[1]`, and so on, including when the person picked one file. See [File Fields](#file-fields).

**Parts from a [floating window button](../../explanation/floating-window-buttons.md):** multipart form data cannot carry `null`, and the string `"null"` would be a lie. So instead of a placeholder value, the two record parts are **not sent at all** — five `meta_*` parts arrive instead of seven:

```
meta_button_id: "btn-1"
meta_company_id: "6789"
meta_event_id: "abc123"
meta_interface_view_id: "view-1"
meta_user_id: "12345"

data_username: "john"
data_email: "john@example.com"
```

Read the absence of the part as "there is no record". Nothing is sent as `0` or `""`.

**With `Omit oneclick metadata` on:** the `meta_*` parts are not sent and the `data_` prefix on form inputs is dropped — every input goes through under its bare name. The `Content-Type` is still `multipart/form-data`:

```
username: "john"
email: "john@example.com"
profilePhoto: (binary, filename="photo.jpg")
attachments[0]: (binary, filename="doc1.pdf")
attachments[1]: (binary, filename="doc2.pdf")
```

**After submission:** both **Select view** and **Wait for response** are available.

***

## File Fields

**Read this before you write the endpoint.** What decides whether a file field arrives as an array is the input's **Allow multiple files** setting — never how many files the person happened to pick.

| The input | JSON | Multipart/Form-Data |
|---|---|---|
| **Allow multiple files** off | One object under `<field>` | One part named `data_<field>` |
| **Allow multiple files** on | Always an array under `<field>` | Always indexed parts `data_<field>[0]`, `data_<field>[1]`, … |

The two shapes below come from the *same* submission: a form with a single-file input named `profilePhoto` and a multi-file input named `attachments`, where the person picked **one file into each**.

```json
{
  "data": {
    "profilePhoto": {
      "filename": "photo.jpg",
      "mimetype": "image/jpeg",
      "data": "base64encodedcontent..."
    },
    "attachments": [
      { "filename": "doc1.pdf", "mimetype": "application/pdf", "data": "..." }
    ]
  }
}
```

```
data_profilePhoto: (binary, filename="photo.jpg")
data_attachments[0]: (binary, filename="doc1.pdf")
```

`attachments` is an array of one, and stays an array when the person picks five. So the endpoint reads a multi-file field with one code path and never counts first.

::: warning An empty multi-file selection is not an empty array
A multi-file input the person never touched — or emptied again — arrives as the **empty string**, exactly as an empty single-file input always has. It never arrives as `[]`. The field is still present, so testing for the key is not enough — check the value before you iterate.

```json
{ "data": { "attachments": "" } }
```

```
data_attachments: ""
```

In multipart the field arrives as an ordinary text part with an empty value: no indexed parts, and no `filename`.
:::

A form built before **Allow multiple files** existed forwards exactly the payload it always did — the setting is off by default, and an input with it off is untouched by this rule.

**One exception — the redirect URL, not the payload.** When **After submission** is **Select view**, every selected file also becomes a URL parameter carrying its *file name*, and those parameters are indexed for both kinds of input: `attachments[0]=doc1.pdf`. That was true before this rule existed and has not changed, so a view already reading `attachments[0]` keeps working.

***

## File Size Limits

A submission that carries files is weighed against a byte budget before anything is forwarded. The budget belongs to the **Form Type**:

| Form Type | Budget for the files of one submission |
|---|---|
| **JSON** | 10 MB |
| **Multipart/Form-Data** | 100 MB |

* The budget is **one cap per submission, across every file field together**. Two file inputs in the same form share it, and so do the several files of one multi-file input. It is not a per-file limit and not a per-field limit.
* A submission over budget gets HTTP `413` back and is never forwarded to the **Submit URL**. The message names both the budget and the size the submission carried, and the user sees it as an error toast.
* A **Multipart/Form-Data** submission over 100 MB is stopped while the request is still being read, before the budget is ever weighed. It fails, but not with the `413` above, and the error the user sees is not the clear message this section describes. 100 MB is the size limit on the whole request as well as the multipart budget.
* MB means 1 048 576 bytes, the same unit the file input's own size display uses.
* JSON gets the smaller budget because it embeds each file as base64 — the payload the server has to build in memory ends up several times the size of the files themselves. Multipart holds the files in memory too, but roughly once and without the base64 inflation, so it can afford the larger number. A form that needs to move more than 10 MB belongs on **Multipart/Form-Data**.
* A file input's own **Max File Size**, **Max Total Size** and **Max Number of Files** settings are separate, browser-side checks. They can only narrow what a person is allowed to pick; none of them raises the budget above the numbers in the table, and the server puts no cap on the file count at all.

***

## Open view with form data

**Use when:** the submit should not call an API at all, but instead jump the user to another view and carry the form values along as URL parameters. Useful for multi-step flows, search forms, and filter panels inside the interface.

**How it works:**

* **No HTTP request is made.** Any **Submit URL** is ignored.
* The user is navigated to the view picked in the **View ID** field of the **After submission** setting.
* Every form input value is appended as a URL search parameter on that navigation.

**Restrictions:**

* The **File** input type is not allowed — the submission cannot pass binary data through a URL.
* **After submission** must be **Select view** (since there is no server to wait for).

**How values end up in the URL:**

* Each input's internal name becomes the URL key, and the input's value becomes the URL value. Form input values are **always** included on the navigation — there is no opt-out at runtime for this form type.
* Any explicit **Parameters** you set on the submit button are merged on top.
* The **Use input values as search params** toggle on the submit button does not affect runtime URL building — input values are forwarded regardless. The toggle is a *design-time* hint that adds the form's inputs to the **Expected Parameters from Views** list in the target view's URL Configuration dialog, so you can recognise them when wiring up that view's data source.

**Resulting URL example:**

```
/interfaces/{viewId}?username=john&email=john@example.com&customParam=value
```

**Reading the parameters in the target view:**

Open the Data Picker in the target view, switch to the **Search Params** tab, and pick the key you need. The placeholder resolves to the string value at runtime, for example `{{searchparams.username}}`.

***

## Forms Inside a Looping Area

When a form's input rows sit inside a looping [Area](../layout/areas.md#loop), every iteration renders its own copy of each input. Two things change in the submission.

**Field names get an iteration suffix.** The first iteration keeps the original field names; every later iteration appends `_loop_N` (N starting at 1). A looped input `name` submits as `name`, `name_loop_1`, `name_loop_2`, and so on.

**The payload gains an `oc_loop` array.** One object per iteration, each grouping the looped fields' values under their base field names. The array is purely additive — the flat suffixed fields are always sent alongside it.

**JSON mode** — `oc_loop` is a genuine array inside `data`:

```json
{
  "data": {
    "name": "ads",
    "name_loop_1": "muu",
    "oc_loop": [
      { "name": "ads" },
      { "name": "muu" }
    ]
  },
  "meta": { "...": "..." }
}
```

**Multipart/Form-Data mode** — multipart is a flat transport, so the array travels as a JSON string in a `data_oc_loop` part:

```
data_name: "ads"
data_name_loop_1: "muu"
data_oc_loop: "[{\"name\":\"ads\"},{\"name\":\"muu\"}]"
```

**With `Omit oneclick metadata` on:** `oc_loop` is form data, not metadata, so it stays — in JSON mode inside the flat body, in multipart mode under the bare `oc_loop` part name.

**Rules:**

* The key is present only when the submitted form contains looped fields. Zero iterations remove the looped rows entirely — no fields, no `oc_loop` key.
* All loops in one form share the single `oc_loop` array, grouped by iteration index.
* File inputs are excluded from the array — files arrive as flat fields only.
* Disabled looped inputs contribute their default values like any other looped field.
* `oc_loop` is a reserved name. A form input the admin names `oc_loop` is overwritten by the generated array.
* A field name that merely looks looped (an input manually named `something_loop_1`) stays out of the array — only fields rendered by a loop participate.
* **Open view with form data** is unaffected: the URL carries the flat suffixed fields only, never an `oc_loop` parameter.

***

## Comparison

| Aspect | JSON | Multipart/Form-Data | Open view with form data |
|---|---|---|---|
| HTTP request | POST | POST | None |
| Content-Type | `application/json` | `multipart/form-data` | — |
| Files | Base64 inside JSON | Binary parts | Not allowed |
| File budget per submission | 10 MB | 100 MB | — |
| Submit URL | Required | Required | Ignored |
| After submission | Both options | Both options | Select view only |
| Context data (default) | `meta` object | `meta_*` parts | Not sent |
| Input values (default) | `data` object | `data_*` parts | URL search params |
| Looped fields | `data.oc_loop` array + flat suffixed fields | `data_oc_loop` JSON string + flat suffixed parts | Flat suffixed URL params only |
| With `Omit oneclick metadata` | Body is just the inner `data` object | No `meta_*` parts; `data_` prefix dropped from input parts | n/a |

***

## What the Backend Should Return

When the submission actually calls the server (JSON and Multipart/Form-Data), the response controls what the user sees next — a toast, an inline alert that replaces the form, or a navigation. See [HTTP Response Format](./http-response-format.md) for the exact shapes.

---

---
url: /reference/data-binding/messaging.md
---
# Messages & Toasts Reference

> **Type:** Reference | **Audience:** Interface builder user (and the backend developer you pass this to)

Any time Interface Builder shows the user a server-authored message — a toast after a submission, an inline alert, or a data-source message view — the text passes through an HTML sanitiser before rendering. This page describes exactly what is allowed, what is stripped, and where each message surface appears.

## Allowed HTML

Messages and titles may include a narrow subset of HTML: inline formatting, links, paragraph and list structures.

| Tag | Purpose |
|-----|---------|
| `<b>` / `<strong>` | Bold |
| `<i>` / `<em>` | Italic |
| `<u>` | Underline |
| `<br>` | Line break |
| `<code>` | Inline monospace |
| `<a href="...">` | Link |
| `<p>` | Paragraph |
| `<div>` | Generic block wrapper |
| `<ul>` / `<ol>` / `<li>` | Bulleted or numbered list |

Every other tag is stripped. Text inside stripped tags is kept; the tags themselves vanish:

* `"<h1>y</h1>"` → `"y"`
* `"<table><tr><td>x</td></tr></table>"` → `"x"`
* `"<script>alert(1)</script>ok"` → `"ok"`

## Allowed attributes

* `<a>` accepts `href`. All other attributes are dropped.
* Event-handler attributes (`onclick`, `onerror`, and so on) are stripped from every tag.
* `<img>`, `<iframe>`, and similar embeds are removed entirely.

## Link behaviour

Anchors are rewritten to open safely:

* `rel="noopener noreferrer"` and `target="_blank"` are added automatically. Your server cannot override them.
* Only `https:`, `http:`, `mailto:`, and `tel:` schemes are allowed. Any other `href` is removed, including `javascript:`, `data:`, a relative path and an anchor.
* An `<a>` with no `href` left, or with an empty `href` or a bare `#`, renders as its text only.

Example:

| Server sends | User sees / clicks |
|--------------|--------------------|
| `Visit <a href="https://example.com">our site</a>` | "our site" link, opens `https://example.com` in a new tab |
| `Email <a href="mailto:help@example.com">us</a>` | opens mail client |
| `<a href="javascript:alert(1)">click</a>` | "click" with no link |
| `Email <a href="">us</a>` | "Email us" as plain text |

## Variants

The `variant` field in a response controls the message's colour and icon. Five values are recognised:

| Variant | Toast type | Inline alert style |
|---------|------------|--------------------|
| `default` | Success | Neutral |
| `success` | Success | Green |
| `destructive` | Error | Red |
| `warning` | Warning | Yellow |
| `info` | Info | Blue |

Unknown values fall back to `default`.

## Where messages appear

Each response shape decides where the message ends up.

| Response | Appears as |
|----------|------------|
| `{ message, variant }` after **Wait for response** | Toast |
| `{ message, title, variant }` after **Wait for response**, with **Show message after submission** off | Toast (`title` = primary text, `message` = description) |
| `{ message, title, variant }` after **Wait for response**, with **Show message after submission** on | Inline alert that replaces the form; view scrolls to it |
| `{ oneclick_data: { message } }` after a submit or URL button | Toast |
| View data source error `{ oneclick_data: { error_message: { title, message, variant? } } }` or `{ oneclick_data: { message_view: { … } } }` | Full-page message view with Go Back / Retry buttons |
| `{ success: "…" }` after **Select view** | Success toast just before navigation |

Titles and messages in every one of these surfaces go through the same allowlist.

## Empty messages

If `title` is empty or missing, the primary display uses `message` instead. If both are empty, nothing is rendered for that field.

## See also

* [HTTP Response Format](./http-response-format.md) — the exact response shapes that carry these messages.
* [How to format messages](../../how-to/data/messages-and-toasts.md) — practical guide for what to return from your backend.

---

---
url: /reference/data-binding/pipedrive-resources.md
---
# Pipedrive Resources Reference

> **Type:** Reference | **Audience:** Interface builder user

The interface builder connects to Pipedrive CRM data through four resource types. Data is loaded based on the selected Pipedrive object in the resource selector.

## Resource Selector

The resource selector lets the builder pick:

* **Resource type**: deal, organization, or person
* **Specific record**: search and select by name/title

The selected resource determines which sample data fills the Deal, Organization, and Person tabs of the Data Picker while you build. At runtime, the actual record passed to the view is whichever record the OneClick button was opened from in Pipedrive.

A [floating window button](../../explanation/floating-window-buttons.md) is opened from no record, so it has no resource selector and none of Deal, Organization or Person is available to its views — only User, which is read from the signed-in session rather than from a record.

## Resources

### Deal

Access via the `deal` tab in the Data Picker. Contains all standard Pipedrive deal fields plus custom fields.

Common fields include: `id`, `title`, `value`, `currency`, `status`, `stage_id`, `pipeline_id`, `add_time`, `update_time`, `close_time`, `won_time`, `lost_time`, `expected_close_date`, `probability`, `lost_reason`.

Nested objects:

* `owner_id` -- User object (deal owner): `id`, `name`, `email`, etc.
* `creator_user_id` -- User object (the user who created the deal)
* `org_id` -- Organization linked to the deal
* `person_id` -- Person linked to the deal
* Deal products available via related data

### Person

Access via the `person` tab. Standard Pipedrive person fields.

Common fields: `id`, `name`, `first_name`, `last_name`, `email`, `phone`, `add_time`, `update_time`, `visible_to`, `label`.

Nested objects:

* `owner_id` -- User object (person owner)
* `org_id` -- Organization the person belongs to

### Organization

Access via the `organization` tab. Standard Pipedrive organization fields.

Common fields: `id`, `name`, `address`, `address_country`, `cc_email`, `add_time`, `update_time`, `visible_to`, `label`.

Nested objects:

* `owner_id` -- User object (organization owner)

### User

Access via the `user` tab. Represents the current Pipedrive user viewing the interface. Unlike Deal, Person, and Organization, the user is **not selectable** — it is always whoever is logged into Pipedrive when the view opens. At runtime the data comes from Pipedrive's `users.getUser` endpoint; the values in the table below are the sample shape the builder's Data Picker shows for design-time reference.

| Field | Type | Example |
|---|---|---|
| `id` | number | 11257768 |
| `name` | string | "Test Zimple" |
| `email` | string | "test.user@zimple.fi" |
| `locale` | string | "fi\_FI" |
| `timezone_name` | string | "Europe/Helsinki" |
| `timezone_offset` | string | "+03:00" |
| `default_currency` | string | "EUR" |
| `icon_url` | string | Profile image URL |
| `active_flag` | boolean | true |
| `is_admin` | number | 1 |
| `role_id` | number | 1 |
| `company_id` | number | Company identifier |
| `company_name` | string | Company name |
| `company_domain` | string | Company subdomain |
| `language` | object | `{ language_code, country_code }` |
| `access` | array | App permissions list |

## Custom Fields

Pipedrive custom field types supported:

* Text, Varchar, VarcharAuto
* Integer, Double, Monetary
* Enum, Set
* Date, Time, DateRange, TimeRange
* Phone, People, Org, User, Address

Custom fields appear alongside standard fields in the deal, person, and organization tabs. Field keys use Pipedrive's hash-based identifiers (e.g., `abc123def456`).

## Data Structure

At runtime, placeholder resolution accesses dynamic data through a structure:

```
{
  deal: { ...deal fields },
  organization: { ...org fields },
  person: { ...person fields },
  user: { ...user fields },
  custom: { ...View URL response data },
  variables: [ ...interface variables ],
  searchparams: { ...URL search parameters }
}
```

Field values are accessed via dot-path notation: `resource.key` (e.g., `deal.title`, `person.owner_id.name`).

---

---
url: /reference/data-binding/placeholder-syntax.md
---
# Placeholder Syntax

> **Type:** Reference | **Audience:** Interface builder user

Placeholders are the way you insert live data values into the interface. You never type them by hand — you create them by picking a field from the Data Picker, and the builder inserts the placeholder for you. This page is a reference for what they look like, what they can target, and how they behave when the data they point at is missing.

## Basic Syntax

Throughout the docs, placeholders are shown using the readable shorthand `{{resource.key}}` — for example `{{deal.title}}` for a deal's title. This shorthand identifies *what the placeholder points at* and is the form most useful when reading or talking about a view.

The Data Picker actually inserts a longer named-field format under the hood — for example:

```
{{key: 'title', name: 'Title', resource: 'deal', variableType:'normal'}}
```

The runtime resolver reads the resource, key, and metadata directly from those named fields (`{{deal.title}}` written by hand would not resolve to anything because the parser does not find a `key:` or `resource:` to read). You never type this form yourself — the picker generates it and the slate editor displays it as a small badge.

The remainder of this page uses the shorthand for clarity.

Examples:

* `{{deal.title}}` — the deal's title
* `{{person.name}}` — the contact's name
* `{{user.email}}` — the logged-in Pipedrive user's email

## Mixing With Static Text

A single field can hold any combination of static text and placeholders:

```
Deal: {{deal.title}} ({{deal.value}} {{deal.currency}})
```

You can add as many placeholders as you like and type freely around them.

## Nested Fields (Dot Notation)

When a field contains a nested object, dot notation reaches deeper into it:

```
{{deal.owner_id.name}}
```

This first picks the `owner_id` object from the deal, then reads its `name` property. If any step of the path is missing, the placeholder resolves to an empty string (see [When Data Is Missing](#when-data-is-missing) below).

## What Placeholders Can Reference

Each placeholder starts with a **source** — the part before the first dot — that tells it where to look for the data. The sources match the tabs you see in the Data Picker:

| Source | What it reads |
|---|---|
| `deal` | Fields of the current Pipedrive deal |
| `organization` | Fields of the current organization |
| `person` | Fields of the current person |
| `user` | Fields of the logged-in Pipedrive user |
| `custom` | Anything the view's data source URL returned |
| `searchparams` | URL parameters passed into the view |
| `variable` | Interface variables you defined |
| `system` | The four System context values — `resource_id`, `resource`, `company_id` and `user_id` — offered by the **Context** tab |
| `view` | A View reference, also offered by the **Context** tab. It stores the id of another view of the same button and resolves to that id, so renaming the view changes nothing. In the builder, the Preview and the Test view a reference to a *deleted* view resolves to an empty string instead; the rendered view cannot tell and returns the id. |
| *(loop item)* | The current iteration's data when the field sits inside a [looping area](../../how-to/layout/areas.md#looping-an-area). The resource shorthand mirrors the loop's source (for example `{{deal.products.name}}` inside an area looping over `deal.products`); the synthetic `{{…index}}` resolves to the iteration number. |

On a [floating window button](../../explanation/floating-window-buttons.md) the `deal`, `organization` and `person` sources have nothing to read and `system` carries only `company_id` and `user_id`, because that button's views get no Pipedrive record.

In addition, the Data Picker's **Functions** tab produces placeholders that run a built-in function (for example the current date) or a system text value — these are inserted the same way but carry their own logic instead of looking up a plain field.

## Inside an Input

Inside a Data Picker input, inserted placeholders look like small badges rather than raw `{{…}}` text. Backspace removes a badge as a whole, and you can type plain text freely before, between, and after them. The raw named-field syntax (see [Basic Syntax](#basic-syntax)) is what the slate field stores behind the scenes — you only see it if you export the view's data or look at it in the database.

## Placeholders Inside Tables

A Table block points its **Target Array** at an array. The table then renders one row per item in that array. Placeholders you put inside the table's columns resolve against the **current row's item** — not against the full resource. For example, if the array contains objects with a `name` field, you write `{{…name}}` in the column and each row shows its own value.

Placeholders that reference anything outside the array (for example `{{deal.title}}`) still resolve against the normal view-wide data. This lets you mix per-row values and view-wide values in the same table.

## When Data Is Missing

Placeholders never crash a view — they degrade quietly.

| Situation | What the placeholder becomes |
|---|---|
| The source (deal, person, custom, …) is not available | empty string |
| The field does not exist in the source | empty string |
| The field is present but its value is `null` | empty string |
| The field is an array (outside table context) | JSON text of the array |

So a missing field never shows `undefined` or an error — it just leaves a gap.

## Confidential Variables

Interface variables can be marked as confidential. A confidential variable never has its value exposed in the browser: the placeholder stays in its `{{…}}` form until the value is actually needed on the server side, where the substitution happens just before the value is used. This lets you reference things like API keys inside a URL or a header without them ever reaching the viewer's browser.

---

---
url: /reference/data-binding/view-data-source.md
---
# View Data Source

> **Type:** Reference | **Audience:** Interface builder user and the backend developer your view talks to

When a view's URL is configured under **View settings → Configure URL** and **URL Active** is on, the rendered view loads custom data from your endpoint. This page lists exactly what your endpoint receives and is allowed to return.

## Request

Interface Builder calls your endpoint **server-side** through its own backend, not directly from the user's browser. The request always goes out as the OneClick app, signed with three reserved system headers.

### Method

| Method | Body sent? | Use when |
|---|---|---|
| **GET** *(default)* | No | The endpoint expects context as URL query parameters only. |
| **POST** | Yes | The endpoint expects a JSON body with view context. |

Configure under **HTTP Method** in the **URL Configuration** dialog.

### URL

The URL you write in the **End-point URL** field is processed before the request goes out:

1. **Placeholder substitution.** Any `{{deal.title}}`, `{{person.name}}`, `{{user.id}}`, `{{variable.api_key}}`, or `{{searchparams.tier}}` token is replaced with its resolved value. If the URL contains Pipedrive field placeholders, the builder waits for the Pipedrive fetch to finish first; otherwise it processes the URL immediately.
2. **Query parameters appended.** Any **Query parameters** rows you added in the dialog, plus every search parameter from the user's current view URL, are appended as `?key=value` pairs.
3. **Whitespace warning.** If the resolved URL still contains `%20` in the path (typically because a placeholder resolved to an empty value), the builder shows a `URL contains whitespace in path` toast and still sends the request.

### Headers

Every request carries:

| Header | Source | Notes |
|---|---|---|
| `x-oc-user-id` | The Pipedrive user who opened the view | Always set, cannot be overridden. |
| `x-oc-company-id` | The Pipedrive company | Always set, cannot be overridden. |
| `x-oc-event-id` | A short unique ID for this view-open event | Always set, cannot be overridden. Use it to correlate logs. |
| OneClick-level headers | The OneClick button's own **Headers** toggle (Pipedrive's Edit a Button page) | Sent on every request when the toggle is on. |
| Per-call headers | The dialog's **Manage Headers** rows on this view | Values accept `{{variable.*}}` placeholders only. |

Per-call header keys cannot collide with the three reserved keys above (`x-oc-user-id`, `x-oc-company-id`, `x-oc-event-id`) — those are dropped before the request goes out. Other `x-oc-*` keys are not reserved and pass through. See [OneClick-Level Headers](../../explanation/architecture.md#oneclick-level-headers) for the merge order.

### POST body

```json
{
  "data": {
    "view_name": "Account Summary"
  },
  "meta": {
    "button_id": "btn-uuid",
    "company_id": 6789,
    "event_id": "aBcDeF",
    "interface_view_id": "view-shortid",
    "resource": "deal",
    "resource_id": 1234,
    "user_id": 12345
  }
}
```

* `data.view_name` — the view's name. Useful when one endpoint serves several views and needs to switch on which view is asking.
* `meta` — the same context block used by form submissions, so a single endpoint can read both flows the same way.

### POST body from a floating window button

A [floating window button](../../explanation/floating-window-buttons.md) has no Pipedrive record, so `resource` and `resource_id` are sent as `null`. Both keys stay in place, which keeps the body shape identical on both kinds of button:

```json
{
  "data": {
    "view_name": "Account Summary"
  },
  "meta": {
    "button_id": "btn-uuid",
    "company_id": 6789,
    "event_id": "aBcDeF",
    "interface_view_id": "view-shortid",
    "resource": null,
    "resource_id": null,
    "user_id": 12345
  }
}
```

A missing record is `null` — never `0`, never `""`.

### POST body with **Omit oneclick metadata** on

The body collapses to an empty object:

```json
{}
```

Use this only when the endpoint rejects unknown fields — e.g. Pipedrive API v2.

### GET request

No request body. Instead, the same context that POST sends in the body is split between the URL and the headers:

| Source | Goes to | Format |
|---|---|---|
| `data.<key>` | URL query string | `?data_<key>=<value>` |
| `meta.<key>` | Request headers | `x-oc-meta-<key>: <value>` (kebab-cased) |
| User / company / event IDs | Request headers | `x-oc-user-id`, `x-oc-company-id`, `x-oc-event-id` |

Example URL after substitution:

```
https://api.example.com/dashboard?data_view_name=Account%20Summary
```

Example headers — every `meta` key becomes its own header, so all seven are there:

```
x-oc-user-id: 12345
x-oc-company-id: 6789
x-oc-event-id: aBcDeF
x-oc-meta-button-id: btn-uuid
x-oc-meta-company-id: 6789
x-oc-meta-event-id: aBcDeF
x-oc-meta-interface-view-id: view-shortid
x-oc-meta-resource: deal
x-oc-meta-resource-id: 1234
x-oc-meta-user-id: 12345
```

### GET headers from a floating window button

Headers cannot carry `null`, and the string `null` would be a lie. So on a [floating window button](../../explanation/floating-window-buttons.md) the two record headers are **not sent at all** — five `x-oc-meta-*` headers arrive instead of seven:

```
x-oc-user-id: 12345
x-oc-company-id: 6789
x-oc-event-id: aBcDeF
x-oc-meta-button-id: btn-uuid
x-oc-meta-company-id: 6789
x-oc-meta-event-id: aBcDeF
x-oc-meta-interface-view-id: view-shortid
x-oc-meta-user-id: 12345
```

Read the absence of the header as "there is no record". Nothing is sent as `0` or an empty header value.

With **Omit oneclick metadata** on, the `data_*` query params and the `x-oc-meta-*` headers are skipped — only the three reserved system headers remain.

## Response

The endpoint's response is parsed as JSON and stored under the active event ID. The view's runtime polls for it and renders once the parsed object is available.

### Plain data (typical case)

Return any JSON object. Every top-level field becomes a `{{custom.<field>}}` placeholder in the Data Picker's **Custom** tab.

```json
{
  "invoice_count": 3,
  "balance_due": 4250.5,
  "next_invoice": { "id": "INV-123", "due_date": "2026-06-01" }
}
```

The Data Picker exposes `{{custom.invoice_count}}`, `{{custom.balance_due}}`, `{{custom.next_invoice.id}}`, and so on.

### Error message

Return an `oneclick_data.error_message` envelope and the view shows a full-page message view instead of rendering blocks:

```json
{
  "oneclick_data": {
    "error_message": {
      "title": "Account not found",
      "message": "We couldn't find that account. <a href=\"/accounts\">Choose another</a>."
    }
  }
}
```

The string form `"error_message": "Something went wrong"` works too. For a note that is not an error, send the same object as `message_view`. See [HTTP Response Format → Error response](http-response-format.md#error-response) for list messages, the optional `variant`, `message_view`, and the `hideRetry` and `hideBack` flags.

### Redirect

Send the user to a different view of the same interface:

```json
{
  "oneclick_data": {
    "redirect_view": {
      "id": "target-view-id",
      "params": { "deal_id": "1234" }
    }
  }
}
```

The view shows a "Redirecting…" toast and navigates to the target. If `id` does not exist, it falls back to a full-page message view with `View with ID … was not found`.

See [HTTP Response Format](http-response-format.md) for the full schema.

## Timeout and status handling

| Condition | What the user sees |
|---|---|
| Endpoint returns a parsed JSON object inside ~20 s | View renders with the data, `{{custom.*}}` placeholders resolved. |
| Endpoint returns HTTP status `400` or higher | Toast: `Data loading failed (status N)` plus whatever response body landed (rendered against the partial data). |
| Endpoint takes longer than ~20 s | Toast: `Request timed out. No custom data received.` View renders without the custom data. |
| Endpoint throws a network error | Full-page message view with the underlying error message. |

The 20-second budget is a polling cap on the builder side, not a server-side fetch timeout. The actual server-side request to your endpoint runs as long as your endpoint takes; the polling layer just stops listening for a response after ~20 seconds.

## Where this runs

The fetch is **only** triggered when the view runs in live rendering (what real Pipedrive users see) or in the builder's **Test** mode. **Preview** mode does not call the data source URL — it renders against the saved **Sample data** instead. See [External Data Flow](../../explanation/external-data-flow.md) for the load order, the parallel fetches, and the Test-mode overrides.

---

---
url: /reference/layout/areas.md
---
# Areas

> **Type:** Reference | **Audience:** Interface builder user

An **Area** groups consecutive rows on the canvas so they share visibility rules and, optionally, a loop. Areas appear as coloured overlays in the builder -- the colour is a builder aid only and is never visible to end users.

See [Using Areas](../../how-to/layout/areas.md) for a step-by-step guide.

## Area Settings

Open **Area Settings** by clicking an area's badge on the canvas. The panel has the following sections.

### Basics

| Setting | Description |
|---|---|
| **Name** | A name for the area, shown on the badge above it. |
| **Rows** | The rows the area covers. Edit by toggling row numbers in the visual row selector at the top of the panel, or by clicking the **Add Row N (above/below)** buttons that appear for adjacent unowned rows. Only the area's edge rows can be removed -- areas must stay contiguous. |
| **Color** | The area's colour on the canvas. Pick **Blue** (default), **Green**, **Purple**, **Orange**, **Red**, **Teal**, **Pink**, or **Gray**. Colour is a builder-only aid. |

### Conditional Visibility

Toggle **Enable conditional visibility** to show or hide the whole area based on data.

| Setting | Description |
|---|---|
| **Condition** | A Data Picker expression. The area is hidden when this resolves to empty or `"false"`. |
| **Hide (keep space)** | The rows disappear but their vertical space stays reserved. |
| **Remove** *(Recommended)* | The rows are removed entirely; the layout closes up. |

### Loop

Toggle **Enable loop** to repeat the area's rows either per item in an array, or a fixed number of times.

| Setting | Description |
|---|---|
| **Loop mode** | Pick **Array** (repeat once per item in an array) or **Count** (repeat a fixed number of times). |
| **Target array** | Shown in Array mode. Pick an array from your data via the Data Picker. |
| **Loop count** | Shown in Count mode. Enter a number or bind it via the Data Picker. |

In **Array** mode, Data Picker tags inside the looped rows resolve against the current iteration's item. In **Count** mode they stay bound to the view's normal data.

A **loop index** (starting from 1) is exposed inside the loop through the **loopItem** tab in the Data Picker -- use it to show a sequence number or detect the first/last iteration. The loopItem tab only appears when the cursor is inside a looping area.

**Cap:** a single area loops at most **1000 times**. Iterations beyond that are dropped and a warning is logged in the browser console.

**Forms inside a loop:** looped form inputs submit under suffixed names (`name`, `name_loop_1`, `name_loop_2`, …) and the submission payload additionally carries an `oc_loop` array with one object per iteration. See [Form Submission Types](../data-binding/form-submission-types.md#forms-inside-a-looping-area) for the exact shapes.

### Delete Area

The **Delete Area** button at the bottom of the panel removes the area but leaves the rows in place on the canvas.

## Rules

* Areas cannot overlap. If you try to extend an area into rows that already belong to another area, the change is rejected.
* Rows inside an area stay reorderable -- moving them within the area is fine; dragging them out detaches them from the area.

---

---
url: /reference/styles/block-styles.md
---
# Block Styles

> **Type:** Reference | **Audience:** Interface builder user

Every block has a **Style** sub-tab in Block Settings (next to Configuration and Visibility) that controls how the block looks -- background, text, borders, corners. This page lists every control on that sub-tab.

> The Badge and Alert blocks use variant-based styling (see their reference pages); their Style sub-tab shows an info card explaining that custom block styles do not apply.

## Background and Text

| Setting | Description |
|---|---|
| **Background Color** | Picked through a colour swatch, with a separate **Transparent** checkbox to clear it. Default: transparent. |
| **Font Size (px)** | Text size in pixels. Default: 14 px (Title blocks default to 22 px). When a global Font Size is active, the field is disabled and a **Use custom style** switch appears next to it -- toggle it on to override the global value with a per-block size. |
| **Font Color** | Picked through a colour swatch, with a separate **Transparent** checkbox. Default: black. The same **Use custom style** switch appears here when a global Font Color is active. |
| **Font Options** | A toggle group with **Bold**, **Italic**, and **Underline**. |

The Image, Avatar, and Divider blocks omit the font-related controls (no text to style). The Image block also omits Background Color.

## Borders

The border section has up to four sides for normal blocks: **Top**, **Right**, **Bottom**, **Left**. Each side has its own **Top border / Right border / Bottom border / Left border** switch. Turning a side on reveals:

| Setting | Description |
|---|---|
| **Width (px)** | Border thickness in pixels. New blocks default to `1`. |
| **Style** | Line style: **Solid**, **Dashed**, or **Dotted**. |
| **Color** | Border colour swatch. |

### All borders

| Setting | Description |
|---|---|
| **All borders** | Master switch above the four side switches. When on, the four per-side cards are replaced by a single Width / Style / Color card whose values apply to every side. Per-side configuration is preserved while All borders is on, so flipping it back off restores the previous side values. Hidden for Table blocks (which keep their six-toggle UI). |

### Border Radius

| Setting | Description |
|---|---|
| **Border Radius (px)** | Corner radius in pixels. Higher values round the corners more; large values produce circular shapes (useful for Avatar and Image). |

## Padding

Block padding sits between the block's content and its outer edge -- visible once a border is drawn. Each side has its own pixel input.

| Setting | Description |
|---|---|
| **Top (Px) / Right (Px) / Bottom (Px) / Left (Px)** | Per-side padding in pixels. Default `0`. |
| **All padding** | Master switch. When on, the four per-side inputs are replaced by a single **Padding (px)** input that drives every side. Per-side values are preserved while All padding is on, so flipping it back off restores them. |

### Table-specific borders

The Table block adds two extra border switches inside the Borders section:

* **Row border** -- lines between rows.
* **Cell border** -- lines between cells.

Each uses the same Width / Style / Color controls as a side border.

### Table cell padding

Tables also expose a **Global Cell Padding** switch under Borders. When on, it reveals **Top / Right / Bottom / Left** pixel inputs that apply to every cell unless overridden by a column-level padding setting.

## Button-specific settings

Button blocks show two extra controls in the Style sub-tab:

* **Button Size** -- **Small**, **Default**, or **Large**.
* **Button Variant** -- **Default**, **Destructive**, **Outline**, **Secondary**, **Ghost**, **Link**, or **Custom**. The other Style controls (font options, font size, font colour, background, borders) only apply when the variant is **Custom**; otherwise the variant decides the look. See the [Button block reference](../block-types/button.md) for what each variant looks like.

## Defaults

A freshly dropped block starts with:

* Background: transparent
* Font Size: 14 px (Title: 22 px)
* Font Color: black
* Bold / Italic / Underline: off
* No borders enabled (each side defaults to 1 px Solid black when toggled on)
* Border Radius: 0
* Padding: 0 px on every side

The Divider block is the exception -- it starts with a light gray background colour so the line is visible.

## Conditional Visibility

Conditional Visibility lives on its own **Visibility** sub-tab in Block Settings, not under Style. See [Conditional Visibility](../../how-to/visibility/conditional-visibility.md) for how it works.

---

---
url: /reference/styles/global-styles.md
---
# Global Styles

> **Type:** Reference | **Audience:** Interface builder user

Global Styles are view-wide defaults for font size, font color, row spacing, and column spacing. They save you from setting the same values on every block.

Open them from **View settings > Global Styles**. The button on the View settings tab shows a status badge -- "Off", "On (no values set)", or "On (X/4 set)" depending on how many of the four fields are filled in.

## Settings

The dialog has a master switch at the top:

| Setting | Description |
|---|---|
| **Enable Global Styles** | Master toggle. When off, none of the global values are applied -- every block falls back to its own settings. |

Below the switch, four fields set the view-wide defaults. Leave any of them empty (placeholder: *Not set*) to skip that default.

| Setting | Description |
|---|---|
| **Font Size (px)** | Default font size in pixels for every block in the view. |
| **Font Color** | Default font color (as a hex code or via the colour picker) for every block in the view. |
| **Row Gap (px)** | Vertical space in pixels between rows. |
| **Column Gap (px)** | Horizontal space in pixels between columns inside a row. |

## Overriding Global Styles Per Block

When Global Styles are on and a value is set, individual blocks and rows can opt out:

* Inside a block's **Style** sub-tab, a **Use custom style** switch appears next to **Font Size (px)** when a global Font Size is active. Toggle it on to keep the block's own font size; the local input becomes editable. The same switch appears next to **Font Color** when a global Font Color is active.
* Inside a row's **Row Settings**, **Exclude from global row gap** appears when Row Gap is set globally; **Exclude from global column gap** appears when Column Gap is set globally. Each one detaches that specific row from the matching global value.

These switches only show up when the matching global value is actually set, so you do not see clutter when you are not using global styles.

## How the Defaults Apply

When **Enable Global Styles** is on and a global value is set:

1. **Font Size** cascades to every block unless the block has **Use custom style** on next to its Font Size input.
2. **Font Color** cascades to every block unless the block has **Use custom style** on next to its Font Color input.
3. **Row Gap** is applied between every pair of rows unless a row has **Exclude from global row gap** on.
4. **Column Gap** is applied between columns in every row unless the row has **Exclude from global column gap** on.

## Reusing Styles Across Views

Two action buttons live at the bottom of the dialog when your interface has more than one view:

| Action | Description |
|---|---|
| **Apply to all interfaces** | Copies the current global styles to every other view in this interface, overwriting their existing global styles. Disabled until **Enable Global Styles** is on. |
| **Load from main interface** | Replaces the current view's global styles with the main view's. Only shown when you are not on the main view. |

Use these to keep typography and spacing consistent when an interface has many views.

---

---
url: /reference/ui/builder.md
---
# Builder View

> **Type:** Reference | **Audience:** Interface builder user

The builder is where you build a view. You add rows on the canvas, drop blocks into them, and configure whatever is selected from the sidebar on the right. This page names every area of the builder and every menu you can open from it.

## Main Areas

| Area | Where it sits | What it does |
|---|---|---|
| **Canvas** | Centre / left | The working surface where you arrange rows and drop blocks into columns. |
| **Sidebar** | Right | Shows the settings of whatever you have selected. See [Sidebar](./sidebar.md). |
| **Top Bar** | Top of the page | View name on the left, action buttons (Preview / Test / Sample data) on the right, and the saving indicator. |

## Canvas

The canvas is the main editing surface. Rows are stacked vertically; inside each row are one or more columns; each column holds at most one block.

### Adding things

* **Add a new row** -- hover the gap between two rows (or the area above the first row); a small `+` button appears. Click it to open the **Add row** dialog and pick a layout (Full width, Two columns, Three columns, Sidebar left, Sidebar right, or Form).
* **Add a block** -- click an empty column to open the **Add block** dialog and pick a block type (Title, Paragraph, Button, Input, Table, etc.).
* **Add a column** -- open a row's "..." menu and choose **Add column**, or use **Add column left / right** from a column-indicator's "..." menu.

### Rearranging

* **Reorder rows** -- grab a row and drag it up or down on the canvas.
* **Move a block to a different column** -- drag the block onto another column. The block leaves the original column empty.

## Sidebar

A panel on the right that always shows **View settings** plus a context-specific tab whenever you have something selected (Block Settings, Row Settings, Column Settings, Form Settings, or Area Settings). See [Sidebar](./sidebar.md) for an overview and [Settings Panel](./settings-panel.md) for the contents of each tab.

## Block Menu

Every block has a "..." button that opens its block menu.

| Action | What it does |
|---|---|
| **Settings** | Opens the block's settings in the sidebar. |
| **Copy block left** | Adds a copy of the block in a new column to the left. |
| **Copy block right** | Adds a copy of the block in a new column to the right. |
| **Copy to new row** | Adds a copy of the block in a brand-new full-width row below. |
| **Delete block** | Removes the block (asks you to confirm first). |

## Row Dropdown

Every row has a "..." menu.

| Action | What it does |
|---|---|
| **Settings** | Opens the row's settings in the sidebar. |
| **Copy row** | Duplicates the row inside the current view. |
| **Copy to another view** | Copies the row into a different view in this interface. |
| **Add column** | Adds a new column to the row. |
| **Delete** | Removes the row (asks you to confirm first). |
| **Copy** *(form rows only)* | On Form Start / Form End, copies the whole form (start, end, and every row inside). |
| **Delete with content** *(form rows only)* | On Form Start / Form End, deletes the form and every row inside it. |

## Column Indicator

A bar shown above each column inside a row. It shows:

* A column label such as **Col 1**, **Col 2**, or just **Column** when the row has only one column.
* A width badge with the current column width, like **1/2**, **1/3**, **Full**, or **25%**.
* A "..." menu with **Add column left**, **Add column right**, and **Delete column**.

Clicking the column label opens **Column Settings** in the sidebar.

## Add Row Dialog

Opens when you click the `+` between rows. Lets you pick the layout for the new row:

* **Full width** -- single full-width column
* **Two columns** -- 50% / 50%
* **Three columns** -- 33% / 33% / 33%
* **Sidebar left** -- 25% / 75%
* **Sidebar right** -- 75% / 25%
* **Form** -- adds a matching **Form Start** + **Form End** marker pair (hidden when you are already inside a form)

## Add Block Dialog

Opens when you click an empty column. Lists every block type you can drop into that column. **Input** blocks are disabled when the surrounding row is not inside a form.

## Top Bar

The bar above the canvas. Contains:

* **View name** on the left, and a back arrow that returns to the Interface Views list.
* **Preview** -- switches to the Preview viewer running against the currently selected Pipedrive resource -- or, on a [floating window button](../../explanation/floating-window-buttons.md), against no record at all, because there is none to select. Your view's external data source URL is **not** called in Preview; instead, the saved **Sample data** (if any) is used as the Custom data the view would normally fetch.
* **Test** -- switches to the Test viewer where the view's API call actually fires so you can debug responses.
* **Sample data** -- opens a dialog where you can paste JSON. The same payload feeds the Data Picker's **Custom** tab and is what Preview renders against, so you can iterate on layout and bindings without hitting an external API.
* **Saving indicator** -- a small spinner plus the word **Saving...** that appears while your latest edit is being saved.

---

---
url: /reference/ui/row-layouts.md
---
# Rows, Columns, and Layouts

> **Type:** Reference | **Audience:** Interface builder user

A view is built by stacking rows. Each row has one or more columns, and every column can hold one block. This page lists all the layout choices the builder offers and every setting you can adjust on a row or column.

## Adding a Row

Hover the gap between two rows (or above the first row) to reveal a small `+` button. Click it to open the **Add row** dialog and pick the layout for the new row.

| Layout | Columns | Column widths |
|---|---|---|
| **Full width** | 1 | 100% |
| **Two columns** | 2 | 50% / 50% |
| **Three columns** | 3 | 33% / 33% / 33% |
| **Sidebar left** | 2 | 25% / 75% |
| **Sidebar right** | 2 | 75% / 25% |
| **Form** | — | Adds a Form Start + Form End marker pair (hidden when you are already inside a form) |

Each option in the dialog shows a small visual preview of its column widths.

## Reordering and Removing Rows

* **Reorder** — grab a row and drag it up or down on the canvas. The row's position updates immediately.
* **Delete** — open the row's "..." menu and choose **Delete**.

## Row Settings

Open a row's "..." menu (the vertical dots button on the right of the row) and choose **Settings** to open the **Row Settings** panel.

### Padding

Four numeric fields set the padding around the row's content (values in pixels):

* **Padding Top**
* **Padding Bottom**
* **Padding Left**
* **Padding Right**

### Gap overrides

If the view has a global **Row Gap** or **Column Gap** applied, two toggles appear so you can exclude this specific row from the global value:

* **Exclude from global row gap** — only appears when a global Row Gap is set on the view.
* **Exclude from global column gap** — only appears when a global Column Gap is set on the view.

Turn them on when you want the row to sit flush against its neighbours (or its columns to sit flush against each other) despite the global spacing.

### Conditional Visibility

The **Conditional Visibility** section lets you show or hide the row based on data.

1. Turn on the **Enable conditional visibility** switch.
2. In the **Condition** field, enter a Data Picker expression. The row is hidden when the expression resolves to an empty value or `"false"`.
3. Pick what happens when the condition hides the row:
   * **Hide (keep space)** — the row disappears but its vertical space stays reserved.
   * **Remove** *(Recommended)* — the row is removed entirely (the layout closes up).

## Column Settings

Every column in a row has a small column indicator bar above it showing the column label (for example "Col 1") and a width badge ("Full", "1/2", "25%", etc.). Click the column label to open the **Column Settings** panel.

### Padding

* **Padding Top**
* **Padding Bottom**
* **Padding Left**
* **Padding Right**

All four are pixel values, same as on rows.

### Width

The **Width** control lets you pick how wide this column is. The options are:

* **Auto** — the column sizes itself based on the layout (equal share with other auto columns in the row).
* **%** — a percentage of the row's width (for example 25%).
* **px** — a fixed width in pixels (for example 200px).

### Alignment

Two dropdowns place the column's content horizontally and vertically inside the column:

* **Horizontal Align** — Left, Center, or Right.
* **Vertical Align** — Top, Middle, or Bottom.

If the row has multiple columns, an **Apply style to all columns** action copies this column's padding, width, and alignment onto the others.

## Form Rows

Picking **Form** in the **Add row** dialog creates two special marker rows on the canvas:

* **Form Start** — shown at the top of the form, with a coloured accent on the left edge and the form name displayed inline in blue.
* **Form End** — shown at the bottom of the form with the same accent.

Every regular row placed between them belongs to that form. Clicking either marker opens the **Form Settings** tab in the sidebar. See [Settings Panel reference](./settings-panel.md) for what Form Settings contains.

## The Whole View

From top to bottom, a view is:

* A vertical stack of rows.
* Rows may be grouped into **Areas** that share a visibility rule — see [Areas](../layout/areas.md).
* Each row contains one or more columns; each column contains at most one block.
* Two rows act as form boundaries (Form Start / Form End) when you add a form.

Everything above is configurable through the builder UI — no file or JSON editing needed.

---

---
url: /reference/ui/settings-panel.md
---
# Settings Panel

> **Type:** Reference | **Audience:** Interface builder user

The settings panel is the sidebar on the right side of the builder. Its contents change based on what you have selected on the canvas -- a block, a row, a column, a form boundary, or an area badge. This page lists every tab the sidebar can show and every setting inside.

## Tabs

The panel always shows **View settings** as one tab. A second tab appears when you click something on the canvas:

| Second tab shown | When it appears |
|---|---|
| **Block Settings** | A block is selected. |
| **Row Settings** | You clicked a row's column-header on the canvas, or picked **Settings** from the row's "..." menu. |
| **Column Settings** | You clicked a column-indicator label (the small "Col 1", "Col 2", "Full", etc. label above each column). |
| **Form Settings** | You selected a Form Start or Form End row. |
| **Area Settings** | You clicked an area's coloured **badge** (the floating chip with the area name above the area's first row). |

## View settings

Open any time by clicking the **View settings** tab. Contains view-wide configuration.

### View URL

Configure an API endpoint that the view calls when it opens. The response is available inside the view via the Data Picker's **Custom** tab.

Click **Configure URL** to open the URL Configuration dialog and fill in:

| Field | Description |
|---|---|
| **End-point URL** | The endpoint URL. Supports the Data Picker for dynamic values. |
| **HTTP Method** | **POST** or **GET** (default: GET). |
| **URL Active** | Toggle the call on or off. When off, no fetch runs on view load. |
| **Omit oneclick metadata** | When on, Interface Builder skips adding `event_id`, `resource_id`, and other OC-specific fields to the request body. Useful for APIs that reject unknown fields. |
| **Query Parameters** | Key/value pairs appended to the URL. |
| **Manage Headers** | Opens a sub-section to add custom HTTP headers. Header keys may only contain letters, numbers, and hyphens, and must not start with `x-oc-`. |

The End-point URL, its query parameters, and its header values all take the Data Picker, including its [Context tab](../data-binding/data-picker.md#context-tab) — the four System context values that scope a call to this company, this user, and this record, and a View reference to any other view of the same button. On a [floating window button](../../explanation/floating-window-buttons.md) that call cannot be scoped to a record: `resource_id` and `resource` are not offered.

### Global Styles

Click **Global Styles** to open a dialog for view-wide style defaults (background, text, spacing, row gap, column gap). See [Global Styles](../styles/global-styles.md) for the full list.

### View ID

Read-only display of the view's identifier. Useful when another view needs to navigate here.

## Block Settings

Shown when you select a block on the canvas. The Block Settings tab has its own three sub-tabs:

* **Configuration** -- block-specific settings (Button Type, Variant inputs, Data Picker bindings, etc.). The exact fields depend on the block type -- each block has its own reference page under **Block Types**.
* **Style** -- the block's visual style (background, text, borders, size). For the Button block this is also where Button Variant and Button Size live.
* **Visibility** -- conditional rules to show or hide this block based on data.

## Column Settings

Shown when you click a column-indicator label above a column.

| Setting | Description |
|---|---|
| **Padding Top** | Top padding, in pixels. |
| **Padding Bottom** | Bottom padding, in pixels. |
| **Padding Left** | Left padding, in pixels. |
| **Padding Right** | Right padding, in pixels. |
| **Width** | Pick **Auto**, **%** (a percentage of the row's width), or **px** (a fixed pixel value). |
| **Horizontal Align** | Left, Center, or Right. |
| **Vertical Align** | Top, Middle, or Bottom. |

When the row has multiple columns, an **Apply style to all columns** button copies this column's settings onto the others.

## Row Settings

Shown when you click a row's column-header on the canvas, or pick **Settings** from the row's "..." menu.

| Setting | Description |
|---|---|
| **Padding Top / Bottom / Left / Right** | Row padding, in pixels. |
| **Exclude from global row gap** | Only appears when a global Row Gap is set. Excludes this row from the global gap. |
| **Exclude from global column gap** | Only appears when a global Column Gap is set. Excludes this row's columns from the global gap. |

### Conditional Visibility

| Setting | Description |
|---|---|
| **Enable conditional visibility** (switch) | Turns visibility rules on or off for this row. |
| **Condition** | A Data Picker expression. The row is hidden when this resolves to empty or `"false"`. |
| **Hide (keep space)** | The row disappears but keeps its vertical space. |
| **Remove** *(Recommended)* | The row is removed entirely. |

## Form Settings

Shown when you select a **Form Start** or **Form End** row on the canvas.

| Setting | Description |
|---|---|
| **Form Identifier** | A unique name for the form. Submit and Reset buttons use this to target the form. |
| **Padding Top / Bottom / Left / Right** | Inner padding around the rendered form, in pixels. |

## Area Settings

Shown when you click an area's **badge**. Areas group consecutive rows so they share a visibility rule -- and, optionally, a loop.

| Setting | Description |
|---|---|
| **Name** | Display name for the area, shown on the badge. |
| **Rows** | The rows the area covers. Edit by toggling row numbers in the visual row selector at the top of the panel, or by clicking the **Add Row N (above/below)** buttons that appear for adjacent unowned rows. |
| **Color** | Blue, green, purple, orange, red, teal, pink, or gray -- how the area is highlighted in the builder. Builder-only aid. |

**Conditional Visibility** -- the same Condition and Hide / Remove options as on rows.

**Loop** -- repeat the area's rows per item in an array, or a fixed number of times. See [Areas](../layout/areas.md) for details.

**Delete Area** -- removes the area and keeps its rows in place.

---

---
url: /reference/ui/sidebar.md
---
# Sidebar

> **Type:** Reference | **Audience:** Interface builder user

The sidebar is the panel on the right side of the builder. It is always visible while you edit a view. Its contents change based on what you currently have selected on the canvas -- it is where every setting lives.

## What the Sidebar Shows

The sidebar always has a **View settings** tab. A second tab joins it when you click something on the canvas -- together they appear side by side at the top of the sidebar.

| Second tab | Appears when |
|---|---|
| **Block Settings** | A block is selected. Has its own sub-tabs: **Configuration**, **Style**, **Visibility**. |
| **Column Settings** | A column-indicator label (the small "Col 1", "Col 2", "Full", etc. label above each column) is clicked. |
| **Row Settings** | A row's column-header on the canvas is clicked, or **Settings** is picked from the row's "..." menu. |
| **Form Settings** | A Form Start or Form End row is selected. |
| **Area Settings** | An area's coloured **badge** (the floating chip with the area name above the area's first row) is clicked. |

For the full list of fields each tab exposes, see the [Settings Panel reference](./settings-panel.md).

---

---
url: /explanation/what-is-interface-builder.md
---
# What is Interface Builder?

> **Type:** Explanation | **Audience:** All users | **Goal:** Conceptual overview of the application

## Interface Builder as Part of OneClick

OneClick is a Pipedrive marketplace app for automation and customization. Interface Builder is a module within OneClick that lets you create custom views -- visual pages that appear inside Pipedrive when a user clicks a OneClick button.

These views are not standalone websites. They are embedded directly in Pipedrive's UI, tied to the deal, person, or organization the user is looking at.

## Why Custom Views in Pipedrive?

Pipedrive offers limited native customization for its UI. Interface Builder fills that gap by letting you create:

* **Custom forms** that collect data and send it to your API or update Pipedrive fields.
* **Dashboards** with charts, tables, and data displays.
* **Data views** showing deal details, customer profiles, or organization info.
* **Multi-step workflows** where buttons navigate between views.

No coding is required. You build everything in a drag-and-drop editor.

## Use Cases

* **Invoicing**: a "Create invoice" form on the deal view that posts to your billing endpoint, paired with a list of all open invoices on the organisation view — both reachable without leaving Pipedrive.
* **CRM process visualization**: deal overviews, customer profiles, account plans.
* **Data collection**: forms that update deal fields, create persons, or post to external APIs.
* **Reporting**: charts and tables pulling data from Pipedrive or external sources.
* **Guided workflows**: multi-view sequences where each step collects or displays different information.

## Do You Need a Backend?

Not always. A view that just renders Pipedrive data — deal overviews, customer profiles, simple dashboards using fields and variables — needs **nothing else**. Interface Builder fetches the Pipedrive context automatically and resolves placeholders at render time.

You will likely need a backend when the view does any of the following:

* **Submits a form** somewhere other than Pipedrive (Form Submit Button → Submit URL).
* **Has a URL button** that POSTs to an external endpoint or returns a toast or redirect from your own logic.
* **Loads external data** via the view's API endpoint (View settings → Configure URL) — Pipedrive can give you the deal, but anything else (invoices, support tickets, weather, internal databases) has to come from somewhere.

The backend can be:

* **Code you write** — any language, any framework. Expose HTTP endpoints that accept JSON and return the response shapes documented under [HTTP Response Format](../reference/data-binding/http-response-format.md).
* **A no-code automation platform** like [Make](https://www.make.com), [Zapier](https://zapier.com), or [n8n](https://n8n.io). These let you build the endpoint visually and chain steps (look up a record, transform it, send an email, return a JSON response). For most form posts, URL-button calls, and view data fetches, this is the fastest path — no servers to operate, no deployment pipeline.

## Core Concepts

* **Interface** -- A collection of views attached to a OneClick button. When a user clicks the button, the interface opens on the **main view**.
* **View** -- A single page within an interface. An interface can have multiple views linked together via navigation buttons.
* **Row** -- A horizontal layout container. Each row has one or more columns (full width, two columns, three columns, sidebar layouts, or a Form). Rows are the basic structural unit.
* **Block** -- A UI component placed inside a row column. Available block types: **Button**, **Title**, **Paragraph**, **Image**, **Divider**, **Table**, **HTML**, **Input**, **Navbar**, **Avatar**, **Hover Card**, **Chart**, **Alert**, and **Badge** (14 in total).
* **Area** -- A named group of consecutive rows. Areas let you apply a single visibility condition to a whole section, **and** repeat the section once per item in an array (looping).
* **Form** -- A group of rows bounded by **Form Start** and **Form End** marker rows on the canvas, with at least one Input block and at least one **Form Submit Button** that sends the collected data. Forms can also include Form Reset buttons.

## User Roles

* **Builder** -- The person who creates and configures interfaces using the drag-and-drop editor. This is typically an admin or operations team member.
* **End user** -- The person who interacts with the finished interface inside Pipedrive. They see the rendered view, fill in forms, click buttons, and view data.

## Available Data

When an interface opens from a OneClick button, it automatically has access to contextual data:

* **Deal data** -- title, value, currency, owner, products, custom fields.
* **Person data** -- name, email, phone, organization, custom fields.
* **Organization data** -- name, address, custom fields.
* **User data** -- information about the currently logged-in Pipedrive user.
* **Variables** -- key/value pairs you configure per interface.
* **Search params** -- URL parameters passed between views (for example from form submissions or button navigation).
* **External data** -- data fetched from an API endpoint you configure for the view via **View settings > Configure URL** (see [External Data Source](../how-to/data/external-data-source.md)). The response fields appear in the Data Picker's **Custom** tab.

## Saving and Validation

Interface Builder saves automatically. There is no publish step -- whatever you have saved in the builder is what end users see the next time they open the interface. Before each save the builder runs a structural validation pass and blocks save until any issues are resolved (for example a form without a submit button, or an Input outside a form). See [Saving](../how-to/views/publishing.md) for the full set of rules.

---

---
url: /explanation/architecture.md
---
# How Interface Builder Works

> **Type:** Explanation | **Audience:** Interface builder user | **Goal:** Understand how the system connects to Pipedrive and what data is available

## Interface Builder in the OneClick Ecosystem

OneClick is a Pipedrive marketplace app. Interface Builder is a module within it that provides a visual editor for creating custom views.

The flow works like this:

1. You install OneClick in Pipedrive.
2. From OneClick's Settings → **Buttons** tab, you create a new **Interface button** and attach an interface to it.
3. When a Pipedrive user clicks that button on a deal, person, or organization page, the interface opens in place.
4. The view renders with live data from the resource the user opened it from.

## Where the Builder Lives

Interface Builder is reached from OneClick's settings, on the **Buttons** tab. From there, **Create new → Interface button** creates a new Interface button. Editing any existing Interface button opens its configuration page, where the **Open interface builder** button launches the visual editor for that interface. The same page also exposes the interface canvas size (default 1100 × 890), the button text shown to end users, an optional description, and a button accent colour.

## How Views Connect to Pipedrive Resources

When a Pipedrive user opens an Interface button from a record (deal, person, or organization), Pipedrive passes the resource type and record ID to the view as URL parameters, alongside a button ID and an event ID. The OneClick button itself is configured for a specific resource type when you create it, so a button placed on the deal page always opens its interface bound to a deal record.

This is what makes the views contextual. A view opened from Deal #42 displays Deal #42's title, value, owner, and custom fields automatically — you do not have to fetch the record yourself.

The one exception is a [floating window button](./floating-window-buttons.md), which floats over Pipedrive instead of sitting on a record page and therefore passes its views no resource type and no record ID.

## What Data is Available

Inside the builder, you reference data through the [Data Picker](../reference/data-binding/data-picker.md). The available sources are:

* **Deal data**: title, value, currency, owner, products, and every custom field defined in your Pipedrive.
* **Person data**: name, email, phone, associated organization, and custom fields.
* **Organization data**: name, address, and custom fields.
* **User data**: information about the currently logged-in Pipedrive user.
* **Variables**: per-interface key/value pairs, useful for configuration values.
* **Search params**: URL parameters carried between views — typically form data or button parameters from a previous view.
* **External data (Source Data)**: data fetched from an API endpoint you configure for the view (URL, HTTP method, headers, query parameters, and an optional response path). See the [External Data Source guide](../how-to/data/external-data-source.md).
* **Loop item**: when a row sits inside a [looping area](../how-to/layout/areas.md#looping-an-area), the current iteration's data is also available via the picker.

## Builder, Preview, Test, and Rendered Views

Interface Builder has three view modes inside the editor, plus the live rendered view that end users see:

* **Builder** — the drag-and-drop editor where you construct the interface. Data Picker placeholders (like `{{deal.title}}`) appear as their badge representation, not resolved values.
* **Preview** — same canvas, but the view is rendered against the active sample resource so placeholders resolve to live values. Pipedrive fields (`{{deal.title}}`, …) resolve against the active deal, person, or organization, while `{{custom.*}}` resolves against your saved **Sample data** — Preview never calls the view's external data source URL. This is the fastest way to verify layout and data display without leaving the builder.
* **Test** — a more complete simulation that runs the view as a real render, including the Pipedrive request flow. Use Test to exercise interactions that require a real round-trip (form submissions, navigation between views).
* **Rendered view** — what end users actually see when they click the OneClick button inside Pipedrive. This is the same code path Test exercises, just opened from a real Pipedrive context.

## OneClick-Level Headers

Every HTTP request an interface makes — the View URL fetch, a form submission, a URL button's POST — is built from headers at two layers:

1. **OneClick button headers**, configured outside the builder on the OneClick **Edit a Button** page (sidebar → **Headers**, with a master toggle that turns the whole set on or off). These are stored encrypted on the button itself.
2. **Per-call headers**, configured inside the builder on the specific request (View URL → Manage Headers, the submit button's Submit URL → Manage Headers, the URL button's Headers section).

When the toggle on the OneClick button is on, every outgoing request automatically carries the OneClick-level headers in addition to any headers you set per call. This lets you configure a single API token (or signing header, or tenant header) once on the button and have every request the interface makes inherit it.

The reserved `x-oc-user-id`, `x-oc-company-id`, and `x-oc-event-id` keys are always set by the system and cannot be overridden from either layer. The builder also rejects per-call header keys that start with `x-oc-` so the two systems do not collide.

If you only need a header on one specific call, set it per call. If you need it everywhere, set it on the OneClick button.

> See [Securing Your Endpoint](./securing-your-endpoint.md) for the threat model and the recommended way to verify that requests really come from your interface.

## Saving

Changes are auto-saved as you build. There is no publish step and no draft mode — every save immediately becomes the live version users see when they open the OneClick button.

::: warning Every save is immediately live
Preview and Test modes inside the builder render against the same saved data, so they do **not** insulate end users from in-progress edits — they only let you load real records inside the builder. For risk-free experimentation, copy the OneClick button in Pipedrive and edit the copy's interface; switch users over to the new button when the changes are ready.
:::

Before each save, the builder validates the view — for example, every form must have a matching Form Start and Form End pair, at least one input inside the form, and at least one submit button pointing at it. If validation fails, warnings appear on the canvas with quick actions to fix them, and the save is blocked until the errors are resolved. A broken view therefore never reaches end users.

## View Layout Structure

A view is composed of rows stacked vertically. When you add a row, you pick one of these layouts:

* **Full width** (100%) — one column.
* **Two columns** (50/50) — equal split.
* **Three columns** (33/33/33) — equal thirds.
* **Sidebar left** (25/75) — narrow left, wide right.
* **Sidebar right** (75/25) — wide left, narrow right.
* **Form** — a special layout that creates a Form Start / Form End pair for collecting input.

Each column in a row holds one block. Rows can be grouped into [Areas](../how-to/layout/areas.md) for batch visibility control and looping. Padding, alignment, and gap settings are configurable at the row, column, and view-wide level.

---

---
url: /explanation/button-transfer.md
---
# Button Transfer

> **Type:** Explanation | **Audience:** OneClick admins | **Goal:** Understand how interface data behaves when a button is transferred between organizations

A button transfer copies a OneClick button — including all its interfaces, views, and interface variables — from one organization to another. The target admin must first issue a transfer-enabled API key; the source admin then uses it from the button's **Transfer** tab. The original button stays untouched in the source organization.

For security, **confidential interface variables and request headers are stripped in transit**. The target admin has to re-enter those secrets before the copied button works.

Full configuration steps, validation rules, audit logs, and rate limits live in the OneClick admin guide: [Button transfer →](https://help.theoneclick.io/books/2-configuration-guide/page/button-transfer).

---

---
url: /explanation/external-data-flow.md
---
# External Data Flow

> **Type:** Explanation | **Audience:** Interface builder user with backend curiosity | **Goal:** Understand how a view loads data from your endpoint, why some modes skip the fetch, and how Pipedrive data and your custom data are sequenced

## Three modes, three behaviours

Where the view is opened decides whether the endpoint is called at all:

| Mode | Custom URL triggered? | Custom data source comes from |
|---|---|---|
| **Live rendering** (what real Pipedrive users see) | Yes | The endpoint, called in real time. |
| **Test mode** (Test button in the builder) | Yes | The endpoint, called every time you click **Load Data** (or on view open if Autoload is on). The URL can be temporarily overridden in Test settings without saving. |
| **Preview mode** (Preview button in the builder) | **No** | The saved **Sample data** in the interface. |

Test and live rendering share the same loading flow. Preview is intentionally separate so you can iterate on layout against a frozen JSON without spamming the endpoint.

## What happens on view open (Test / live rendering)

When the view opens, two work streams run in **parallel** so total wait time is the slower of the two, not their sum.

```mermaid
sequenceDiagram
    actor User
    participant Browser
    participant Backend as Interface Builder server
    participant Pipedrive
    participant Endpoint as Your endpoint

    User->>Browser: Open view
    Note over Browser: Test mode + Autoload off<br/>waits for "Load Data" click

    par Pipedrive context
        Browser->>Backend: Request deal / person / org / user
        Backend->>Pipedrive: Fetch fields and sample data
        Pipedrive-->>Backend: Resource data
        Backend-->>Browser: Pipedrive context
    and Custom data
        Browser->>Backend: Start custom fetch
        Note over Browser,Backend: If URL has {{deal.…}},<br/>wait for Pipedrive data first
        Backend->>Endpoint: POST or GET (data, meta, headers)
        Endpoint-->>Backend: JSON response
        Note over Backend: Stored under event ID<br/>for ~1 hour
        loop up to ~20 s, every 1 s
            Browser->>Backend: Poll for response
            Backend-->>Browser: Empty (still waiting)
        end
        Backend-->>Browser: Custom data ready
    end

    Note over Browser: Merge Pipedrive + custom +<br/>variables + search params
    Browser-->>User: Rendered view
```

### Why parallel

If the URL is purely static — `https://api.example.com/dashboard` — the custom data fetch starts immediately and runs alongside the Pipedrive fetch. Total wait is the slower of the two.

If the URL contains a Pipedrive placeholder — `https://api.example.com/orgs/{{organization.id}}/dashboard` — the custom fetch can't start until the Pipedrive fetch has resolved the placeholder. The custom flow parks itself until Pipedrive is ready, then proceeds.

### Why polling instead of a direct fetch

The browser doesn't call your endpoint. The Interface Builder server does — that's how the OneClick metadata and headers stay server-side. The flow:

1. Browser asks the Interface Builder server to call the endpoint.
2. The server calls your URL with the configured method, headers, and body.
3. Response body is written to a temporary store keyed by the event ID.
4. Browser polls the store every 1 second until the response is ready — or until ~20 seconds have passed.

The 20-second cap is a UI budget, not a server timeout. If your endpoint takes 60 seconds, the server still waits and writes the response — but the user has already seen the timeout toast and the view has rendered without custom data.

### How the URL and headers are processed

Before the request goes out, the URL string passes through the full Data Picker substitution (client-side), with sources `deal`, `organization`, `person`, `user` (from the Pipedrive fetch), `variables`, `searchparams` (the browser's current URL), `system` (the four [Context tab](../reference/data-binding/data-picker.md#context-tab) values), and `view` (a [View reference](../reference/data-binding/data-picker.md#view-references), which resolves to the id of another view of the same button). After substitution, the search parameters from the browser URL are appended to the request URL so navigation context survives.

On a [floating window button](./floating-window-buttons.md) the `deal`, `organization` and `person` sources have nothing to substitute and `system` carries only `company_id` and `user_id`, because that button's views get no Pipedrive record.

Header values go through the same client-side substitution, so a header can carry any Data Picker source the URL can. The already-substituted headers are what reach the server. The server then fills in what is left, which is `{{variable.*}}` and nothing else: a confidential variable never leaves the server in the first place, so it stays a placeholder until that point. Any other placeholder still unresolved when the server sees it becomes an empty string. The same is true of URL button POSTs and form submissions.

A `view` source is the one that does not resolve the same everywhere. The builder, the Preview and the Test view hold the button's view list, so a reference to a view that has since been deleted resolves to an empty string and the broken link is visible in a test run. The rendered view loads only itself, so it cannot tell a live reference from a stale one and resolves both to the stored id — a working link resolving to nothing would be the worse failure.

The builder warns with a toast in two cases:

* **Whitespace in path** — when the processed URL contains `%20` in its path. Usually means a placeholder resolved to an empty value.
* **Invalid URL** — when the processed URL fails to parse.

The request is sent either way; the toast is just a hint.

## Test-mode specifics

Test mode shares the loading flow with live rendering but adds these twists:

* **Manual trigger.** When Autoload is off, the view sits idle until you click **Load Data**.
* **URL override.** The Test settings sidebar lets you change the URL without saving the view. The override is applied just before the request goes out, so the URL stored on the view stays untouched.
* **Live updates.** Edit the override URL in the Test sidebar and the next load picks it up.
* **Sample data is Preview-only.** Test mode never renders against Sample data -- it always uses what the live data source actually returns. Test and Preview can therefore disagree in three cases: the View URL toggle is off, the URL is missing or broken, or the endpoint returns a payload whose shape differs from your saved Sample data. Switch to Preview when you want to see how Sample data renders against your current layout.

Live rendering has no manual trigger; loading starts immediately on view open.

## Preview-mode specifics

Preview never calls your endpoint. Instead it:

1. Reads the saved **Sample data** for the view.
2. Fetches Pipedrive context the same way the other modes do.
3. Merges the two into the view and renders.

That means:

* A view with a configured URL but no Sample data shows empty `{{custom.*}}` placeholders in Preview.
* Updating the saved Sample data is the only way to change what Preview renders for `{{custom.*}}`.
* A request to your endpoint never leaves the builder while you're in Preview.

See the [Saving page](../how-to/views/publishing.md) for why Sample data behaves like a frozen production response.

## What ends up in the rendered view

After both fetches finish, the runtime assembles the data layer every block reads:

| Source | Comes from | Placeholders |
|---|---|---|
| **Pipedrive context** | Pipedrive fetch | `{{deal.*}}`, `{{organization.*}}`, `{{person.*}}`, `{{user.*}}` |
| **Custom data** | Endpoint response (live / Test) **or** saved Sample data (Preview) | `{{custom.*}}` |
| **Variables** | Interface variables | `{{variable.*}}` |
| **Search params** | Current browser URL | `{{searchparams.*}}` |

## When something goes wrong

| Outcome | What the user sees |
|---|---|
| Endpoint returned `oneclick_data.error_message` or `oneclick_data.message_view` | Full-page message view with title + body, **Go Back** and **Retry** buttons. The body can be a bullet list, and `variant` sets the colours and icon of the card; see [HTTP Response Format](../reference/data-binding/http-response-format.md). |
| Endpoint returned `oneclick_data.redirect_view` to a valid view | Brief "Redirecting…" toast, then navigation. |
| Endpoint returned `oneclick_data.redirect_view` to a missing view | Full-page message view: `View with ID … was not found`. |
| Endpoint returned non-2xx HTTP status | `Data loading failed (status N)` toast plus whatever body came back. |
| Endpoint took longer than 20 s | `Request timed out. No custom data received.` toast, view renders without custom data. |
| Network error during the fetch itself | Full-page message view with the underlying error message. |

---

---
url: /explanation/floating-window-buttons.md
---
# Floating Window Buttons

> **Type:** Explanation | **Audience:** Interface builder user | **Goal:** Understand what a floating window button is, why its views get no Pipedrive record, and what you can still build with one

## What a floating window button is

A OneClick button sits on one of two places in Pipedrive. Most buttons sit in the **main panel** of a deal, a person or an organization — the user opens a record, and the button belongs to that record. A **floating window** button sits somewhere else: it opens a draggable, resizable window that floats over Pipedrive and stays open while the user navigates around the app. It can be opened from the apps dock, from a phone number, from the call tab, or from another app through the SDK.

A floating window is not a modal and it is not an interface of its own. It is the surface the button lives on, exactly as the main panel is. Pressing the button opens your interface in a modal the same way a panel button does, the views render the same way, and navigation between views works the same way. Everything about building a view is the same except for one thing: the data a Pipedrive record would have given you.

## Why there is no Pipedrive record

A floating window is global. It is reachable from anywhere in Pipedrive and it survives navigation, so it cannot belong to a record — the record the user was looking at when they opened it may already be a different one, or none at all. Pipedrive gives the window only the signed-in user, the company, a token and the button's own id.

For a view this means the record is not merely empty, it never arrives. A panel button's run always names one record: the user opened a deal, a person or an organization, and the button knows which. A floating window button's run names none.

## How the builder tells you

Open the views listing of a floating window button and two things are there that a panel button does not show. Next to the button's name is a grey badge reading `⧉ Floating window` — a permanent mark of which kind of button you are editing. Under the Beta box is a grey row headed **No Pipedrive record**, which spells out the consequence: *this button floats over Pipedrive and opens from anywhere, so its views get no data from a deal, person or organization*.

Both are neutral grey and carry no warning icon. A floating window button is not broken and there is nothing to repair — the row is a fact about the data, not an error.

## What the builder hides

Rather than let you pick a value that would always resolve empty, the builder removes those values from view:

| Where | What is hidden |
|---|---|
| [Data Picker](../reference/data-binding/data-picker.md) tab strip | The **Deal**, **Organization** and **Person** tabs. |
| Data Picker **Context** tab | The System context values `resource_id` and `resource`. |
| **Preview** and **Test** | The Pipedrive resource selector in the toolbar. |

The hidden tabs are gone from the strip, not greyed out, and the picker opens on a tab that is actually there. If a saved view already holds a chip from a hidden tab, the chip still renders under its own name rather than as an unknown reference — hiding a tab never rewrites what you have already built.

In **Test**, the run does not ask Pipedrive for record data at all, because there is no record to ask about. Your external data source is still called exactly as it is for a panel button. In **Preview**, the view renders against the saved Sample data as always.

## What you can still build

Everything that does not depend on the record stays:

* **The view's external data source.** It is called the same way, and every field it returns is available under `{{custom.*}}`. This is the main way a floating window view gets its content.
* **The signed-in user.** The **User** tab resolves from the session, not from a selected record.
* **Search params, variables, functions and loop items** — none of them read a record.
* **`company_id` and `user_id`** on the Context tab, both read from the session token.
* **View references** on the Context tab, which point at the other views of the same button.

In practice a floating window view can do nearly anything a panel view can. It reads its data from your endpoint and from the signed-in user instead of from a Pipedrive record. Forms submit normally, tables render normally, and navigation between the button's views works normally.

## What your endpoint receives

A run without a record carries that fact honestly: the two record values are never faked with `0` or an empty string. How the absence looks on the wire depends on the transport, because JSON can carry `null` and the other two shapes cannot:

| Transport | `resource` and `resource_id` on a floating window run |
|---|---|
| JSON body (`{ data, meta }`) | Both keys are present with the value `null`, so the payload shape stays constant. |
| Multipart form data (`meta_*` parts) | Both parts are missing entirely. |
| GET data source (`x-oc-meta-*` headers) | Both headers are missing entirely. |

The other five metadata values — `button_id`, `company_id`, `event_id`, `interface_view_id` and `user_id` — are sent on every run, floating window or not. A panel button's payload is unchanged in every shape, so an integration that already works keeps working.

Full payloads for both cases are in [Form Submission Types](../reference/data-binding/form-submission-types.md) and [View Data Source](../reference/data-binding/view-data-source.md).

---

---
url: /explanation/form-system.md
---
# Form System

> **Type:** Explanation | **Audience:** Interface builder user | **Goal:** Understand how forms work in Interface Builder

## What is a form?

A form in Interface Builder is a group of input fields whose values are collected together and either sent to a server or handed to another view. You build a form visually on the canvas -- there is no HTML to write.

## Why Form Start and Form End?

Interface Builder uses a row-based layout. Forms are not drag-and-drop containers -- they are defined by two special marker rows shown on the canvas: **Form Start** and **Form End**. Every regular row placed between these two markers belongs to the form.

This design lets you arrange input blocks freely across multiple rows and column layouts while still grouping them into a single form for submission.

Clicking either the **Form Start** or **Form End** row opens the **Form Settings** tab in the right panel. The most important setting there is the **Form Identifier** -- a unique name that connects Submit and Reset buttons to this specific form. The Form Identifier also shows up next to Form Start on the canvas as a small inline label. Form Settings also lets you adjust the form's inner padding (**Padding Top / Bottom / Left / Right**, in pixels).

## How Buttons Connect to a Form

A button becomes a submit button when its **Button Type** is set to **Form Submit Button**. The button settings then show a **Form** dropdown listing every form in the view by its Form Identifier. Pick the form this button should submit.

* A submit button does not need to live inside the form's Form Start / Form End boundaries. It can sit anywhere in the view.
* Multiple submit buttons can point at the same form.
* A **Form Reset Button** works the same way: its own **Form** dropdown selects which form to reset.

## What the Builder Validates

When you save a view, the builder checks these rules and surfaces warnings directly on the canvas if any are broken:

* Every form needs a matching **Form Start** and **Form End** pair.
* A form must contain at least one **input block** between its markers. The warning on the canvas is **Missing input field**.
* A form must have at least one submit button somewhere in the view that targets its Form Identifier. The warning is **Missing submit button**.
* Input blocks must sit **between** Form Start and Form End. An input placed outside any form is a validation error.
* Each input inside a form has a unique internal name. The builder generates these names automatically when you drop a block, so you normally never see this detail unless you manually copy blocks in a way that breaks uniqueness.
* When the submit button's **Form Type** is **Open view with form data**, file-type inputs are not allowed -- that mode passes every value as a URL search parameter and cannot carry file uploads.

Submit and Reset buttons that point to a Form Identifier with no matching form also trigger a validation error.

## Form Type: How Data Is Sent

The submit button's **Form Type** setting decides how form data leaves the browser.

### JSON

Sends a `POST` request to the configured **Submit URL** with the form values in the request body. This is the default choice for most forms without file uploads.

### Multipart/Form-Data

Same as JSON, but explicitly intended for forms that include file uploads. Files are attached as individual parts of the request. Use this whenever any input in the form has **Type = File**.

### Open view with form data

Does not send an HTTP request at all. Instead, the submit button navigates to another view inside the same interface and passes every input value as URL search parameters. Useful for multi-step workflows where one form's answers become the starting data for the next view. File inputs are not supported in this mode.

## After Submission: What Happens Next

For JSON and Multipart/Form-Data, the submit button's **After submission** setting decides what happens once the request is sent.

### Select view

Navigates the user to a specific **View ID** immediately after sending the request. You can pass static parameters to the target view, and optionally turn on an option that forwards every input value as search parameters to that view.

### Wait for response

Waits up to **Timeout (s)** seconds (10--60) for the server to reply, then acts on the response:

* If the response contains a redirect to another view, the user is navigated there.
* If the response contains a message, it is displayed either as a replacement alert where the form was, or as a toast notification -- controlled by **Show message after submission**.
* Turning on **Disable form after submission** blocks the user from re-submitting while the response is being processed.

For **Open view with form data**, there is no server response to wait for -- the after-submission behavior is always a view navigation.

For the exact response payloads the builder understands (redirects, messages, polling), see the [HTTP Response Format reference](../reference/data-binding/http-response-format.md). For the request shape your endpoint receives, see the [Form Submission Types reference](../reference/data-binding/form-submission-types.md).

## How a Submit Reaches Your Endpoint

Validation runs first. Then the request goes out — unless the Form Type is **Open view with form data**, in which case there is no request and the user simply navigates to the target view with the input values attached as search parameters.

```mermaid
sequenceDiagram
    actor User
    participant Browser
    participant Endpoint as Your Submit URL

    User->>Browser: Click submit button
    Browser->>Browser: Validate Required, Pattern, file type and size
    alt Form Type: Open view with form data
        Browser->>Browser: Navigate to target view<br/>with input values as search params
    else JSON or Multipart/Form-Data
        Browser->>Endpoint: POST data + meta<br/>(JSON or multipart parts)
        Endpoint-->>Browser: Response
        alt After submission: Wait for response
            alt redirect_view in response
                Browser->>Browser: Navigate to target view
            else message in response
                Browser-->>User: Toast or replace form with alert
            else 4xx / 5xx
                Browser-->>User: Error toast
            end
        else After submission: Select view
            Browser->>Browser: Navigate to chosen view immediately
        end
    end
```

Validation errors (Required missing, Pattern mismatch, file too large or of the wrong type, "Open view with form data" containing a file input) stop the flow before the request is made. The submit button's **Disable form after submission** option freezes the form between the request and the response so the user cannot trigger a duplicate submit.

## Input Fields

Input blocks live between Form Start and Form End and provide the fields users actually fill in. Every input has at minimum:

* **Label** -- the visible text shown above the field.
* **Type** -- one of Text, Textarea, Email, Number, URL, Date, File, Hidden, Checkbox, Radio, Single Select, Multi Select.

Depending on the type, additional settings appear -- for example **Options Type** for selection inputs, **Allow multiple files** and the file limits for file uploads, or **Min** / **Max** for numbers. Full details are in the [Input Block Reference](../reference/block-types/input.md).

**Allow multiple files** is off by default and appears on the File type only. It does two things at once: it lets one field carry several files, and it decides that field's shape on the wire -- a shape that follows the setting rather than the number of files the user happened to pick, so a receiving integration never has to branch. That is also why turning it on for a field an integration already reads is a breaking change for that integration. The shapes themselves are in [File Fields](../reference/data-binding/form-submission-types.md#file-fields).

**Accepted file types** narrows a File input to the extensions and MIME types the author lists. It is a check in the browser only: the file dialog offers only those types, and a selected file of another type holds back the submit. The server that forwards the submission never reads the list, so a request that skips the browser can carry any type. A Submit URL that must refuse a file type has to check the type itself. The list format and messages are in [File Type Limits](../how-to/forms/form-validation.md#file-type-limits).

### Selection Inputs: Static vs. Dynamic Options

Checkbox, Radio, Single Select, and Multi Select inputs need a list of options. The **Options Type** setting picks between:

* **Static** -- a fixed list of label/value pairs you enter in the builder.
* **Dynamic** -- a template label and value pair that expands at render time from Data Picker data.

---

---
url: /explanation/securing-your-endpoint.md
---
# Securing Your Endpoint

> **Type:** Explanation | **Audience:** Backend developer / integrator | **Goal:** Understand why your endpoint needs authentication and how to verify that requests really come from Interface Builder

When your interface fetches data from a custom endpoint or submits a form to one, you control that endpoint. Interface Builder gives you tools to identify itself in every request — but it is your responsibility to actually verify that identity on the server. This page explains why, and how.

## Why this matters

Your endpoint is on the public internet. Even though [the request is made server-side by the Interface Builder backend, not from the user's browser](./external-data-flow.md), the URL still reaches your server over plain HTTPS. Anyone who learns the URL — through a leaked log, a screenshot, an old Slack message, or a guess — can call it directly.

If your endpoint accepts requests without checking the caller, anyone can:

* Read data your endpoint returns (deal information, customer records, internal status).
* Trigger side effects — create records, send emails, run a Make scenario, charge an API quota.
* Submit forged form data and have it stored as if a real user filled it.
* Flood the endpoint with traffic and run up your bill.

The interface itself does not protect the endpoint. It is just one of many possible callers, and the only thing standing between bad actors and your data is whatever check your endpoint code performs on each request.

## How Interface Builder helps

Interface Builder attaches headers to every outgoing request at two layers — see [OneClick-Level Headers](./architecture.md#oneclick-level-headers) for the full mechanism. The relevant pieces for security are:

* **Reserved system headers.** `x-oc-user-id` and `x-oc-company-id` are set automatically. They tell you *who* in Pipedrive triggered the call — useful as input to authorisation, but not as authentication on their own.
* **OneClick button headers.** Configured once on the OneClick button (Pipedrive → OneClick → Edit Button → **Headers**), encrypted at rest, sent on every request the interface makes. This is the right place for a long-lived shared secret.
* **Per-call headers.** Set on a single View URL, form submission, or URL button. Useful when one specific call needs an extra value.

The system headers tell you the context. The OneClick button headers are how you prove the call is genuinely yours.

> \[!WARNING]
> Do not trust `x-oc-company-id`, `x-oc-user-id`, or any other header on its own. Headers can be set by anyone calling your endpoint directly. They are only meaningful **after** you have authenticated the caller with a shared secret you control.

## Recommended setup: a shared-secret header

The simplest and most robust pattern is a static API token in a header. One token per OneClick button, stored on the button, checked on every request.

### 1. Generate a strong random token

```bash
openssl rand -hex 32
```

This produces a 64-character hex string. Treat it like a password — store it in your secret manager (1Password, Doppler, your platform's env vars).

### 2. Add the token to the OneClick button

In Pipedrive, open OneClick → **Edit Button** → **Headers**. Add a new row:

* Key: `x-api-token` (or whatever name you like, as long as it is not reserved with the `x-oc-` prefix). If your endpoint is a Make webhook, use **`x-make-apikey`** so Make's built-in API-key check picks it up automatically — see step 3 below.
* Value: the token from step 1

Turn the Headers master toggle **on**. The token is encrypted at rest on the button and added to every request the interface sends.

> The per-row **Confidential** toggle visible in the screenshot below is a Pipedrive-side UI option that affects how the value is displayed in the OneClick admin form. It does not change what your endpoint receives — header values are encrypted at rest and decrypted on every outgoing request regardless of this toggle.

### 3. Check the token on your endpoint

Reject anything without a matching token before doing any other work:

**Node.js / Express**

```js
app.post("/my-endpoint", (req, res) => {
  if (req.header("x-api-token") !== process.env.OC_TOKEN) {
    return res.status(401).end();
  }
  // …handle the request
});
```

**Make.com**

Make's Webhook module has built-in API-key authentication — no Filter or Router needed. In the webhook's settings, click **+ Add API key**, give the keychain a name, and paste the token. Make then expects every incoming request to carry the token in the **`x-make-apikey`** header and rejects anything else with a 403 before the scenario runs. Use `x-make-apikey` as the header name on the OneClick button to match.

Multiple API keys can be attached to the same webhook, which lets you rotate without downtime.

**n8n**

Place an **IF** node right after the Webhook trigger. Compare `$headers["x-api-token"]` to a credential. Route the false branch to a node that returns a 401 response.

That is it. With those three steps, no caller without your token can do anything against your endpoint.

## Multiple endpoints? Use per-call headers

Setting the token on the OneClick button works perfectly when every call from the interface lands on the same endpoint (or different paths of the same backend that share a secret). The token is sent automatically and you do not have to think about it.

The moment your interface talks to **more than one** distinct endpoint — for example, one Make scenario for "load deal data", a different scenario for "submit a form", and a third for "trigger an action via URL button" — give each one its own token.

To do this, configure the token **per call** instead of (or in addition to) on the OneClick button:

* **View URL** — open the view's data source dialog and add the header under **Manage Headers**.
* **Form Submit URL** — open the submit button's settings and add the header under **Manage Headers**.
* **URL Button** — open the URL button's settings and add the header under **Headers**.

Per-call headers are sent on top of the OneClick button headers, so you can use both layers together: a shared header on the button (e.g. a tenant identifier sent everywhere), plus a per-call token specific to each endpoint.

### Store each token as an Interface Builder variable

Pasting raw tokens straight into every header field works, but it scatters secrets across many block settings and makes them harder to rotate or audit. Interface Builder has its own **Environment Variables** system that solves this — store each token there once, then reference it from any header.

For each endpoint:

1. Open the **Variables** tab and click **Add Variable → Normal**.
2. Give it a key like `make_deal_token`, paste the token as the value, and turn **Confidential** on. All variable values — confidential or not — are encrypted at rest. The Confidential flag adds two extra protections: the value is masked in the builder UI for everyone, and only the user who created it can edit or delete it.
3. In the per-call header field for that endpoint (View URL → Manage Headers, the form's Submit URL → Manage Headers, or the URL button's Headers), set the value via the Data Picker: `{{variable.make_deal_token}}`.

Header values accept `{{variable.*}}` placeholders only — other Data Picker resources (`deal.*`, `organization.*`, `searchparams.*`, …) are silently dropped. At request time the variable is decrypted and substituted in. Rotating a token becomes a single edit on the Variables page, with no need to touch any block.

See [Managing Interface Variables](../how-to/data/variables.md) for full details.

## Things to avoid

* **Tokens in the URL.** Query parameters end up in server access logs, browser history, referer headers, and proxy logs. Always use a header.
* **Reusing the same token across many buttons.** When you need to rotate one, you have to rotate everywhere. Generate a separate token per button.
* **Sending the token back in the response.** Logs and error trackers can capture response bodies.
* **Trusting `x-oc-*` headers without a shared-secret check first.** Anyone can put `x-oc-company-id: 123` on a request to your URL. The header is only trustworthy once you know the caller is genuinely Interface Builder.

## Further reading

* [External Data Flow](./external-data-flow.md) — how a request travels from the browser through the Interface Builder backend to your endpoint
* [Architecture: OneClick-Level Headers](./architecture.md#oneclick-level-headers) — full description of the header layering system
* [View Data Source reference](../reference/data-binding/view-data-source.md) — complete table of headers and request shapes
* **External:** [Make — Webhooks app documentation](https://apps.make.com/gateway) — covers the built-in API-key authentication used in the Make example above
* **External:** [OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) — broken authentication and broken object-level authorisation are the two failures this page is built to prevent

---

---
url: /explanation/url-button-flow.md
---
# URL Button Flow

> **Type:** Explanation | **Audience:** Interface builder user | **Goal:** Understand what a URL button does at runtime, when it polls for follow-up updates, and how redirects and toasts come back to the user

## What a URL button does

A URL button (Button block with **Button Type = URL**) sends an HTTP request to your endpoint when clicked, then reacts to the response. Unlike a Form Submit Button there is no form payload — the button posts whatever you configured under **Button body data**.

Two things make URL buttons different from a regular `<a href>`:

1. The response can be more than "page navigated" — it can be a toast, a redirect to another view, a message view, or a stream of follow-up messages.
2. With **Wait page transition** turned on, the button keeps polling for follow-up responses your endpoint posts back, until a redirect arrives or the timeout fires.

## What happens when the user clicks

```mermaid
sequenceDiagram
    actor User
    participant Browser
    participant Endpoint as Your URL endpoint

    User->>Browser: Click URL button
    Browser->>Endpoint: POST<br/>(body and headers as configured)
    Endpoint-->>Browser: First response

    alt Response contains redirect_view
        Browser->>Browser: Navigate to target view
    else Wait page transition: on
        loop until redirect_view, new message, or timeout
            Browser->>Browser: Check for new response
            opt New message
                Browser-->>User: Toast
            end
            opt redirect_view appears
                Browser->>Browser: Navigate to target view
            end
        end
    else Wait page transition: off
        opt Response has a message
            Browser-->>User: Toast
        end
    end
```

## The first response

The first response can be anything the [HTTP Response Format reference](../reference/data-binding/http-response-format.md) accepts. The most common shapes:

* `oneclick_data.redirect_view` — send the user straight to another view.
* `oneclick_data.message` — show a single info toast.
* `oneclick_data.error_message` or `oneclick_data.message_view` — show a full-page message view.
* An empty body or 2xx status with no `oneclick_data` — the button is "fire-and-forget".

## Wait page transition

With **Wait page transition** off, the click is one round trip: the request goes out, the first response comes back, the browser reacts, done.

With it on, the button assumes the workflow your endpoint kicked off may want to talk back over time — for example to push progress messages. After the first response the browser keeps checking for new `oneclick_data`, and shows a toast for every new message until a `redirect_view` arrives or the configured timeout passes.

The polling interval scales with the timeout — short timeouts poll more often, long timeouts back off.

## When something goes wrong

| Outcome | What the user sees |
|---|---|
| Endpoint returned a 4xx or 5xx status | Error toast with the response body's message, if any. |
| Endpoint returned `oneclick_data.error_message` | Full-page message view with title and message. The message can be a bullet list, and `variant` sets the colours and icon of the card (see [HTTP Response Format](../reference/data-binding/http-response-format.md)). |
| Wait page transition exceeded the configured timeout | The polling stops and the last toast (if any) stays. The user is not navigated. |
| Network error while calling the endpoint | Error toast with the underlying message. |

## Differences from form submissions

URL buttons and Form Submit Buttons both POST to your endpoint, but differ on:

* **Trigger.** Form submits run on form submission; URL buttons run on a single click without a form context.
* **Body content.** Forms send every input value keyed by name; URL buttons send the **Button body data** as configured.
* **Polling.** Form submits never poll — the first response is the only response. URL buttons can poll if **Wait page transition** is on.
* **Validation.** Form submits run input validation first; URL buttons have nothing to validate.

For the exact request shape, see [Form Submission Types](../reference/data-binding/form-submission-types.md) (forms) and the [Button how-to](../how-to/blocks/button.md) (URL buttons).

---

---
url: /explanation/visibility-system.md
---
# Visibility System

> **Type:** Explanation | **Audience:** Interface builder user | **Goal:** Understand how conditional visibility works

## Three Levels of Visibility

Conditional visibility can be applied at three levels, each controlling a different scope:

### Block-level

Show or hide an individual block within a row. Other blocks in the same row can remain visible. Block visibility is configured in the **Visibility** sub-tab of Block Settings in the sidebar.

### Row-level

Show or hide an entire row, including all its columns and blocks. Row visibility is configured in **Row Settings → Conditional Visibility**.

### Area-level

Show or hide a named group of consecutive rows. You pick which rows the area covers when you create it. When the area is hidden, every row inside it disappears. Area visibility takes the highest priority — if an area is hidden, its rows are hidden regardless of their individual row or block visibility settings. Area visibility is configured in **Area Settings → Conditional Visibility**.

## How Conditions Are Evaluated

A **Condition** is a string that the builder resolves at render time. After Data Picker placeholders are replaced with their live values, the result is treated as **plain text** — there is no expression engine. The visibility check is therefore a simple string comparison:

* An empty string (or only whitespace) means **hidden**. The builder flags this state with an "Always hidden" warning so it doesn't ship by accident — see the [how-to](../how-to/visibility/conditional-visibility.md#empty-condition-warning) for what the indicator looks like.
* The string `"false"` means **hidden**.
* Any other value means **visible**.

When the **Conditional Visibility** toggle is off, the element is always visible — whatever the Condition says.

### Comparisons need functions, not operators

::: warning Operators in conditions are read as plain text
You cannot write `{{deal.value}} > 1000` and expect a comparison — that resolves to the literal string `"4000 > 1000"`, which is non-empty and not `"false"`, so the element would always be visible.
:::

Use Data Picker **functions** for any non-trivial check:

| Goal | Condition |
|---|---|
| Show when a value is set | `{{isNotEmpty(deal.value)}}` |
| Show when value greater than 1000 | `{{gt(deal.value, 1000)}}` |
| Show when stage equals "Negotiation" | `{{equals(deal.stage_name, "Negotiation")}}` |
| Hide when no products on deal | `{{isNotEmpty(deal.products)}}` |
| Show only one of several branches | `{{if(equals(deal.status, "won"), "show", "")}}` |
| Show when a value has any substance | `{{boolean(deal.value)}}` |

These all return either `"true"` / a non-empty string (visible) or `"false"` / `""` (hidden). See the [Functions reference](../reference/data-binding/functions.md) for the full list.

`boolean` and the plain logic functions read an empty list differently. `if`, `and`, `or` and `not` follow JavaScript, where an empty array counts as true, so `{{if(deal.products; "show"; "")}}` shows the element for a deal with no products. `boolean` calls an empty array and an empty object false, so `{{boolean(deal.products)}}` hides it. Use `boolean` whenever the condition asks "is there anything here".

## Hide vs. Remove

When a condition evaluates to hidden, the **When hidden** choice decides what happens to the space the element was taking. The control is labelled **Hide (keep space)** or **Remove** on every level (block, row, area).

### Hide (keep space)

The element becomes invisible but keeps its space in the layout. The row or block still occupies its normal height and width — it is just not rendered visually. Layout never shifts when an element toggles.

### Remove

The element is removed from the layout entirely. For rows and areas, that means no vertical space at all. For **blocks**, Remove has two sub-modes (the radio group beneath **Remove**):

* **Keep original sizes** — the block is gone, but its column stays at its original width as empty space. Other blocks stay in their positions.
* **Redistribute space** *(Recommended)* — the block is gone and its column's width is shared out among the remaining visible blocks in the row. For example, if a 33% column is removed, each of the two remaining 33% columns grows to roughly 50%. Widths are only redistributed among columns that use the same unit: percentages with percentages, pixels with pixels, and auto (`1fr`) with auto.

If every block in a row is hidden with **Remove + Redistribute space**, the whole row collapses out of the layout.

## Priority

When multiple visibility levels apply to the same content, the evaluation order is:

1. **Area visibility** (checked first — highest priority)
2. **Row visibility** (checked second)
3. **Block visibility** (checked last)

If an area is hidden, its rows are hidden regardless of row-level or block-level settings. If a row is hidden, its blocks are hidden regardless of block-level settings.

## Visibility and Looping

Area visibility runs **before** loop expansion. If a [looping area](../how-to/layout/areas.md#looping-an-area) has its visibility condition evaluate to hidden, the loop is skipped entirely — zero iterations are rendered, just as if the target array were empty. When the area is visible, the rows inside it are duplicated once per iteration in the normal way, and per-row or per-block visibility conditions are then evaluated against each iteration's data.

## Use Cases

* **Role-based content**: show admin controls only when `{{user.is_admin}}` is `"true"` — boolean fields resolve to either `"true"` or `"false"`, which the visibility check handles directly.
* **Stage-dependent displays**: branch on a specific stage with `{{equals(deal.stage_id, "5")}}` rather than just checking emptiness.
* **Threshold checks**: hide an area when the deal value is below a number, e.g. `{{lt(deal.value, 1000)}}`.
* **Empty data handling**: hide a chart or table when no data is available, e.g. `{{isNotEmpty(custom.results)}}`.
* **Progressive forms**: show extra fields based on earlier selections (carried via search params or variables) using `{{if(equals(searchparams.tier, "enterprise"), "show", "")}}`.

---

---
url: /reference/data-binding/agent-bindings.md
---
# Binding Reference for Agents

> **Type:** Reference | **Audience:** An agent that edits views through the Interface Builder tools

This page says what a binding means: which data each namespace reads, when a placeholder needs `arrayPath`, what an Area loop's `target` and `count` resolve to, and which compiler functions exist. The tool descriptions do not have room for it.

For how a person picks the same values, see [Placeholder Syntax](placeholder-syntax.md) and [Data Picker](data-picker.md).

## How a Binding Is Written

A field that carries data is a plain string with placeholder tokens in it. Text and tokens mix freely:

```text
Deal: {{key: 'title', name: 'Title', resource: 'deal', variableType:'normal'}} is open
```

* Never write a token yourself. Call `list_bindable_values` to find a `key`, then call `make_placeholder` with the `namespace` and the `key`. Put the token it returns into the string.
* `make_placeholder` derives the display name, and for a variable its id and confidentiality. A token it returns always points at something that exists at that moment.
* `get_block` returns every Data picker field as the same plain string, so you read the form you write.
* Every string of a block is searched for tokens when the view renders, so a token resolves in any field. A missing value resolves to an empty string. `get_block` lists the tokens that no longer point at anything in `brokenBindings`.

## Namespaces

`namespace` is the `resource` of the token. There are ten.

| Namespace | What it reads | `key` is |
|---|---|---|
| `deal` | The Pipedrive deal the view opens on. In the builder, the deal sample. | A path in the deal object, such as `title` or `org_id.name`. A custom field is its hash key. |
| `organization` | The Pipedrive organization the view opens on. In the builder, the organization sample. | A path in the organization object. |
| `person` | The Pipedrive person the view opens on. In the builder, the person sample. | A path in the person object. |
| `user` | The Pipedrive user who opens the view. | A path in the user object. |
| `custom` | The response of the view's data source URL. In the builder, the view's Sample data. | A path in that response. |
| `variable` | A variable of the button. | The variable's `key`. The token stores the variable's id, so renaming the key does not break it. |
| `view` | A View reference: another view of the same button. | The view's id. It resolves to that id. |
| `system` | Where the view runs: `resource_id`, `resource`, `company_id` and `user_id`. | One of those four names. |
| `searchparams` | The URL parameters the view was opened with. | The parameter name. |
| `functions` | A keyword of the Functions tab. See [Keywords](#keywords). | The keyword. |

Notes on the namespaces:

* **The four Pipedrive namespaces.** `deal`, `organization` and `person` are empty on a floating window button, because its views get no Pipedrive record. `list_bindable_values` gives each key a `label`: a custom field's own name where the field has one.
* **Paths go through objects.** A related record's value, such as `org_id.name`, and a custom field under `custom_fields` exist only further down the tree. Give `list_bindable_values` a `prefix` to walk into them.
* **`variable`.** A confidential variable resolves in the browser only as the token itself, never as its value. `list_bindable_values` lists confidential variables too, by key. No value travels, `include_values` included.
* **`view`.** In the builder, the Preview and the Test view, a reference to a deleted view resolves to an empty string. The rendered view cannot tell, and it returns the id.
* **`system`.** On a floating window button, `resource_id` and `resource` are empty and `list_bindable_values` does not offer them. `company_id` and `user_id` come from the session and are always there.
* **`searchparams`.** The builder has no URL parameters, so `list_bindable_values` returns nothing for it. You must be told the name of a parameter to bind it.
* **`functions`.** `list_bindable_values` does not take this namespace. Name the keyword with `make_placeholder` and `variableType`.

## Example Values

`list_bindable_values` lists keys and no values. Pass `include_values: true` and each listed value carries a `value` as well: what the key holds in one real record, cut at 40 characters, an array shown as its item count and an object shown as nothing, exactly as the Data picker draws it beside the key. Ask for it when you have to choose between keys that look alike, not to read a record — a listing can run to hundreds of keys.

Where the values come from:

* `deal`, `organization` and `person` read the **Preview record**, the record the Preview and the Test view run against. Asking for values fetches it; asking for keys alone fetches nothing.
* `custom` reads the view's Sample data, `variable` a variable's own value and `system` the four values a run would actually send. All three are in the browser already.
* The `user` namespace carries no value at all, and the sandbox user behind `owner_id` and `creator_user_id` supplies none anywhere: a value at those keys inside a deal, an organization or a person is shown only where the fetch supplied one.
* A confidential variable carries no value, whoever asks.
* `view` and `searchparams` have no values of their own.

A namespace with no record — one the Preview record does not reach, a record that was not found, a failed fetch, or a button that carries no Pipedrive record at all — lists its keys unchanged and says why once in `valuesUnavailable`. A namespace that does have values names the record in `valuesFrom`. The values are display only: a placeholder carries the key and resolves against whatever record the run carries.

## When `arrayPath` Is Required

A key names the keys of an array's **item**, never an index. `list_bindable_values` walks into an array through its first item, so under `deal_products` it lists `deal_products.name`.

Such a key is not a path in the resource: the resource holds an array at `deal_products`, not an object. The token must therefore say which array it reads the key out of. Give `arrayPath` when a key goes through an array:

| Key | `arrayPath` |
|---|---|
| `title` | *(leave out)* |
| `org_id.name` | *(leave out — `org_id` is an object)* |
| `deal_products.name` | `deal_products` |

`make_placeholder` checks the key through the array's first item. If you leave out `arrayPath` for a key under an array, it refuses with `field_not_found` and names the array to give.

What the token resolves to depends on where the block is:

* **Outside an Area loop and outside a table,** the token resolves to a JSON array of that key's value in every item, such as `["Product A","Product B"]`. Empty values are left out.
* **Inside an Area loop in array mode,** the loop's target array wins over the token's `arrayPath`. A key that starts with the target's key is read out of the current item. See [Area Loops](#area-loops).
* **Inside a Table block's columns,** a key that starts with the table's target key is read out of the current row's item, the same way.

A token whose key does not start with the loop's or the table's target key resolves against the whole resource by its key alone. Its `arrayPath` is ignored there, so a key under another array resolves to an empty string, not to the JSON array it gives outside.

## Area Loops

An Area's `loop` has `enabled`, `mode`, `target` and `count`. Write `target` and `count` as strings with a token in them, the same way as any field. A loop that is not `enabled` does nothing.

### `target` (array mode)

* The loop reads the **first** token of `target`: its namespace and its `key`. The array is the value at that key in that namespace, for example `deal_products` in `deal`.
* If that value is not an array, or the array is empty, the area's rows are removed from the view.
* Otherwise the area's rows repeat once for each item, up to 1000 items. Items beyond that are dropped.
* Inside the rows, a key that starts with the target's key reads the current item. Write the key as `list_bindable_values` gives it, such as `deal_products.name`, with `arrayPath: 'deal_products'`.

### `count` (count mode)

* The loop resolves the tokens of `count` and reads the result as a number. Plain text such as `3` works too.
* If the result is not a number, or it is `0`, the area's rows are removed from the view.
* The number is rounded up (towards positive infinity), then its sign is dropped: `2.5` gives 3 repeats, `-2` gives 2, `-2.5` gives 2.
* The rows repeat up to 1000 times. Repeats beyond that are dropped.
* Compiler functions do not run in `count`. Write a placeholder or a plain number.

### The loop index

* In both modes, each repeat carries its number, starting from 1.
* Make its token with `make_placeholder` and `is_loop_index: true`. The key is `index`.
* The loop index resolves only in a block inside an Area loop. Anywhere else it resolves to nothing and `get_block` reports it broken.

### Other rules

* A loop whose area has conditional visibility on and whose condition resolves to empty or `false` does not repeat.
* Form inputs inside a loop submit under suffixed names (`name`, `name_loop_1`, …). See [Form Submission Types](form-submission-types.md#forms-inside-a-looping-area).

## Compiler Functions

The Data picker's **Functions** tab offers the functions below. A function runs after the tokens in its arguments are substituted. Arguments are separated by `;`, and functions can be nested. The parameters, return values and examples of each function are in [Functions](functions.md).

Write a function into a Data picker field as plain text and the tool stores the form that runs:

```
formatCurrency(fi-FI;EUR;{{key: 'value', name: 'Value', resource: 'deal', variableType:'normal'}})
```

`get_block` reads the field back as the same text, and the field opens in the builder as the chips a person's own insert produces. `list_functions` returns each function's parameter counts, parameters, return type and example as data.

**What counts as a function.** A name from the list below, spelled exactly, followed immediately by `(`, with balanced parentheses. A name that is unknown, wrongly cased or followed by a space stays text, so prose such as `Katso if (…)` is left alone. A `{{…}}` token is read whole, so a `)` or a `;` inside a display name counts for nothing. A `)` inside an argument is not supported — it ends the function, the same limit a person has.

**Where a function runs.** Only in a field that offers a Data picker. The schema `get_block_schema` returns marks each one with `dataPicker: true`. In any other field the text stays text.

**Three Area fields are the exception.** An Area loop reads its `target`, its `count` and its area's visibility condition before the functions of the view are run, so a function written in one of them is stored but never runs there. Write a placeholder or plain text in all three. An area's visibility condition does run its functions for showing and hiding the area — only the loop's own check reads it early. This is the behaviour a person's own insert has.

**What is refused.** A known name with unbalanced parentheses returns `function_unclosed`, and a parameter count outside the function's own bounds returns `function_arity` — for example `formatCurrency expects 3 parameters, got 2`. Both refuse the whole write and name the field, and nothing is written. Parameter types are not checked: a placeholder's value exists only at render.

| Category | Functions |
|---|---|
| Text Processing | `capFirst`, `capitalize`, `contains`, `endsWith`, `first`, `last`, `length`, `lower`, `replace`, `replaceAll`, `slice`, `split`, `startsWith`, `stripHtml`, `trim`, `upper` |
| Mathematics | `add`, `divide`, `multiply`, `round`, `subtract` |
| Logic & Comparison | `and`, `boolean`, `equals`, `gt`, `gte`, `if`, `lt`, `lte`, `not`, `notEquals`, `or`, `switch` |
| Data Validation | `isEmpty`, `isNotEmpty`, `isNumber`, `isWeekend`, `useDefault` |
| Date & Time | `addDays`, `addMonths`, `addYears`, `daysBetween`, `formatDate`, `formatDateTime`, `formatRelative`, `subtractDays`, `subtractMonths`, `subtractYears` |
| Data Manipulation | `formatCurrency`, `formatList`, `get`, `join`, `map`, `sort`, `sortBy`, `unique`, `uniqueBy` |

`boolean` is the one function whose truth test is not JavaScript's: it reads an empty array and an empty object as `false`, while `if`, `and`, `or` and `not` read them as true. Use `boolean` for a visibility condition that asks whether a list has anything in it.

A function's error shows when the view renders, not when you write the field.

### Keywords

The Functions tab also offers keywords. Make their tokens with `make_placeholder`, `variableType` and the keyword as the `key`. The namespace is always `functions`.

| `variableType` | Keyword | Resolves to |
|---|---|---|
| `systemFunc` | `now` | The current time as an ISO 8601 string. It works in a plain string. |
| `systemText` | `whitespace` | A space. |
| `systemText` | `emptystring` | An empty string. |
| `systemText` | `tab` | A tab character. |
| `systemText` | `newLine` | A line break. |

A `systemText` keyword takes effect only in the form a person's edit stores. In a plain string it stays as the token text. Unlike a compiler function, nothing converts it for you.

---

---
url: /how-to/agent/connect-claude-code.md
---
# Connecting Claude Code to Interface Builder

> **Type:** How-to | **Audience:** Builder admin | **Goal:** Let Claude Code read and edit your views through the tools of a browser tab

Interface Builder offers its builder as a set of tools to an agent on your own machine. Claude Code reaches those tools through a small local program, the **relay**. This guide sets up the relay, adds the permission rules, and shows how to check the connection.

You do this setup once per machine. After that, every Standalone tab you open offers its tools to the same relay.

## Before You Start

* **Chrome.** The tools use WebMCP, which Chrome turns on for the Interface Builder address through an origin trial token that the page carries. There is no polyfill: in another browser, or on a deployment without a token, the page offers nothing. The **Agent** popover then says *"This browser does not support the agent tools."*
* **Claude Code** installed, with Node.js available, because the relay runs through `npx`.
* **A Standalone tab.** Inside Pipedrive's iframe the page cannot offer tools. Open the views listing from Pipedrive and click **Open in new tab** in its header. The **Agent** button appears only in that tab.

## 1. Install the Relay

1. In the Standalone tab, click **Agent** in the header.
2. Under **1. Install the relay**, copy the command.
3. Paste the command into a terminal and run it.

The command has this shape. Copy it from the popover rather than from here, because the popover fills in the address of your tab and the relay version that the page was built with:

```text
claude mcp add interface-builder -- npx -y @mcp-b/webmcp-local-relay@<version> --widget-origin <origin>
```

What the command does:

* `claude mcp add interface-builder` adds an MCP server called `interface-builder` to Claude Code. The name is the middle part of every tool name that Claude Code sees, for example `mcp__interface-builder__get_page`.
* `npx -y @mcp-b/webmcp-local-relay@<version>` is how Claude Code starts the relay. The version is pinned: the part of the relay that runs in the page is copied into Interface Builder at the same version, and the two must match.
* `--widget-origin <origin>` is the address of the tab you copied the command from. The relay answers only a page served from that address. The command never uses `*`.

The relay listens only on the loopback address of your machine (`127.0.0.1`). Nothing outside your computer can reach it, and a page on any other address cannot list or call the tools.

## 2. Add the Permission Rules

By default, Claude Code asks you before every call to an MCP tool. The permission rules change that for two groups of tools.

1. In the popover, under **2. Add the permission rules**, copy the snippet.
2. Open your Claude Code `settings.json`. Use `~/.claude/settings.json` for every project, or `.claude/settings.json` in the project where you run Claude Code.
3. Add the entries of `allow` and `ask` to the `permissions` section of the file. If the file already has a `permissions` section, add the entries to its lists. Do not replace the lists.

The snippet has this shape. The popover builds the full list from the tools the page offers:

```json
{
  "permissions": {
    "allow": [
      "mcp__interface-builder__get_page*",
      "mcp__interface-builder__get_block*"
    ],
    "ask": [
      "mcp__interface-builder__delete_view*",
      "mcp__interface-builder__delete_block*"
    ]
  }
}
```

What the rules mean:

| Section | Tools | Effect |
|---|---|---|
| `allow` | Tools that only read | Claude Code calls them without a prompt. |
| `ask` | Tools that delete or overwrite something you cannot easily get back | Claude Code always asks first. |
| *(neither)* | Ordinary writes, such as adding a row or updating a block | Claude Code keeps its own default prompt, where you can choose "don't ask again". |

The `ask` rules are the only protection before a delete. The relay does not pass on the tool's own "consequential" flag, so without the snippet one "don't ask again" on a delete tool approves that tool for good. With an `ask` rule, Claude Code asks every time: a "don't ask again" answer or `bypassPermissions` mode does not remove the prompt.

Every rule ends in `*`. When two tabs offer the same tool, the relay adds a suffix to the name, and the `*` makes the rule match the suffixed name too.

## 3. Check the Connection

The page cannot see your agent, so the popover never says "connected". Check from Claude Code:

1. Start Claude Code, or restart it if it was running when you installed the relay.
2. Run `/mcp`.
3. Find `interface-builder` in the list and open it. Its tools are listed with names such as `get_page`, `open_view` and `add_row`.
4. Ask the agent to call `get_page`. It answers with the page the tab is on: the views listing or the builder.

If the server is in the list but it has no tools:

* Make sure the Standalone tab is open and its **Agent** popover does not say that the browser is not supported.
* Make sure the tab's address is the address in the `--widget-origin` of the command. A command copied from another deployment answers only that deployment. Run `claude mcp remove interface-builder`, then add the server again with the command from this tab.
* Make sure this tab is the one that offers the tools. See [One Tab at a Time](#one-tab-at-a-time).

## One Tab at a Time

Only one Standalone tab offers its tools at a time, so the names of the tools stay the same. The first tab you open takes the tools. Another tab shows *"The tools are offered in another tab."* and a **Use agent here** button. Click the button to move the tools to that tab. The other tab then stops offering them and shows a banner.

When you close the tab that offers the tools, no other open tab takes them by itself. Click **Use agent here** in the tab you want to use, or reload it.

## When the Session Ends

The address of a Standalone tab works as your login. It holds a token that is valid for 24 hours from the moment you clicked **Open in new tab**. Nothing renews it.

* **Do not share the address.** Anyone who holds it acts as you until the token expires.
* **30 minutes before the end**, a banner says *"This session ends in less than 30 minutes"*. Finish your work, or open a new tab from Pipedrive.
* **After 24 hours**, the banner says *"This session ended"*. Nothing that you or the agent change in that tab is saved any more.

To carry on:

1. Open the views listing from Pipedrive again and click **Open in new tab**.
2. If the old tab is still open, close it, or click **Use agent here** in the new tab.

You do not install the relay again or change the permission rules. The new tab carries a new token in its address, but it is served from the same origin, and the relay matches the origin.

## Limits

* A tool call must finish within 60 seconds, which is the relay's own timeout.
* The relay starts with the first Claude Code session that uses it. A second Claude Code session on the same machine shares that relay.

## Related

* [Binding Reference for Agents](../../reference/data-binding/agent-bindings.md) — what a placeholder means, written for the agent

---

---
url: /for-ai.md
---
# For AI

This documentation is available in machine-readable formats for use with Large Language Models. Pick the right one for your tool and context window.

## Quick links

* [`/llms.txt`](/llms.txt) — small index of every page
* [`/llms-full.txt`](/llms-full.txt) — every page concatenated into one file

Both files follow the [llms.txt](https://llmstxt.org/) convention.

## Which one should I use?

### `llms.txt` — the index

A short, structured list of every page in the documentation, with titles and links to the raw markdown of each page.

**Use it when:**

* Your AI tool can fetch URLs on its own (Claude with web access, Cursor, agentic IDEs).
* You want the AI to look up only the pages it needs, not the whole corpus.
* The full corpus would not fit in your context window.

**How it works:** the AI reads the index, decides which pages are relevant to your question, then fetches them one by one from `/your-page.md`.

### `llms-full.txt` — the whole corpus

Every page in the documentation concatenated into a single file (~6,000 lines, around 50–80k tokens depending on the tokenizer).

**Use it when:**

* You want to paste the entire documentation into a chat (ChatGPT, Claude.ai) once and ask many questions against it.
* Your AI tool cannot fetch URLs but has a large context window.
* You want everything available without the AI having to make follow-up requests.

**Trade-off:** large. May exceed smaller context windows. Wastes tokens on pages unrelated to your question.

## Per-page raw markdown

Every documentation page is also available as raw markdown at the same URL with a `.md` suffix. For example:

* HTML page: [`/reference/block-types/button`](/reference/block-types/button)
* Raw markdown: [`/reference/block-types/button.md`](/reference/block-types/button.md)

Useful when you want to drop a single page into an AI conversation without the surrounding HTML.

## Example prompts

**With `llms.txt` and a tool that can browse:**

> Read https://docs.example.com/llms.txt and answer the following question. Fetch any pages you need from the index.
>
> Question: How do I add validation to a form input?

**With `llms-full.txt` pasted into chat:**

> Below is the full Interface Builder documentation. Answer my questions using only this content.
>
> \[paste contents of /llms-full.txt here]
>
> How do I add validation to a form input?

---

---
url: /README.md
---
# Interface Builder v2 - Documentation

Interface Builder v2 is a module within the OneClick application that enables building custom visual interfaces (views) for Pipedrive CRM. These interfaces are bound to specific resources (deals, persons, organizations) and can be opened from buttons within Pipedrive.

## Getting Started

If you're new to Interface Builder, start here:

1. [First Interface](tutorials/01-first-interface.md) - Build your first view step by step
2. [Data Binding Basics](tutorials/02-data-binding-basics.md) - Connect Pipedrive data to your interface
3. [Building a Form](tutorials/03-building-a-form.md) - Create interactive forms
4. [Multi-View App](tutorials/04-multi-view-app.md) - Build apps with multiple views and navigation
5. [Table View](tutorials/05-table-view.md) - Display tabular data

## How-To Guides

### Blocks

* [Button](how-to/blocks/button.md) - Add and configure buttons (URL, action, submit, reset)
* [Table](how-to/blocks/table.md) - Configure tables with columns, sorting, and actions
* [Chart](how-to/blocks/chart.md) - Add charts (bar, line, area, pie)
* [Image](how-to/blocks/image.md) - Add static or dynamic images
* [HTML](how-to/blocks/html.md) - Embed custom HTML content
* [Navbar](how-to/blocks/navbar.md) - Add navigation bars
* [Alert & Badge](how-to/blocks/alert-and-badge.md) - Add alerts and badges
* [Hover Card](how-to/blocks/hover-card.md) - Add hover-triggered cards
* [Avatar](how-to/blocks/avatar.md) - Add avatar/profile images

### Forms

* [Creating a Form](how-to/forms/creating-a-form.md) - Set up form boundaries and structure
* [Input Field Types](how-to/forms/input-field-types.md) - All input types and configuration
* [Form Validation](how-to/forms/form-validation.md) - Required fields, patterns, validation rules
* [Form Submission](how-to/forms/form-submission.md) - Configure submit actions and responses

### Layout

* [Rows & Columns](how-to/layout/rows-and-columns.md) - Manage layout structure
* [Global Styles](how-to/layout/global-styles.md) - Apply consistent styling across views
* [Block Styles](how-to/layout/block-styles.md) - Style individual blocks
* [Areas](how-to/layout/areas.md) - Group rows into named areas

### Data

* [Data Picker](how-to/data/data-picker.md) - Use the Data Picker for dynamic content
* [Variables](how-to/data/variables.md) - Create and manage interface variables
* [External Data Source](how-to/data/external-data-source.md) - Connect to external APIs
* [Search Params](how-to/data/search-params.md) - Use URL parameters in views

### Visibility

* [Conditional Visibility](how-to/visibility/conditional-visibility.md) - Show/hide blocks, rows, and areas

### Views

* [Creating a View](how-to/views/creating-a-view.md) - Add new views to an interface
* [Navigation](how-to/views/navigation.md) - Navigate between views
* [Saving](how-to/views/publishing.md) - How auto-save works and what validation runs before each save

## Reference

### Block Types

* [Button](reference/block-types/button.md) | [Title](reference/block-types/title.md) | [Paragraph](reference/block-types/paragraph.md) | [Image](reference/block-types/image.md) | [Divider](reference/block-types/divider.md)
* [Table](reference/block-types/table.md) | [HTML](reference/block-types/html.md) | [Input](reference/block-types/input.md) | [Navbar](reference/block-types/navbar.md) | [Avatar](reference/block-types/avatar.md)
* [Hover Card](reference/block-types/hover-card.md) | [Chart](reference/block-types/chart.md) | [Alert](reference/block-types/alert.md) | [Badge](reference/block-types/badge.md)

### Data Binding

* [Data Picker](reference/data-binding/data-picker.md) - Complete Data Picker reference
* [Pipedrive Resources](reference/data-binding/pipedrive-resources.md) - Available resource types and fields
* [Placeholder Syntax](reference/data-binding/placeholder-syntax.md) - `{{resource.field}}` syntax reference
* [Functions](reference/data-binding/functions.md) - All 57 functions (text, math, logic, dates, data manipulation)
* [HTTP Response Format](reference/data-binding/http-response-format.md) - oneclick\_data, redirects, errors, polling
* [Form Submission Types](reference/data-binding/form-submission-types.md) - JSON, Multipart/Form-Data, Open view with form data

### Styles

* [Global Styles](reference/styles/global-styles.md) - Global style settings reference
* [Block Styles](reference/styles/block-styles.md) - Per-block style settings reference

### UI Components

* [Builder](reference/ui/builder.md) - Builder view structure
* [Sidebar](reference/ui/sidebar.md) - Block palette and row layouts
* [Settings Panel](reference/ui/settings-panel.md) - Configuration panel tabs
* [Row Layouts](reference/ui/row-layouts.md) - All layout options

## Concepts

* [What is Interface Builder?](explanation/what-is-interface-builder.md) - Overview and concepts
* [How It Works](explanation/architecture.md) - How Interface Builder connects to Pipedrive
* [Form System](explanation/form-system.md) - How forms are structured and validated
* [Visibility System](explanation/visibility-system.md) - How conditional visibility works