> 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/data-adornments.md).

# Create Data Adornments

Include data adornments in your Kizen apps for selectable icons next to Date, DateTime, and Phone Number fields, each with its own custom script.

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

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

## Overview

*Data adornments* are graphical icons that appear next to Kizen fields of a particular type (see Figure 1). Selecting the adornment launches a custom script.

<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%2FxBwZXMamUR6sYIQoAt8e%2Fappdev_dataadornments.png?alt=media&amp;token=d246da6b-09ad-46ee-9643-b7a851622831" alt=" A data adornment from an app enables the user to see the value of DateTime fields in New York time." width="563"><figcaption><p><strong>Figure 1:</strong> A data adornment from an app.</p></figcaption></figure></div>

Kizen adds the adornment to all fields of its type throughout the user's business, although empty fields don't get the adornment. You also can't suppress the adornment on any field that has a value.

Any given app supports a single data adornment per field type. If your app attempts to add more than one adornment to the same type of field, the app's build fails. However, if multiple apps add adornments to the same type of field, Kizen displays an ellipsis next to these fields. Selecting the ellipsis opens a menu of all the field's active data adornments (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%2FNk7w9UPBzY5lpkNS1pUi%2Fappdev_dataadornments_ellipsismenu.png?alt=media&amp;token=b068589e-f617-42d3-bd2d-41c4cf383d65" alt="The user opens a data adornment&#x27;s ellipsis menu in an environment where two different apps add adornments to the same type of field." width="381"><figcaption><p><strong>Figure 2:</strong> The ellipsis menu for multiple data adornments.</p></figcaption></figure></div>

***

## Add a data adornment to your app

Add your data adornment to the `dataAdornments` directory in `src`. Place each adornment in its own subdirectory with `config.json` and `script.js` files, like this:

```
src/
└── dataAdornments/
    ├── newYorkTime/
    │   ├── config.json
    │   └── script.css
    └── quickCaller/
        ├── config.json
        └── script.css
```

The following table describes these files:

| File          | Type       | Purpose                                                       | Required? |
| ------------- | ---------- | ------------------------------------------------------------- | --------- |
| `config.json` | JSON       | The configuration file for the data adornment                 | Yes       |
| `script.js`   | JavaScript | The script that runs when the user selects the data adornment | Yes       |

Data adornments also support custom icons. Include a PNG or SVG file for the icon in the adornment's directory. If you don't supply a custom icon, you can configure the adornment to use any of Kizen's built-in icons.

```
src/
└── dataAdornments/
    └── quickCaller/
        ├── config.json
        ├── phone.svg
        └── script.js
```

See below for details on each of these files.

### About `config.json` for data adornments

The configuration file for a data adornment sets the properties of the adornment:

```json
{
  "icon": "globe",
  "color": "#0000ff",
  "tooltip": "Convert to New York time",
  "customIconFile": "clock.svg",
  "field_type": "datetime",
  "when": "!{{userConfig.hideNewYorkTime}}"
}
```

{% hint style="info" %}
**Note:** The configuration above includes sample values for **`icon`**, **`color`**, and **`customIconFile`**. In actual practice, Kizen defaults to the custom icon file when you specify one and ignores the values of **`icon`** and **`color`**. If this were a real configuration, you would use either **`icon`** and **`color`** or **`customIconFile`** but not all three together.
{% endhint %}

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>icon</code></strong></td><td>The name of the icon that appears as the data adornment. For the available icon names, see the <a href="https://kizen.github.io/app-engine/index.html">coding reference</a>. If you supply a custom icon, Kizen ignores the value of this key.</td><td>No</td></tr><tr><td><strong><code>color</code></strong></td><td>The color of the data adornment. If you supply a custom icon, Kizen ignores the value of this key.</td><td>No</td></tr><tr><td><strong><code>tooltip</code></strong></td><td>The text that appears when the user hovers over the data adornment.</td><td>No</td></tr><tr><td><strong><code>customIconFile</code></strong></td><td>The file name of the PNG or SVG file to use as the data adornment icon. Store this file at the same level of the directory structure as the <code>config.json</code> file.</td><td>No</td></tr><tr><td><strong><code>field_type</code></strong></td><td><p>The type of field to which to apply the data adornment:</p><ul><li><code>date</code>. Apply the data adornment to all Date fields in the user's business.</li><li><code>datetime</code>. Apply the data adornment to all DateTime fields in the user's business.</li><li><code>phonenumber</code>. Apply the data adornment to all Phone Number fields in the user's business.</li></ul></td><td>No</td></tr><tr><td><strong><code>when</code></strong></td><td>A condition that determines when to show the data adornment on the screen. This condition applies to all fields of the specified type, not just to a particular field. 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>

### About `script.js` for data adornments

The JavaScript file for a data adornment is the adornment's main script. Kizen runs the script when the user selects the adornment.

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. It knows the user's name and currently active business. It also knows where the user selected the adornment by its associated field, record, and so on, all of which the script can read from properties of the **`this.args`** object. See the following table for details.

| this.args property | Contains                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **`entityId`**     | The ID of the specific record                                                                                                  |
| **`fieldId`**      | The ID of the specific field                                                                                                   |
| **`fieldType`**    | The type of the field: `date` for the Date type, `datetime` for the DateTime type, and `phonenumber` for the Phone Number type |
| **`objectId`**     | The ID of the record object                                                                                                    |
| **`value`**        | The value of the field                                                                                                         |

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

However, keep in mind these limitations:

* **A data adornment script has no DOM access.** It can display toasts and modals, and it can navigate to other pages, but it can't directly edit the content in the browser window.
* **A data adornment script requires user interaction.** It can't launch itself. For tasks that need to run automatically, use an agentic workflow code step instead.
* **A data adornment script starts fresh on each run.** 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).

***

## What's Next

Go to [Create App Surfaces](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces.md) to explore the types of surfaces that you can include 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 Pages](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-pages.md)
* [Create Blocks](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-blocks.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/data-adornments.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.
