> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-blocks.md).

# Create Blocks

Include blocks in your Kizen app to display custom content tiles on dashboards, homepages, chart groups, and record details pages.

{% hint style="success" %}
**Audience:** Developers, solution architects

**Purpose:** Explains how to build blocks as surfaces in Kizen apps
{% endhint %}

## Overview

*Blocks* are tiles of content that sit in dashlet grids on dashboards, homepages, and chart groups (see Figure 1).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F4BcXhsWJtOPQnv5ORBh5%2Fappdev_blocks.png?alt=media&amp;token=0b7e5f9c-a281-443e-b164-bc06cb3044e8" alt=" A block from an app displays a randomly generated funny affirmation on the Dashboard page in Kizen." width="563"><figcaption><p><strong>Figure 1:</strong> A block from an app on the Dashboard page.</p></figcaption></figure></div>

Blocks can also appear on record details pages (see Figure 2).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FCLmI0YTMxuKorvirwpoa%2Fappdev_blocks_recorddetailsaffirmation.png?alt=media&amp;token=34b572a4-986c-4c37-a048-22fa887d98fe" alt="The user has added the same block to a record details page in Kizen." width="563"><figcaption><p><strong>Figure 2:</strong> The same block on a record details page.</p></figcaption></figure></div>

After a user installs your app, they can place your blocks among their existing dashlets and content on these four types of pages.

The content of a block can come from custom HTML, or you can embed the content from a page on the web.

***

## Add a block to your app

Add your block to the `blocks` directory in `src`. Place each block in its own subdirectory with `config.json`, `script.js`, and `styles.css` files as needed, like this:

```
src/
└── blocks/
    ├── affirmation/
    │   ├── config.json
    │   ├── script.js
    │   └── styles.css
    └── welcomeVideo/
        ├── config.json
        └── script.js
```

{% hint style="info" %}
**Note:** Depending on the block, you might not need `styles.css`. See the table below for details.
{% endhint %}

The following table describes these files:

| File          | Type                  | Purpose                                                                                                                | Required? |
| ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------- |
| `config.json` | JSON                  | The configuration file for the block.                                                                                  | Yes       |
| `script.js`   | JavaScript            | The script that runs when the block loads.                                                                             | Yes       |
| `styles.css`  | Cascading Style Sheet | The styles for the content in the block. If the block embeds content from an outside source, you don't need this file. | No        |

Blocks also support event scripts. Place event scripts in the block's `eventScripts` subdirectory. For more information about event scripts, see the [coding reference](https://kizen.github.io/app-engine/04-worker-runtime-api.html).

```
src/
└── blocks/
    └── affirmation/
        ├── config.json
        ├── script.js
        ├── styles.css
        └── eventScripts/
            ├── matchTimeOfDay.js
            └── nextAffirmation.js
```

See below for details on each of these files.

### About `config.json` for blocks

The configuration file for a block sets the properties of the block:

```json
{
  "name": "Affirmation",
  "api_name": "affirmation",
  "min_w": 3,
  "max_w": 5,
  "min_h": 2,
  "max_h": 3,
  "recommended_height": 600,
  "types": ["charts","dashboards","homepages","records"],
  "when": "!{{config.hideAffirmations}}"
}
```

The keys are as follows:

