Handbook · Where data lives
Where data lives
Where in the UI. Binding pickers appear on Layout inspectors, Structure field-bindings nodes, edit-filter watch lists, and some actions.
If you remember one page, remember this one. A binding is a pointer into a real store. Point at the wrong store and the widget is blank, or worse, writes the wrong place.
Five places values live
| Place | Survives save? | Who writes it | Example |
|---|---|---|---|
| Item fields | Yes — the item row | User, layout edit, scripts, field bindings | title, amount, backgroundColor |
| Category properties | Yes — per assigned category | User (Edit Entry), scripts if scriptWritable | Nickname, voltage, brew mass |
| Item variables | Yes — itemVariablesJson | Scripts (and some bindings) | runningTotal, selectedChildId |
| Localized template strings | Yes — template JSON | You, in the translations matrix | Button labels, alerts via ContaindText |
| Runtime / session | No (session or clock) | Host | currentDateTime, canvasScale, localState |
Item fields vs category properties
Item fields exist on every item in Containd (title, geometry, value…). Use them when the concept is universal. Category properties exist only if that category is assigned. Use them for domain fields (“roast date”, “ISBN”). Nested categories inherit ancestor properties; the binding still names the owning category id.
Localized strings (not a binding)
Author the template in the primary locale. UI chrome and script messages that users will see should go through the translations matrix (and Containd text blocks in Blockly), not hardcoded English in a stock text block. IDs, property keys, and class ids stay untranslated.
A locale string is not a DataRef. You cannot bind a widget to “the German title of this button” the way you bind Title. You author one key; the host picks the string for the current language. Bindings point at item fields, category properties, variables, metrics, and similar stores — see DataRef kinds.
Not bindable as a single scalar
Tags, documents, history, embeddings, and similar blobs have their own editors. You cannot hang one text widget on “the whole tag list” as an itemField. Use metrics (tagCount) or scripts that call host methods instead.
Full lists: item fields, DataRef kinds.