Skip to content
Verified

Component

The unit of UI, an element tree bound to local state, data and the workflow logic that wires it together.

A Component is a UI unit: an element tree bound to local state, optional data, lifecycle logic and an input and output interface. A page, a card, a modal, a popover, an inline fragment, they are all Components, and it is the richest document type in the platform, carrying its own UI tree alongside the fields, events and datasource shared with every other program type.

Properties

renderType is a legacy flag, not a live property

renderType (form / grid / list) is deprecated and no longer required; new components are created without it. What a new Component actually gets is a scaffold choice, single or multi, picked once in the New Component dialog: single seeds a bare xu-template root ready to build into directly, multi seeds the same xu-template root with a loading div and an xu-multi-view already nested inside it. xu-single-view is still a real, authorable tag, just not one the factory places for you: only an unmigrated legacy doc (root not yet xu-template) is checked against it, when its stale renderType still says form.

progUi, the element tree

The root node is always a transparent xu-template, seeded by create_prog's scaffold_prog_ui. Choosing the multi scaffold nests a loading div and an xu-multi-view inside it for you; the single scaffold leaves it empty, build directly inside its children. Every node needs a unique id, type: "element", a tagName, and attributes: {} and children: [] even when empty.

Besides plain HTML tags, a handful of xuda tags are authored directly: xu-template, xu-single-view, xu-multi-view, xu-panel, xu-teleport, xu-slot.

A capitalised tagName (Button, Dialog) is always claimed as a compiled design-system component, never an HTML element, even when it is a typo: it throws at mount, naming the tag and every source tried. Its plain attributes become props, not DOM attributes (variant, color, class all arrive as props.<name>), and unlike xu-panel it has no out-params, a component tag only reads what you pass it.

Dynamic behavior: xu-* attributes

Every xu-* attribute a Component's element tree can carry:

Two are easy to get backwards: xu-bind takes the bare field id, no @, the one exception to the @ rule everywhere else; and xu-exp:class replaces the static class attribute entirely, so layout classes have to be repeated inside the expression.

progFields, progEvents, progDataSource

Local state (progFields, virtual or table-bound), an optional embedded Datasource, and lifecycle events. Three of those events split the work in a way that is easy to get backwards:

Putting refresh work in screen_ready re-runs create logic against DOM that still exists, and stacks a second widget on top of the first.

Embedding another program: xu-panel

xu-panel (lower-case tagName, program attribute) mounts another Component prog with its own fields, datasource and events, in contrast to a capitalised design-system tag. Pass values into its _in params with xu-exp:<param> attributes; unlike a design-system tag, a panel can write values back to your fields through its _out params.

json
{ "id": "ui-…", "type": "element", "tagName": "xu-panel", "attributes": { "program": "392_cmp_child…", "xu-exp:order_id_in": "@selected_order_v" } }

Worked example

Choose the shape

Pick single in the New Component dialog for one record: build directly inside the xu-template root. Pick multi for a list: it seeds an xu-multi-view inside that root for you, add xu-for (or the .xu for= shorthand) on the repeating node.

Bind the data

xu-bind for inputs, xu-exp:xu-content for computed text, a progDataSource if the component owns its own read.

Wire the interaction

xu-on:click with a workflow, or in .xu, a named action block referenced with @click.

Build the tree on the canvas: drag elements, set attributes in the properties panel, wire xu-on:* handlers to workflow steps in the workflow editor. Press the preview play button to check the result live.

xml
<meta lang="json5">
{
  id: "user_profile_card",
  menuTitle: "User Profile Card",
  uiFramework: "@xuda.io/xuda-framework-plugin-tailwind"
}
</meta>

<params lang="json5">
{
  in: { user_name_in: "string", user_role_in: "string" }
}
</params>

<template>
  <single-view>
    <aside class="user-card">
      <div class="avatar" :content="(@user_name_in || 'A').substring(0, 1)"></div>
      <h3 :content="@user_name_in"></h3>
      <p :content="@user_role_in"></p>
    </aside>
  </single-view>
</template>

<style>
.user-card { display: grid; gap: 0.75rem; padding: 1rem; border-radius: 1.2rem; }
</style>

.xu compiles <single-view> to xu-single-view, :content to an xu-exp:xu-content expression, and a bare for="@list_v" attribute to xu-for.

json
{
  "properties": { "menuType": "component", "menuName": "Student Card", "rwMode": "U", "allowCreate": false },
  "progUi": [
    { "id": "root", "type": "element", "tagName": "xu-template", "attributes": {}, "children": [] }
  ],
  "progFields": [
    { "id": "b2c3d4e5-…", "data": { "field_id": "STU_Student_Id", "type": "table" }, "props": { "fieldType": "string" } }
  ],
  "progEvents": [
    { "id": "d4e5f6a7-…", "data": { "type": "on_load", "parameters": [], "condition": "" }, "workflow": [] }
  ]
}