> 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-pages.md).

# Create Pages

Include pages in your Kizen app to display full-screen content with optional links in the global navigation.

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

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

## Overview

*Pages* are complete, full-screen web pages that appear within Kizen (see Figure 1). They have unique URLs that work for anyone who installs your app. Depending on how you configure your pages, you can automatically create toolbar items for them that the user can add to their global navigation.

<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%2FnvkJ6lp0NIJg0meQUf0B%2Fappdev_page.png?alt=media&amp;token=5b731d7b-7ca3-4ffb-8ffa-5c2bcb800f98" alt=" A page from an app displays a randomly generated abstract painting in Kizen. The page appears in the global navigation as the Modern Art toolbar item." width="563"><figcaption><p><strong>Figure 1:</strong> A page from an app.</p></figcaption></figure></div>

The content of a page can come from custom HTML, or you can embed the content from a page on the web.&#x20;

***

## Add a page to your app

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

```
src/
└── pages/
    ├── modernArt/
    │   ├── config.json
    │   ├── script.js
    │   └── styles.css
    └── signThatContract/
        ├── callback.js
        ├── config.json
        ├── script.js
        └── styles.css
```

{% hint style="info" %}
**Note:** Depending on the page, you might not need one or more of the files.
{% endhint %}

The following table describes these files:

| File          | Type                  | Purpose                                                                                                                                                                             | Required? |
| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `config.json` | JSON                  | The configuration file for the page.                                                                                                                                                | Yes       |
| `script.js`   | JavaScript            | The script that runs when the page opens.                                                                                                                                           | Yes       |
| `styles.css`  | Cascading Style Sheet | The styles for the content on the page. If the page embeds content from an outside source, you don't need this file.                                                                | No        |
| `callback.js` | JavaScript            | The script that runs when the page receives a cross-document message of the `kizen:plugin_callback` type. If your page doesn't listen for these messages, you don't need this file. | No        |

Pages also support event scripts. Place event scripts in the page'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/
└── pages/
    └── modernArt/
        ├── config.json
        ├── script.js
        ├── styles.css
        └── eventScripts/
            ├── addToGallery.js
            ├── hangIt.js
            └── newPainting.js
```

See below for details on each of these files.

### About `config.json` for pages

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

```json
{
  "api_name": "modern_art_page",
  "name": "Modern Art",
  "is_toolbar_item": true,
  "toolbar_color": "#cc0000",
  "toolbar_icon": "pen-fancy"
}
```

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>api_name</code></strong></td><td>The API name of the page 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 page's subdirectory.</td><td>Yes</td></tr><tr><td><strong><code>name</code></strong></td><td>The name of the page.</td><td>No</td></tr><tr><td><strong><code>is_toolbar_item</code></strong></td><td>Whether the page adds a toolbar item to the global navigation. When this value is <code>true</code>, the <strong><code>name</code></strong> field supplies the label of the page's toolbar item.</td><td>No</td></tr><tr><td><strong><code>toolbar_color</code></strong></td><td>The color of the page's toolbar label and icon when the toolbar item is active. Set the value to a hexadecimal color code, CSS color, or color keyword. When <strong><code>is_toolbar_item</code></strong> is <code>false</code>, the value of this key has no effect.</td><td>No</td></tr><tr><td><strong><code>toolbar_icon</code></strong></td><td>The name of the icon that appears next to the label in the global navigation. For the available icons, see the <a href="https://kizen.github.io/app-engine/index.html">coding reference</a>. When <strong><code>is_toolbar_item</code></strong> is <code>false</code>, the value of this key has no effect.</td><td>No</td></tr></tbody></table>

### About `script.js` for pages

The JavaScript file for a page is the page's main script. Kizen runs the script once, when the page opens. The script sets the starting state of the page.

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 their name and currently active business. However:

* **A page script has no DOM access.** It can show toasts and modals and navigate to other pages, but it can't otherwise change the browser window outside the page.
* **A page script runs only while the page 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 page script starts fresh each time the page opens, including when the user refreshes it or returns to it.** To carry values from previous runs, attach them as query parameters to the page's URL. See [Pass values to the page](#pass-values-to-the-page) below for details.

{% hint style="info" %}
**Note:** You can also store values for the page in the user's configuration or as short-term session data. For more information, see the [coding reference](https://kizen.github.io/app-engine/glossary.html#session-data).
{% endhint %}

* **A page script must finish before the user can interact with the page.** Code that runs on a loop or long delay, like a status message that refreshes every minute, belongs in an event script.

#### Paint content into the page

To paint content into the page, use one of two methods. Use `this.outputUI()` for HTML and CSS:

```javascript
import { paint } from '../../lib/painting.js';