<table data-search="false"><thead><tr><th>Key</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><strong><code>name</code></strong></td><td>The name of the block.</td><td>Yes</td></tr><tr><td><strong><code>api_name</code></strong></td><td>The API name of the block in all lowercase letters. If you don't specify a value for this key, the system automatically generates one based on the name of the block's subdirectory.</td><td>Yes</td></tr><tr><td><strong><code>min_w</code></strong></td><td>The smallest allowable width of the block in grid columns (<code>1</code>–<code>12</code>). This key applies to blocks of the <code>charts</code>, <code>dashboards</code>, and <code>homepages</code> types.</td><td>No</td></tr><tr><td><strong><code>max_w</code></strong></td><td>The largest allowable width of the block in grid columns (<code>1</code>–<code>12</code>). This key applies to blocks of the <code>charts</code>, <code>dashboards</code>, and <code>homepages</code> types.</td><td>No</td></tr><tr><td><strong><code>min_h</code></strong></td><td>The smallest allowable height of the block in grid rows (<code>1</code>–<code>24</code>). This key applies to blocks of the <code>charts</code>, <code>dashboards</code>, and <code>homepages</code> types.</td><td>No</td></tr><tr><td><strong><code>max_h</code></strong></td><td>The largest allowable height of the block in grid rows (<code>1</code>–<code>24</code>). This key applies to blocks of the <code>charts</code>, <code>dashboards</code>, and <code>homepages</code> types.</td><td>No</td></tr><tr><td><strong><code>recommended_height</code></strong></td><td>The default height of the block in pixels (<code>100</code>–<code>800</code>). This key applies to blocks of the <code>records</code> type.</td><td>No</td></tr><tr><td><strong><code>types</code></strong></td><td><p>An array of page types on which the user can add the block:</p><ul><li><code>charts</code>. The user can add the block to the chart group of a record list page.</li><li><code>dashboards</code>. The user can add the block to a dashboard page.</li><li><code>homepages</code>. The user can add the block to a homepage.</li><li><code>records</code>. The user can add the block to a record details page.</li></ul></td><td>Yes</td></tr><tr><td><strong><code>when</code></strong></td><td>A condition that determines when to show the block on the screen. For more information, see the <a href="https://kizen.github.io/app-engine/index.html">coding reference</a>.</td><td>No</td></tr></tbody></table>

{% hint style="info" %}
**Note:** Blocks on pages of the `charts`, `dashboards`, and `homepages` types use the **`min_w`**, **`max_w`**, **`min_h`**, and **`max_h`** keys to set their minimum and maximum size on the dashlet grid. The values of these keys are in columns and rows. The user can't drag the block beyond the minimum or above the maximum width or height.

Blocks on pages of the `records` type have a standard width but a variable height that you set with the **`recommended_height`** key, in pixels. The recommended height becomes the default height of the block, although the user can set their own height value when they add the block to a record details page.

A block that can appear on multiple types of pages uses the applicable size keys according to its page. When the block is in a chart group, for example, it follows the column and row sizes and ignores the recommended height. When the block is on a record details page, it does the opposite.
{% endhint %}

### About `script.js` for blocks

The JavaScript file for a block is the block's main script. Kizen runs the script when the block loads, including when the user refreshes or resizes the browser window or changes the filters on a dashboard page. The script sets the starting state of the block.

The script can use standard JavaScript, most web APIs available to Web Workers, and Kizen's runtime API. Because the script acts as the signed-in user, it can do whatever the user can do in Kizen, with the same permissions, and it knows the user's name and currently active business. For all page types except for homepages, it also knows details about the page on which the block appears, such as the record on a record details page or the values of the filters on a dashboard page. The script can read this information from properties of the **`this.args`** object, although the exact properties depend on the page type. See the following table for details.

| this.args property | Contains                                                      | Page types          |
| ------------------ | ------------------------------------------------------------- | ------------------- |
| **`dateFilter`**   | The dashboard's date range as start and end dates             | `dashboards`        |
| **`entityId`**     | The ID of the specific record                                 | `records`           |
| **`objectId`**     | The ID of the record object                                   | `charts`, `records` |
| **`teamFilter`**   | The values of the dashboard's team filters as set by the user | `dashboards`        |

