Editing a model in the browser

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 model would load it, with the nearest model.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.