const seed = Number(this.args.seed) || Math.floor(Math.random() * 1e9);

this.outputUI(`
  <div class="modern-art">
    <div class="modern-art__canvas">
      ${paint(seed)}
    </div>

    <p class="modern-art__label">Painting no. ${seed}</p>

    <div class="modern-art__actions">
      <button type="button" class="modern-art__button" data-script="newPainting">New painting</button>

      <form class="modern-art__form" data-script="addToGallery">
        <input type="hidden" name="seed" value="${seed}">
        <button type="submit" class="modern-art__button">Add it to your gallery</button>
      </form>

      <form class="modern-art__form" data-script="hangIt">
        <input type="hidden" name="seed" value="${seed}">
        <button type="submit" class="modern-art__button">Hang it in a floating frame</button>
      </form>
    </div>
  </div>
`);
```

{% hint style="info" %}
**Note:** The **`data-script`** attributes in this example indicate the event scripts to run when the user interacts with the HTML elements on the page. For more information on **`data-script`**, see the [coding reference](https://kizen.github.io/app-engine/glossary.html#data-script).
{% endhint %}

The method takes a single HTML string as its argument. The CSS comes from the page'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 lat = Number(this.args.lat) || 40.7484;
const lon = Number(this.args.lon) || -73.9857;
const d = 0.01;

this.outputIframe(
  `https://www.openstreetmap.org/export/embed.html?bbox=${lon - d},${lat - d},${lon + d},${lat + d}&marker=${lat},${lon}`
);
```

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

#### Pass values to the page

To pass values to the page, attach them to the page's URL as query parameters:

```
https://go.kizen.com/plugins/my_awesome_app/modern_art_page?seed="48213"&status="new"
```

When the page opens, Kizen turns your query parameters into properties of the page's **`this.args`** object. In the example above, the script receives **`this.args.seed`** and **`this.args.status`** with their respective values.

When working with the **`this.args`** object:

* **All values are strings, even numeric values.** Use the `Number()` JavaScript function to convert a numeric string to a number.
* **Missing query parameters are undefined.** If your script depends on a **`this.args`** property to have a value, use the logical OR operator to specify a default, like this:

```javascript
const status = this.args.status || "new";
```

* **The page's event scripts can access the same `this.args` properties as the page itself.** However, the page's `callback.js` script can't. It receives only the values from the callback.

For more information about **`this.args`**, see the [coding reference](https://kizen.github.io/app-engine/04-worker-runtime-api.html#thisargs).

{% hint style="info" %}
**Note:** To get the entire query string, including the leading `?`, use **`this.location.search`**.
{% endhint %}

### About `styles.css` for pages

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

```css
.modern-art__button {
  padding: 10px 20px;
  border: 2px solid #cc0000;
  border-radius: 6px;
  background: #ffffff;
  color: #cc0000;
  font-size: 16px;
  font-weight: 700;
  cursor: pointer;
}

.modern-art__button:hover {
  background: #ffeeee;
}

