App UI description

Workspace apps · UI description spec (full).

Doc version: 1.0 (matches app.json / AppSpec v1) Readers: people who hand-write or review an app UI description (including the app-development assistant when it revises a draft) Related: appsdk directory notes · App views · Hand-build an app · Workspace apps mechanism

---

1. Core principles

1. The UI is generated from a description, not a hand-written web page. The platform Web standard renderer reads app.json and draws lists and forms from views.
2. One description does three things: what data looks like (entities) → which blocks the page has (views) → what buttons call (actions).
3. User-visible copy uses label; name / id / action are program ids (lowercase, underscores, and similar). Do not use them as UI titles.
4. Currently only three views: list | form | action_form. There is no standalone layout model; extensions and “UI from a picture” are in App views.

When the app opens, the renderer draws each block top to bottom in views array order.

---

2. Files and pack location

When hand-writing the UI, you usually only change app.json. If you add a custom action, you also implement the matching action id in handlers.py.

---

3. Root object

{
  "version": 1,
  "entities": [ /* at least one */ ],
  "views": [ /* at least one */ ],
  "actions": [ /* actions referenced by action_form must be declared here */ ]
}

Validation failure cannot save/publish (see §10).

---

4. Entities entities[]

One business table (SQLite) inside the app. The platform automatically adds primary-key column id (autoincrement). You need not declare id in fields.

{
  "name": "profile_reports",
  "label": "Profile records",
  "fields": [
    { "name": "emp_name", "label": "Employee name", "type": "text", "required": true },
    { "name": "status", "label": "Report status", "type": "select", "default": "待生成",
      "options": ["待生成", "已生成", "失败"] },
    { "name": "created_at", "label": "Generated at", "type": "datetime", "read_only": true, "auto": "now" }
  ]
}

4.1 Entity attributes

4.2 Fields fields[]

Field types and UI controls:

Time conventions (aligned with product “time display and timezone preference”):

• On disk: datetime / auto=now are UTC absolute-time strings; do not store “Beijing time pretending to be local, with no timezone” in the DB.
• List display: the platform formats by the current user’s display timezone, date format, and 12/24-hour setting; not the browser system timezone.
• Form input: the user fills wall clock in the display timezone; submit converts to UTC ISO.
• Account preference itself cannot be written into app.json; point users to “Me → Preferences → Time display”.

4.3 Special list convention

If the entity has a field named upload_id (stores an attachment id), the list Actions column offers Open / Download for rows that have a value (used for employee-profile HTML reports and similar). This is a renderer convention, not a separate view type.

---

5. Views views[] (how the UI is drawn)

Each element is one UI block. type decides what is drawn.

5.1 List list

Shows a table for an entity; data comes from built-in action crud.list.

{
  "type": "list",
  "id": "history",
  "label": "Past profiles",
  "entity": "profile_reports",
  "columns": ["emp_name", "report_title", "status", "created_at"],
  "limit": 100,
  "allow_delete": true
}

UI behavior: “Refresh” next to the title; delete calls crud.delete.

5.2 Entity form form

Inserts one row into an entity; submit calls crud.create.

{
  "type": "form",
  "label": "New note",
  "entity": "notes",
  "mode": "create",
  "fields": ["title", "body"]
}

Fields that do not appear on the form: id, hidden=true, read_only=true, auto=now (auto=now is written by the frontend on submit; no input shown).

5.3 Action form action_form

Collects params and calls a custom action (usually impl=script).

{
  "type": "action_form",
  "id": "generate",
  "label": "Generate employee profile",
  "action": "profile.generate"
}

Important (not intuitive): when the standard renderer draws an action form, inputs come from actions[].params, not views[].fields. views[].fields may be documentation/assistant hints, but the current frontend does not generate controls from it. When hand-writing, put form fields on the matching action’s params.

After submit: calls invoke(action, params). If the result includes upload_id (and optional filename), the UI can offer open/download report (same as employee profile).

---

6. Actions actions[]

{
  "id": "profile.generate",
  "label": "Generate employee profile",
  "impl": "script",
  "params": [
    { "name": "emp_name", "label": "Employee name", "type": "text", "required": true },
    { "name": "emp_id", "label": "Employee ID (when names collide)", "type": "text" }
  ]
}