{% hint style="info" %}
**Note:** For more information on the **`this.args`** object, see the [coding reference](https://kizen.github.io/app-engine/04-worker-runtime-api.html#thisargs).
{% endhint %}

Keep in mind:

* **A block script controls only its own tile.** It can show toasts and modals and navigate to other pages in Kizen, but it can't otherwise change the browser window outside the tile. It can, however, launch the event script of another block from the same app on the same page. See [Run the event script of another block on the page](#run-the-event-script-of-another-block-on-the-page) below for more information.
* **A block script runs only while the page holding the block is open.** Navigating to another page or closing Kizen entirely stops the script. For tasks that need to run on their own, use an agentic workflow code step instead.
* **A block script starts fresh each time the block loads.** To carry values from previous runs, store them in the user’s configuration or as short-term session data. For details, see the [coding reference](https://kizen.github.io/app-engine/glossary.html#session-data).
* **A block script must finish before the user can interact with the block.** Code that runs on a loop or long delay belongs in an event script.

#### Paint content into the block

To paint content into the block, use one of two methods: `this.outputUI()` or `this.outputIframe()`.

For HTML and CSS, use `this.outputUI()`:

```javascript
this.outputUI(`
  <p class="you-are-here">You are here: <strong>Kizen</strong></p>
  <p class="you-are-here__proof">${this.location.host}</p>
`);
```

The method takes a single HTML string as its argument. The CSS comes from the block's `styles.css` file or from inline **`style`** attributes in the HTML. For security, Kizen strips out `<script>` tags, event handlers, and `javascript:` links but leaves SVG, images, and `<iframe>` elements. For more information, see the [coding reference](https://kizen.github.io/app-engine/11-output-ui-iframes-frames.html#thisoutputuimarkup-options).

To embed a live web page, use `this.outputIframe()`:

```javascript
const latitude = 30.27;
const longitude = -97.74;
const zoom = 5;
const layer = 'wind';

const params = new URLSearchParams({
  lat: latitude,
  lon: longitude,
  zoom,
  overlay: layer,
});

this.outputIframe(`https://embed.windy.com/embed2.html?${params}`);
```

{% hint style="info" %}
**Note:** Another way to embed a live web page is to write an `<iframe>` element into your custom HTML with `this.outputUI()`.
{% endhint %}

The page loads from its own server and runs its own code, so it can update itself. The address must start with `https://`, and the site must allow embedding. For more information, see the [coding reference](https://kizen.github.io/app-engine/11-output-ui-iframes-frames.html#thisoutputiframeurl-allow-sandbox-options).

{% hint style="info" %}
**Note:** Kizen loads embedded pages through a frame proxy at `https://plugin-assets.kizen.com`. If you need to update your site to make it embeddable in Kizen, allow the proxy's domain, not just Kizen's. For more information on the frame proxy, see the [coding reference](https://kizen.github.io/app-engine/11-output-ui-iframes-frames.html#the-frame-proxy).
{% endhint %}

#### Run the event script of another block on the page

From the `script.js` file of the current block, you can launch the event script of an entirely different block using the  `this.communicate.runBlockScript()` method:

```javascript
const hour = new Date().getHours();
const timeOfDay = hour < 12 ? 'morning' : hour < 18 ? 'afternoon' : 'evening';
const firstName = this.currentUser.profile.first_name || 'there';

this.outputUI(`
  <p class="greeting">Good ${timeOfDay}, ${firstName}!</p>
`);

this.communicate.runBlockScript('affirmation', 'matchTimeOfDay', { timeOfDay });
```

Keep in mind:

* **The target block must belong to the same app as the current block.** You can't target blocks that belong to different apps.
* **The target block must be on the same page as the current block.** If it isn't, nothing happens.
* **If the target block appears more than once on the page, every instance runs the same event script.** You can't target them individually.

For more information on `this.communicate.runBlockScript()`, see the [coding reference](https://kizen.github.io/app-engine/09-blocks.html#cross-block-communication-runblockscript.).

### About `styles.css` for blocks

The style sheet for a block provides the style definitions for the classes in the block's custom HTML:

```css
.you-are-here {
  margin: 0;
  padding: 16px 20px 4px;
  font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
  font-size: 20px;
  color: #333333;
}

.you-are-here strong {
  font-size: 24px;
  color: #cc0000;
}

.you-are-here__proof {
  margin: 0;
  padding: 0 20px 16px;
  font-family: ui-monospace, Menlo, monospace;
  font-size: 13px;
  color: #666666;
}
```

You don't need a style sheet if your block uses `this.outputIframe()` to embed a live web page.

{% hint style="info" %}
**Note:** Custom HTML content can inherit styling from Kizen before your style sheet applies. Therefore, for best results, explicitly set style properties for your classes instead of relying on default settings.
{% endhint %}

***

## Add a block to a page

When a user installs your app, your app's blocks don't automatically appear in Kizen. The user must manually add them to the appropriate pages. Each block's **`types`** configuration key determines which types of pages it can appear on:

| Type         | Appears on           |
| ------------ | -------------------- |
| `charts`     | Record list pages    |
| `dashboards` | Dashboard pages      |
| `homepages`  | Homepages            |
| `records`    | Record details pages |

{% hint style="info" %}
**Note:** A block can belong to multiple page types.
{% endhint %}

After you add blocks from an app to pages in Kizen, uninstalling the app hides the blocks on record details pages but shows placeholder tiles on all other page types. Reinstalling the app returns the blocks to their placeholders.

For step-by-step instructions on adding blocks to each page type, keep reading.

### Add a `charts` block to a record list page

To add a `charts` block to a record list page:

{% stepper %}
{% step %}

### Go to the list of custom objects

From the global navigation, select **Data > Custom Objects**.
{% endstep %}

{% step %}

### Go to the record list of a custom object&#x20;

Select the name of a custom object in the list.
{% endstep %}

{% step %}

### If necessary, switch to Chart view

Select the icon for Chart view at the top of the page (see Figure 3).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FWIPvDNik1xPtsdH77kRr%2Fappdev_blocks_chartview.png?alt=media&amp;token=bf635e6a-c952-45e5-94f3-62fd0a933869" alt="The user selects the Chart view icon at the top of the page to switch to Chart view." width="563"><figcaption><p><strong>Figure 3:</strong> The icon for Chart view.</p></figcaption></figure></div>
{% endstep %}

{% step %}

### Add the block

To add the block:

1. Select **Add Chart**. The Add New Block modal appears (see Figure 4).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FQdOfAtmGych0sFKsSYEg%2Fappdev_addnewblock.png?alt=media&amp;token=a1f768c6-1a04-4403-a231-72270fb435c4" alt="The user opens the Add New Block modal." width="563"><figcaption><p><strong>Figure 4:</strong> The Add New Block modal for the chart group on a record list page.</p></figcaption></figure></div>

2. Under Integrations, select the app with the block that you want to add. The controls on the modal change (see Figure 5).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F1FjsvoQ0DZTDHuxSYykM%2Fappdev_blocks_addnewblock_marcsdevelopmentplugin.png?alt=media&amp;token=066942e6-0f09-4745-ab5a-3c49f4316f57" alt="When the user selects an app from the modal, the modal shows a dropdown menu for choosing a block and a slider for turning on a drop shadow." width="563"><figcaption><p><strong>Figure 5:</strong> The reconfigured Add New Block modal for the chart group on a record list page.</p></figcaption></figure></div>

3. From the dropdown menu, select the block to add.
4. To display a subtle shadow under the block's tile, turn on the drop shadow effect.
5. Select **Add**. The modal closes, and the block appears on the page.
6. Drag the lower right corner of the block to adjust its size.
   {% endstep %}
   {% endstepper %}

### Add a `dashboards` block to a dashboard page

To add a `dashboards` block to a dashboard page:

{% stepper %}
{% step %}

### Go to the Dashboard page

From the global navigation, select **Dashboard**.
{% endstep %}

{% step %}

### If necessary, select a dashboard

Open the menu next to the name of the current dashboard, and select the dashboard on which you want to add the block (see Figure 6).

<figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F1sr7ZUOYJYONykoxwrpt%2Fappdev_dashboardlist.png?alt=media&amp;token=c47e6612-0316-4202-b0b9-b6e65bd3250b" alt="The user opens a menu to select a dashboard." width="563"><figcaption><p><strong>Figure 6:</strong> The dashboard selector.</p></figcaption></figure>
{% endstep %}

{% step %}

### Add the block

To add the block:

1. Select **Add Dashlet**. The Add New Block modal appears (see Figure 7).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FMnZlycEEbsHsAfN7mpn3%2Fappdev_blocks_addnewblock_dashboard.png?alt=media&amp;token=e482d973-2c75-4e19-8d9b-85d5512c7e2f" alt="The user opens the Add New Block modal." width="563"><figcaption><p><strong>Figure 7:</strong> The Add New Block modal for the Dashboard page.</p></figcaption></figure></div>

2. Under Integrations, select the app that has the block that you want to add. The controls on the modal change (see Figure 8).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F1FjsvoQ0DZTDHuxSYykM%2Fappdev_blocks_addnewblock_marcsdevelopmentplugin.png?alt=media&amp;token=066942e6-0f09-4745-ab5a-3c49f4316f57" alt="When the user selects an app from the modal, the modal shows a dropdown menu for choosing a block and a slider for turning on a drop shadow." width="563"><figcaption><p><strong>Figure 8:</strong> The reconfigured Add New Block modal for the Dashboard page.</p></figcaption></figure></div>

3. From the dropdown menu, select the block to add.
4. To display a subtle shadow under the block's tile, turn on the drop shadow effect.
5. Select **Add**. The modal closes, and the block appears on the page.
6. Drag the lower right corner of the block to adjust its size.
   {% endstep %}
   {% endstepper %}

### Add a `homepages` block to a homepage

To add a `homepages` block to a homepage:

{% stepper %}
{% step %}

### Go to the Homepages page

From the global navigation, select **Homepages**.

{% hint style="info" %}
**Note:** If you don't find the Homepages link in the global navigation, add it to your toolbar layout. For instructions, see our [knowledge base](https://kizen748362562368528725.freshdesk.com/support/solutions/articles/154000202819-how-to-view-and-customize-my-toolbar).
{% endhint %}
{% endstep %}

{% step %}

### If necessary, select a homepage

Open the menu next to the name of the current homepage, and select the homepage on which you want to add the block (see Figure 9).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FkND7Af0KK30smoFkv2js%2Fappdev_blocks_homepageselector.png?alt=media&amp;token=756eab49-7b00-411c-9616-71877c3ea3f8" alt="The user opens a menu to select a homepage." width="563"><figcaption><p><strong>Figure 9:</strong> The homepage selector.</p></figcaption></figure></div>
{% endstep %}

{% step %}

### Add the block

To add the block:

1. Select **Add Block**. The Add New Block modal appears (see Figure 10).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FhWD0MCfHfCBzhsinTOhM%2Fappdev_blocks_addnewblock_homepages.png?alt=media&amp;token=c7bf5dc3-2848-4ec0-9ad7-d47c3a3457b8" alt="The user opens the Add New Block modal." width="563"><figcaption><p><strong>Figure 10:</strong> The Add New Block modal for a homepage.</p></figcaption></figure></div>

2. Under Integrations, select the app that has the block that you want to add. The controls on the modal change (see Figure 11).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F1FjsvoQ0DZTDHuxSYykM%2Fappdev_blocks_addnewblock_marcsdevelopmentplugin.png?alt=media&amp;token=066942e6-0f09-4745-ab5a-3c49f4316f57" alt="When the user selects an app from the modal, the modal shows a dropdown menu for choosing a block and a slider for turning on a drop shadow." width="563"><figcaption><p><strong>Figure 11:</strong> The reconfigured Add New Block modal for a homepage.</p></figcaption></figure></div>

3. From the dropdown menu, select the block to add.
4. To display a subtle shadow under the block's tile, turn on the drop shadow effect.
5. Select **Add**. The modal closes, and the block appears on the page.
6. Drag the lower right corner of the block to adjust its size.
   {% endstep %}
   {% endstepper %}

### Add a `records` block to a record details page

To add a `records` block to a record details page:

{% stepper %}
{% step %}

### Go to the list of custom objects

From the global navigation, select **Data > Custom Objects**.
{% endstep %}

{% step %}

### Go to the record list of a custom object&#x20;

Select the name of a custom object in the list.
{% endstep %}

{% step %}

### Open the object settings

Select the Settings icon, and choose **Object Settings** from the menu that appears (see Figure 12). Kizen opens the editing interface for the custom object.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FUbHM1elFMWJSnaW0xwvE%2Fappdev_blocks_settings_objectsettings.png?alt=media&amp;token=a2d6c9a9-0e3f-4d4e-a684-73bb68c9122b" alt="The user selects the Settings icon and chooses Object Settings from its menu." width="563"><figcaption><p><strong>Figure 12:</strong> The Settings icon and menu for the custom object.</p></figcaption></figure></div>
{% endstep %}

{% step %}

### Customize the record layout

To customize the record layout:

1. Go to the Customize Layout step of the custom object editor (see Figure 13).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FR9N367MLGawTK08D657N%2Fappdev_blocks_customizelayout.png?alt=media&amp;token=5203764d-a7d3-498a-a545-03466d4e3b6b" alt="The user switches to the Customize Layout step of the object editor." width="563"><figcaption><p><strong>Figure 13:</strong> The Customize Layout step of the custom object editor.</p></figcaption></figure></div>

2. From the **Choose Layout to Modify** dropdown menu, select the layout on which to add the block.
3. In the work area under Customize Record Layout, choose a column of the record details page into which to add the block, and select its **Add Layout Component** control (see Figure 14).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FSL906Ykk5Dr1nV83C5Td%2Fappdev_blocks_customizerecordlayoutcontrols.png?alt=media&amp;token=2550bd04-0e94-4bed-9abe-87ccd8ab368d" alt="The user selects one of the the Add Layout Component controls in the Customize Record Layout work area." width="563"><figcaption><p><strong>Figure 14:</strong> One of the Add Layout Component controls in the Customize Record Layout work area.</p></figcaption></figure></div>

&#x20; Kizen opens the Add Layout Component modal (see Figure 15).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FLPlOalPALWctjBPvK32b%2Fappdev_blocks_addlayoutcomponet.png?alt=media&amp;token=3ea9f8f3-82c3-483e-a207-084bed34a529" alt="The user opens the Add Layout Component modal." width="563"><figcaption><p><strong>Figure 15:</strong> The Add Layout Component modal.</p></figcaption></figure></div>
{% endstep %}

{% step %}

### Add the block

To add the block:

1. Under Integrations in the modal, select the app that has the block that you want to add. The controls on the modal change (see Figure 16).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2Fy0vOLyy8AWQ4wLupjraE%2Fappdev_block_addlayoutcomponent_marcsdevelopmentplugin.png?alt=media&amp;token=363ca595-6454-4add-b1d7-28282c7065eb" alt="The user selects an app under Integrations, and the controls on the modal change." width="563"><figcaption><p><strong>Figure 16:</strong> The reconfigured Add Layout Component modal.</p></figcaption></figure></div>

2. From the **Choose Block** dropdown menu, select the block to add. Kizen automatically sets its recommended height.
3. Drag the **Block Height** slider to change the height of the block if you prefer.
4. In the **Internal Block Name** field, type a name for the block. This name is how Kizen refers to the block in the Customize Record Layout work area.
5. Select **Save**. The modal closes, and the block appears in the Customize Record Layout work area (see Figure 17).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FxcdLhCb2P6KfigGFPEcX%2Fappdev_blocks_youarehereblock.png?alt=media&amp;token=243d8908-6f14-4cb4-9326-e9c26209500e" alt="The user finds the new block in the Customize Record Layout work area." width="563"><figcaption><p><strong>Figure 17:</strong> The block in the Customize Record Layout work area.</p></figcaption></figure></div>

6. Drag the block elsewhere in the work area to position it where you like among the other pieces of content on the record details page (see Figure 18).

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FowDuP7eiNNlqdFg0wZLj%2Fappdev_blocks_youarehere_moved.png?alt=media&amp;token=ca38fccd-af6b-4f49-a803-9aabeaca04c8" alt="The user moves the block to a different relative position in the Customize Record Layout work area." width="563"><figcaption><p><strong>Figure 18:</strong> The repositioned block in the Customize Record Layout work area.</p></figcaption></figure></div>

{% hint style="info" %}
**Note:** Use the mockup of the layout under Record Preview to help you position the block.
{% endhint %}

7. Select **Save** at the top of the custom object editor.

{% hint style="info" %}
**Note:** After you have placed the block on the record details page, you can edit its height and internal name by going back to the Customize Layout step of the object settings, opening the block's ellipsis menu in the Customize Record Layout work area, and selecting **Edit**. You can also change its position by dragging it elsewhere among the other pieces of content in the work area.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## What's next?

Continue to [Create Data Adornments](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/data-adornments.md) to learn how to create data adornments for your app.

<details>

<summary>Related Topics</summary>

* [Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development.md)
* [Work with Marketplace Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/work-with-marketplace-apps.md)
* [Work with Business Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/work-with-business-apps.md)
* [Develop Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps.md)
* [Work with KiCode](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/work-with-kicode.md)
* [Create App Surfaces](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces.md)
* [Create Toolbar Items](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/toolbar-items.md)
* [Create Floating Frames](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/floating-frames.md)
* [Create Pages](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-pages.md)
* [Create Data Adornments](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/data-adornments.md)

</details>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-blocks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