.modern-art__button:focus-visible {
  outline: 3px solid #663300;
  outline-offset: 2px;
}
```

You don't need a style sheet if your page 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 %}

### About `callback.js` for pages

The `callback.js` file for a page is a script that runs when Kizen's browser window receives a *callback*, which is a cross-document message of the `kizen:plugin_callback` type, while the page is open. The callback arrives when the user completes a task in the embedded page of an external service, like signing an agreement or making a payment. Depending on the service, it can also arrive if the user cancels the task without completing it. The service redirects the user to the `/plugins/callback` address at Kizen, which is what sends the callback message that the page receives along with an optional query string.

The callback script contains logic for what happens on the page in response to the user's action:

```javascript
if (this.args.status === 'signed') {
  this.outputUI(`
    <h1>Signed</h1>
    <p>Contract ${this.args.envelope} is complete.</p>
  `);
  this.showToast('Contract signed');
} else {
  this.outputUI(`
    <h1>Not signed</h1>
    <p>The contract wasn't completed. You can close this page or try again.</p>
  `);
}
```

The script receives values through properties of the **`this.args`** object, which it gets from the optional query parameters of the `/plugins/callback` URL:

```
https://go.kizen.com/plugins/callback?status=signed&envelope=abc123
```

{% hint style="info" %}
**Note:** Floating frames can also listen for callbacks. If your page includes a floating frame and the browser window receives a callback, both the page's `callback.js` script and the frame's `message.js` script run. For more information, see [Create Floating Frames](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/floating-frames.md).
{% endhint %}

***

## Add a page's toolbar item to the global navigation

When a user installs your app, the toolbar items for the app's pages don't automatically appear in their global navigation. The user must manually add them to their toolbar layout.

To add a page's toolbar item to the global navigation:

{% stepper %}
{% step %}

### Open your user profile

In the global navigation, click your avatar, and select **My Profile** from the menu that appears.
{% endstep %}

{% step %}

### Switch to your toolbar settings

Select **My Toolbar**.
{% endstep %}

{% step %}

### Add the toolbar item to the global navigation

To add the toolbar item to the global navigation:

1. In the Available Options list, find the toolbar item to add (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%2FUoygCIH9kZGqR6fNGgTr%2Fappdev_page_availableoptions.png?alt=media&amp;token=2a1fa88e-5fa6-428f-97ed-26803dd7b909" alt="A user finds the Modern Art toolbar item in the list of available options." width="563"><figcaption><p><strong>Figure 2:</strong> A page's toolbar item in the Available Options list.</p></figcaption></figure></div>

2. Drag the item to the Your Toolbar list, and drop it where you want to place it in the global navigation (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%2FZ0JmKfQSXrO0YY4QcuQU%2Fappdev_page_yourtoolbar.png?alt=media&amp;token=b56badf7-bea2-402c-8105-41640013e531" alt="The user drags the Modern Art toolbar item to the Your Toolbar list and positions it among the existing toolbar items." width="563"><figcaption><p><strong>Figure 3:</strong> The page's toolbar item in the Your Toolbar list.</p></figcaption></figure></div>

{% hint style="info" %}
**Note:** Use the mockup of the global navigation under Preview to help you set the order of the toolbar items.
{% endhint %}

3. When you're satisfied with the placement, select **Save**.
   {% endstep %}
   {% endstepper %}

{% hint style="info" %}
**Note:** You can also add the toolbar item for a page to a toolbar template. Depending on the template's settings, other users in your business can access it and apply it to their global navigation without dragging and dropping individual toolbar items. For more information, see our [knowledge base](https://kizen748362562368528725.freshdesk.com/a/solutions/articles/154000202833?portalId=154000122462).&#x20;
{% endhint %}

After you add toolbar items from an app to the global navigation, uninstalling the app hides its toolbar items but doesn't remove them entirely. Reinstalling the app causes the toolbar items to reappear as they were. However, if you adjust your toolbar layout and save it while the app is uninstalled, reinstalling the app doesn't restore its toolbar items. You must add them again manually.

***

## What's next?

Continue to [Create Blocks](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-blocks.md) to learn how to include blocks in 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 Blocks](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-blocks.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-pages.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.
