form-list-layout

Form and List Layout

ui-actions-policies covers behaviour on a form — what happens when a field changes. This covers the shape of it: which fields are on the form, in what order, in which sections, and what the list shows. Nothing covered lists at all before this guide.

Views come first

Almost every table in this guide has a view field, and it is the thing to decide before anything else.

A view is a named layout for one table. The empty string "" is the default view — the one everyone gets. "mobile", "ess" and any custom name are separate layouts on the same table, and editing one changes nothing about the others.

await snow_add_list_column({ table: "incident", element: "u_root_cause" })   // default view: everyone
await snow_create_list_layout({ table: "incident", view: "mobile", columns: [...] })  // mobile only

Getting this wrong is the most common way to "change nothing" — the edit landed on a view nobody opens — and the most common way to break a form for the whole company, which is the same mistake pointed the other way.

The field must exist first

sys_ui_element and sys_ui_list_element hold a field name as a string. Neither the platform nor these tools check that the column exists in sys_dictionary. Placing a field that is not there produces a layout row that silently renders nothing.

Check before you place:

await snow_discover_table_fields({ table: "incident" })

The same applies to dot-walked columns on a list (caller_id.department): the path has to resolve or the column comes back blank.

Forms

sys_ui_form       the form layout for (table, view)  — the container
  └── sys_ui_section    a section on it, with a caption and a position
       └── sys_ui_element   one field, with a position inside the section

Build outward from the container:

const form = await snow_create_form_layout({ name: "Incident", table: "incident", type: "standard" })
const sec = await snow_create_form_section({ name: "Root cause", table: "incident",
                                             caption: "Root cause", position: 2 })
await snow_add_form_field({ section_sys_id: sec.sys_id, element: "u_root_cause", position: 1 })