6.1 Params params[]

select on action params: if you need a dropdown, the current action-param structure does not include options. Put dropdown options on entity fields and use form/list. Action forms currently center on text/number/textarea/datetime (aligned with renderer resolveActionFields). For enums, use text and validate in the script, or extend the contract later.

6.2 Built-in actions (need not be in actions)

Provided by the platform; lists/forms call them automatically:

A custom action referenced by action_form but missing from actions → validation fails.

6.3 Mapping to handlers.py

When impl=script, runtime calls the in-pack script entry, roughly:

handle(action, params, ctx) -> dict

• action equals actions[].id (for example profile.generate)
• params are key-values submitted from the form
• Return should include ok; on failure include error; optional upload_id / warnings and similar for the UI

Script detail and the platform bridge (fetch data, save attachments) are in the mechanism docs under “invoke”. Whether a button appears on the UI is still decided by this file’s actions + action_form.

---

7. Minimal hand-written example (notebook)

{
  "version": 1,
  "entities": [
    {
      "name": "notes",
      "label": "Notes",
      "fields": [
        { "name": "title", "label": "Title", "type": "text", "required": true },
        { "name": "body", "label": "Body", "type": "textarea" },
        { "name": "created_at", "label": "Created at", "type": "datetime", "read_only": true, "auto": "now" }
      ]
    }
  ],
  "views": [
    {
      "type": "form",
      "label": "New note",
      "entity": "notes",
      "mode": "create",
      "fields": ["title", "body"]
    },
    {
      "type": "list",
      "label": "All notes",
      "entity": "notes",
      "columns": ["title", "created_at"],
      "allow_delete": true
    }
  ]
}

No actions needed: only form + list, all built-in CRUD.

---

8. Hand-written example with a custom action (sketch)

{
  "version": 1,
  "entities": [
    {
      "name": "jobs",
      "label": "Job records",
      "fields": [
        { "name": "keyword", "label": "Keyword", "type": "text", "required": true },
        { "name": "status", "label": "Status", "type": "select", "options": ["待处理", "完成", "失败"] },
        { "name": "upload_id", "label": "Attachment ID", "type": "text", "hidden": true },
        { "name": "created_at", "label": "Time", "type": "datetime", "read_only": true, "auto": "now" }
      ]
    }
  ],
  "views": [
    {
      "type": "action_form",
      "id": "run",
      "label": "Run job",
      "action": "job.run"
    },
    {
      "type": "list",
      "label": "History",
      "entity": "jobs",
      "columns": ["keyword", "status", "created_at"]
    }
  ],
  "actions": [
    {
      "id": "job.run",
      "label": "Run job",
      "impl": "script",
      "params": [
        { "name": "keyword", "label": "Keyword", "type": "text", "required": true }
      ]
    }
  ]
}

You also need to implement job.run in logic/handlers.py (produce a result, optionally write the jobs table). Changing only the UI description without a script will fail on submit.

---

9. Employee-profile walkthrough (live structure)

A complete sample is the app.json in the runtime app pack (employee-profile template).

---

10. Validation checklist (self-check after hand-writing)

• [ ] entities ≥ 1, and each has name/label/fields
• [ ] Entity names and field names match the lowercase-id rules; fields have label; types are valid
• [ ] views ≥ 1; type is only list | form | action_form
• [ ] list/form entity exists
• [ ] Each action_form action exists in actions
• [ ] Each actions[] has id/label; impl is script or crud.create
• [ ] Action-form fields are on actions[].params, not only on views[].fields
• [ ] Custom actions are implemented in handlers.py (if impl=script)
• [ ] User-visible copy is all in label; English ids are not used as titles

Implementation validator: workspaceapp.ValidateSpec.

---

11. Explicitly out of this spec

---

12. Revision convention

• Contract changes (new view types, field attributes, action-param options, and similar) must sync: this file, spec.go validation, WorkspaceAppRenderer.tsx render behavior, and bump this section’s doc version.
• Mechanism overview Workspace apps may keep a short summary; full hand-write notes are this document.