cadau
Log inTry Cadau
ProductAppsSolutionsPlansDocsBlogForumAbout
Log inTry Cadau
← All docs

App views

Views and layout: what you can do, what you cannot, how to add more later.

Source docs/en/site/sdk-appsdk-layout.md

Views and layout: what you can do, what you cannot, how to add more later.

Readers: people who need to understand “what the UI looks like” and “how to build a UI from a design / screenshot”. Related: App UI description · Hand-build an app · Platform plugin SDK

1. Currently only three views

The standard renderer only recognizes:

TypeWhat the user seesWhat a click does
listTable listLoad/refresh/optional delete; with upload_id can open/download attachments
formEntity registration formCreate one row in the local business DB (crud.create)
action_formAction-param formCall a custom action (usually handlers.py)

There is no fourth. Unknown type: validation may fail; even if it reaches the frontend, it is skipped (not shown).

Field-level writing: App UI description.

2. Is there “layout”?

There is no standalone layout model. There is no:

  • Columns / grid / sidebar / tabs
  • Master-detail, drawers, overlays (delete confirm is a platform-unified confirm, not a configurable layout)
  • Custom CSS, free HTML component trees, routed subpages

The only “layout” tools:

  1. views[] array order → cards stacked top to bottom on the page
  2. Field/column order inside each block → fields / columns / actions[].params
  3. Platform-unified skin → .wa-* styles; authors cannot change them

So: you can build tool pages such as “form on top + history below”. You cannot reproduce a complex operations-back-office look from a design.

3. If you want new views / layout later, how?

Treat it as “change the platform contract”, not only one app’s app.json.

3.1 Suggested flow

  1. Product freeze: what the new view gives users (for example “kanban”, “detail page”, “editable table”).
  2. Extend the contract (same version or bump):

- backend/internal/workspaceapp/spec.go: ViewDef + ValidateSpec - client/web/src/api/apps.ts: WorkspaceAppViewDef - client/web/src/WorkspaceAppRenderer.tsx: add a render branch - Sync this document and App UI description

  1. Optional: sync the app-development assistant’s system prompt / validation hints so it does not invent unsupported types.
  2. Migration: old apps without the field keep the same behavior; new fields need defaults and validation.

3.2 Approaches we do not recommend

ApproachWhy
Invent type: "dashboard" in app.json without changing the rendererFrontend ignores it; users think it is broken
Stuff complex UI semantics into action_formDescription drifts from real controls; hard to maintain
Return HTML from handlers.py as a “whole-page UI”Current standard UI only understands limited result fields (for example upload_id), not a custom page shell

3.3 The proper exit for complex UI

Need a full web close to a design (multi-page, charts, drag-and-drop, own component library) → use a platform plugin (apps-desktop iframe + your own frontend). Do not force-expand lightweight workspace apps.

4. “Upload a picture and build the UI from it” — how?

First split the goal:

What you wantRecommended path
A. A report/result page that looks like a picture (for example employee-profile HTML layout)Lightweight app: assets/*.html + assemble script + field mapping; the UI entry is still a standard form
B. The app operations UI looks like a design (many blocks, complex interaction)Platform plugin draws its own UI; or wait until the platform adds view types and then use declarative
C. Use AI to tweak an existing form/list from a screenshotApp-development assistant: treat the picture as an attachment describing intent → still only structures the three views can express

4.1 Path A: “result layout” from a picture (employee-profile family)

Fits: the screenshot is a report/file page; the user fills a few params and gets previewable HTML.

  1. Turn the target layout into assets/xxx.html (hand-restore from design first, or export static HTML from design).
  2. Use references/field-mapping.json (or logic inside the assemble script) to fill fetch results into the template.
  3. app.json only provides a standard entry: action_form (input) + list (history, optional upload_id to open the result).
  4. Action implementation: handlers.py → fetch → assemble → platform.save_upload → return upload_id.

What the picture is for here: a layout reference for people/assistants. What lands is an HTML template, not a PNG as a runnable UI.

Details: App data pipeline, App actions.

4.2 Path B: “the operations console itself” from a picture

Fits: the screenshot is a full business UI (nav, multi-panel, complex controls).

  1. Build the frontend as a platform-plugin project (any framework).
  2. Register it in Cadau as an apps-desktop plugin.
  3. If conversation should call the same backend, add skills + an internet capability pack (see pluginsdk).

A lightweight app cannot render an uploaded PNG/JPG as a clickable business UI.

4.3 Path C: attach a picture for the app-development assistant

  1. In the app-development assistant conversation, paste/upload a screenshot and say in natural language: “form on top, list below”, “remove delete”, and similar.
  2. The assistant can only output app.json (and optional scripts) that match the current contract.
  3. If the screenshot far exceeds the three views, switch to a plugin, or split into “standard operations page + HTML result page” (path A).

4.4 Decision sketch

Is the upload a “result page / report” sample?
  ├─ Yes → path A: HTML template + fetch assemble + standard form entry
  └─ No (operations console / complex layout)
        ├─ Must be pixel-accurate → path B: platform plugin
        └─ Standard list/form is acceptable → path C: assistant changes app.json, or hand-write the three views

5. Relation to the UI description spec

  • How to write fields: App UI description wins.
  • How to build the whole pack, how to write scripts: other documents in this directory.
  • This page: answers “why only three”, “layout bounds”, “which path for UI from a picture”.