Add app-bar buttons and iframes

An app bar adds a button or embedded page to Caraer. Choose its location based on the task: a record action receives record context, while a toolbar action can work without a selected record. Begin with a scaffolded app and a sandbox installation.

Action buttons

An action invokes a function. Declare it alongside the handler in a current CLI app-bar module, using a stable name. Follow collect input from an app-bar action for a complete example with a file dialog and the correct payload fields.

Choose a location

Location	Suitable task
RECORD_PREVIEW	An action from a compact record preview
RECORD_OVERVIEW	An action from a record listing
RECORD_TRAIT	A trait-specific record action
RECORD_DETAIL	An action or embedded page within record details
TOOL_BAR	A tool independent of one record
TRAIT_BAR	A tool associated with a trait

RECORD_PREVIEW, RECORD_OVERVIEW, and RECORD_TRAIT can collect dialog input before invoking the handler. Configure the bar’s settingsSchema for that input and read it from appBarSettingsValues.

Embed an iframe

A bar can open an external page instead of invoking an action. Declare the iframe on an app-bar module’s exported manifest:

export const manifest = {
  appBars: [{
    name: 'inbox_panel',
    location: 'RECORD_DETAIL',
    label: 'Inbox',
    iframeUrl: 'https://apps.example.com/inbox?record={recordUuid}&object={object}',
  }],
};

Supported URL placeholders include {recordUuid}, {object}, {viewId}, {trait}, and {companyUuid}. Use only context that is present for the selected location.

The embedded page receives a short-lived iframe session. Validate that session using the App Bar Iframe Sessions API before trusting its context or scoped apiToken. Keep tokens out of URLs, settings, and logs.

Validate the installed experience

caraer apps validate
caraer apps push --deploy
caraer apps status

Configure the installation’s visibility and open the intended location. For an iframe, check the final URL and session validation; for an action, check its actual handler response and saved result. Do not infer these from rendered button text or runtime readiness.

Common mistakes

Keep stable names so later pushes update the same bar. Use installation visibility when hiding a bar in one company; removing it from the manifest removes the shared definition. Use injected runtime context instead of asking installers for platform URLs.