snackapp.ui. Every example is a complete
page module: paste it into a new file under pages/ of a project scaffolded by
snackapp init and it runs against that project’s items and notes
collections.
The types a primitive renders come from the collection’s declared schema. The
storage shape, the operands, and the renderer of each type are in the
field-type reference.
A page function runs once per navigation, on the server, with real data in
hand. What it returns is a tree, not HTML. Typing, sorting a loaded table,
opening a modal, and switching a tab never call Python again; an
@action
does.Layout
ui.header
A button passed to
actions is moved into the header, so it renders once.
ui.row
Children wrap, and below 768px they stack.
ui.column
ui.card
ui.tabs
ui.tab children and nothing else; switching one
is client-local and calls no Python.
ui.tab
ui.fragment
A fragment is what replaces a whole-page rerun: an action names it and only
this subtree is rebuilt. The collections read inside it become its
dependencies, so a write to one refreshes it without being asked.
ui.grid
Below 768px it is one column.
ui.divider
Display
ui.text
ui.markdown
ui.stat
Handed a
Query, it issues an aggregate; the rows it counts never leave the
database.
ui.badge
ui.empty
Data surfaces
Each of the four view types takes either a materialisedlist[dict], which is
paged in the browser, or a Query, which is paged on the
server: the page function registers it and the client fetches every page —
the first one included — through /_sa/rows.
ui.table
A column’s type comes from the declared schema, so the renderer and the editor
match the field type without the page repeating it.
A single column opts out with
{"field": ..., "editable": False}. Grouping
comes from the URL, and each group gets its own cursor and its own count.
ui.list_view
This is also what a board or a calendar falls back to below 768px.
ui.kanban
With no
on_move, a drop writes group_by through the record endpoint. The
column count and the value_field sum are aggregates over the whole column,
not over the cards that happen to be loaded; value_field must be a number,
because the aggregate endpoint refuses sum() over a JSON column.
ui.calendar
date_field is checked against the declared schema when the page runs, so a
calendar over a field that is not a date fails with the dated fields named
rather than rendering nothing.
ui.fields
An editable grid needs one of
collection or action, or it raises.
ui.record
A tab is
"notes" — a collection that points back at this one — or a dict:
{"collection": ..., "via": ..., "columns": [...], "label": ..., "row_link": ..., "page_size": ...} when the pointing field is ambiguous or is not a relation, or
{"field": ...} to list the records a multi-relation on this record points at.
Each tab’s count is an aggregate over the whole related set.
ui.timeline
Naming a
collection and an id shows the framework’s own feed: what it wrote
when the record was created and when a tracked field changed, plus the comments
people added, newest first. Tracking is activity=True on the collection.
ui.chart
A chart over a query is one
GROUP BY computed by the backend. Six widgets on
a dashboard are six aggregates, not six scans.
ui.bar_chart
The minimal bars, for a series a page function already has.
ui.chart is what
aggregates.
View controls
ui.view_bar
The current view is whatever the address bar says, so switching is a navigation
and the back button undoes it. With
collection, the bar shows the defaults
views= declares on the collection — which cannot be renamed or deleted — plus
the personal and shared views the signed-in user can see, and saving, renaming,
duplicating and deleting go through /_sa/views.
ui.filter_bar
Filters bind to the URL, not to hidden server state, so a filtered view is
shareable and back-button correct. With
collection, the filter, sort and group
builders offer exactly the operands each field’s type declares, so a user cannot
compose a filter the compiler would reject.
Input
ui.button
confirm is checked first, then opens, then link, then action.
ui.form
Draft state lives in the browser: Python never sees a keystroke. Without
collection, a field with no declared type is a text box — which is how a
url field ends up rejected by the backend on submit rather than by the editor
on the way in.
ui.modal_form
ui.form’s. The form is declared where the page wants it and
stays closed until a ui.button(opens=name) reveals it; a successful submit
closes it.
CSV
ui.import_csv
Upload, preview, map, validate, write — in that order. Nothing reaches the
collection until the mapping is confirmed and every row validates, and the
wizard refuses at the start for a user who cannot create in the target. Computed
fields are not offered as targets.
ui.export_csv
The export is the view: the same query, narrowed by the same URL, streamed from
the server a page at a time rather than assembled in the browser.