Editing a model in the browser#
model edit serves a form-based editor for a model directory. It is an
alternative to writing the YAML by hand, not a replacement: it writes the same
files, and leaves everything it does not edit as it found it.
Install#
The editor’s UI is NiceGUI, an optional dependency:
pip install 'model[editor]'
With Nix, nix run gitlab:terryp/model#editor -- ./catalog runs it without
installing anything.
Run#
model edit ./catalog
This serves the editor on http://127.0.0.1:8080 and opens it in a browser.
--port and --host move it, and --no-show leaves the browser closed.
/?name=Product opens the editor on the type Product.
The page has three parts:
The type files, on the left, each tagged with its kind. New type adds a struct, enum or union.
A form for the selected file. A struct lists its fields, an enum its values, and a union its variants. Each can be added, renamed, moved and deleted.
The model’s status, along the bottom. A moment after each edit the model is loaded as
modelwould load it, with the nearestmodel.toml, and this says whether it loads, or why it does not and in which file.
Save (or Ctrl+S) writes every changed file. The editor asks before a tab with unsaved changes closes.
Field forms#
A field’s form comes from its type’s entry in the
field-type catalog. Picking a type shows its parameters,
such as a string’s min_length or a list’s values. A constraint that is set
reads back as the sentence a generated form shows for it, such as Must have at
least 5 characters. Changing the type drops the old type’s parameters and
keeps the field’s display, desc and required.
A reference, such as a ref’s referenced_type, picks from the model’s
types. A list’s values, a map’s keys and values, and a union variant’s
inline type are edited with a nested form of their own.
Some keys have no form yet: a struct’s xml and meta,
extension keys, and parameters such as a path’s relative_to. These are
shown as YAML, under Other keys. A route has no form at all, and is edited
entirely as YAML.
Summary#
A struct’s summary is under Summary, above its perms.
Fields picks from the struct’s fields, Title and Subtitle are the
templates, typed as they are written in the file, and Image picks from its
url and path fields. Clearing all of them drops summary from the file.
Perms#
A struct’s perms are under Perms, above its fields, and each
field has its own under Perms in its card. A toggle picks flat perms or
perms by class, which show a row for each of
user, group and other. Each perm picks anonymous, authenticated,
false, a perm the model already uses, or a new one typed in. Under each perm
is what it means when it is cleared, such as Unset: as read.
Switching to perms by class keeps what the perms allow. A flat perm left out
requires nothing, but one left out of a class allows nothing. So a struct’s
flat perms move to other, with read and update set to anonymous where
they were left out, and a left-out create takes update’s value, as it fell back
to. A field’s move to other as they are, since an action that no class sets
adds nothing to the struct’s.
Switching back to flat drops the classes, owner_field and group_field,
after asking, since flat perms cannot say them. A route’s perm has no form
yet.
What a save changes#
Only what was edited. The editor reads each file with
ruamel.yaml’s round-trip mode and edits it
in place, so comments, key order, quoting and the file’s indentation are kept.
A string that YAML would read as something else, such as yes or 5, is
written quoted.
There are two limits:
Irregular indentation is normalized. In a file indented by different amounts in different places, the first save re-indents the whole file consistently.
Moving an entry leaves the comment above it behind. The comment on the line above a moved field stays where it was.