Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Create Pages

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

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.

 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.
Figure 1: A page from an app.

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


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:

Note: Depending on the page, you might not need one or more of the files.

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.

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:

The keys are as follows:

Key
Description
Required?

api_name

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.

Yes

name

The name of the page.

No

is_toolbar_item

Whether the page adds a toolbar item to the global navigation. When this value is true, the name field supplies the label of the page's toolbar item.

No

toolbar_color

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 is_toolbar_item is false, the value of this key has no effect.

No

toolbar_icon

The name of the icon that appears next to the label in the global navigation. For the available icons, see the coding reference. When is_toolbar_item is false, the value of this key has no effect.

No

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 below for details.

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.

  • 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:

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.

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.

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

Note: Another way to embed a live web page is to write an <iframe> element into your custom HTML with this.outputUI().

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.

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.

Pass values to the page

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

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:

  • 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.

Note: To get the entire query string, including the leading ?, use this.location.search.

About styles.css for pages

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

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

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.

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:

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

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.


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:

1

Open your user profile

In the global navigation, click your avatar, and select My Profile from the menu that appears.

2

Switch to your toolbar settings

Select My Toolbar.

3

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

A user finds the Modern Art toolbar item in the list of available options.
Figure 2: A page's toolbar item in the Available Options list.
  1. Drag the item to the Your Toolbar list, and drop it where you want to place it in the global navigation (see Figure 3).

The user drags the Modern Art toolbar item to the Your Toolbar list and positions it among the existing toolbar items.
Figure 3: The page's toolbar item in the Your Toolbar list.

Note: Use the mockup of the global navigation under Preview to help you set the order of the toolbar items.

  1. When you're satisfied with the placement, select Save.

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.

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 to learn how to include blocks in your app.


Last updated

Was this helpful?