From 5f0d7d2392185febef51b844d7899919c827234c Mon Sep 17 00:00:00 2001 From: jamesread Date: Wed, 8 Jul 2026 21:46:14 +0100 Subject: [PATCH] docs: Extra entities fields --- docs/modules/ROOT/nav.adoc | 2 + docs/modules/ROOT/pages/entities/icons.adoc | 115 +++++++++++++++++ docs/modules/ROOT/pages/entities/intro.adoc | 12 +- .../ROOT/pages/entities/properties.adoc | 120 ++++++++++++++++++ 4 files changed, 248 insertions(+), 1 deletion(-) create mode 100644 docs/modules/ROOT/pages/entities/icons.adoc create mode 100644 docs/modules/ROOT/pages/entities/properties.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index ac12883..9e6d7da 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -98,6 +98,8 @@ ** xref:logs/queue.adoc[Queue view] ** xref:logs/saving.adoc[Saving logs] * xref:entities/intro.adoc[Entities] +** xref:entities/properties.adoc[Entity Properties] +** xref:entities/icons.adoc[Entity Icons] ** xref:entities/examples.adoc[Examples] ** xref:entities/yaml.adoc[YAML Entity Files] ** xref:entities/json.adoc[JSON Entity Files] diff --git a/docs/modules/ROOT/pages/entities/icons.adoc b/docs/modules/ROOT/pages/entities/icons.adoc new file mode 100644 index 0000000..2a1635d --- /dev/null +++ b/docs/modules/ROOT/pages/entities/icons.adoc @@ -0,0 +1,115 @@ +[#entity-icons] += Entity icons + +The `icon` field is configured on each entity definition in `config.yaml`. It sets an icon for the entity *type* (for example, all `server` instances share the same icon). + +Entity icons use the same icon system as actions. See xref:action_customization/icons.adoc[Icons] for the full range of supported formats — Unicode aliases, HTML entities, Iconify, image paths, and custom-webui assets. + +== Configuration + +Add `icon` under an entity definition alongside `file`, `name`, and `properties`: + +[source,yaml] +---- +entities: + - file: /etc/OliveTin/servers.yaml + name: server + icon: ssh + properties: + - name: hostname + title: Hostname + + - file: /etc/OliveTin/containers.json + name: container + icon: +---- + +If `icon` is omitted or empty, no icon is shown for that entity type. Unlike actions, entity types do not get a default icon. + +=== Short-name aliases + +OliveTin resolves a few common short names to Unicode HTML entities at config load time. These are convenient for entity types that match common action categories: + +[cols="1,1", options="header"] +|=== +| Alias | Typical use + +| `ssh` +| Servers accessed over SSH + +| `ping` +| Network hosts + +| `box` +| Containers or packages + +| `backup` +| Backup targets + +| `restart` / `reboot` +| Systems or services + +| `light` +| Lights or switches + +| `robot` +| Automation targets +|=== + +The full alias list is in the xref:action_customization/icons.adoc#icons[Icons] documentation and in the source file `service/internal/config/emoji.go`. + +=== Custom-webui image paths + +A path containing `/` (that does not start with `<`) is expanded to an `` tag pointing at `/custom-webui/`. For example, `icons/server.png` becomes an image served from `/custom-webui/icons/server.png`. + +== Where icons appear + +Entity icons are shown in the web UI next to the entity type name, not next to individual instances. + +=== Entities page + +On the Entities page, each entity type section heading shows the configured icon beside the type name (for example, `Entity: server`). + +=== Entity details page + +When viewing a single entity instance, the icon appears in the page title beside the instance name. The icon comes from the entity type definition, not from fields in the entity data file. + +=== API + +The `icon` field is included on: + +* `EntityDefinition` — returned by `GetEntities` for each entity type +* `Entity` — returned by `GetEntity` for a single instance (same type-level icon) + +== What entity icons do not affect + +* **Individual instances** — icons are per entity type in `config.yaml`, not per row in the entity data file. You cannot give `server1` a different icon from `server2` through entity configuration alone. +* **Dashboards** — entity fieldsets and directories use their own `icon` fields on dashboard components. See xref:dashboards/intro.adoc[Dashboards]. +* **Action buttons** — actions have their own `icon` field. An entity-bound action does not inherit the entity type icon automatically. + +== Example + +[source,yaml] +---- +entities: + - file: entities/servers.yaml + name: server + icon: ssh + properties: + - name: hostname + title: Hostname + - name: ip + title: IP + + - file: entities/containers.json + name: container + icon: box +---- + +With this configuration, the Entities page shows a key icon beside the `server` section and a box icon beside the `container` section. Opening any server instance shows the same key icon in the details page title. + +== What's next? + +* xref:action_customization/icons.adoc[Icons] — full icon format reference (Iconify, Unicode, images, and offline hosting) +* xref:entities/intro.adoc[Entities] — overview of entities in OliveTin +* xref:entities/properties.adoc[Entity properties] — configure which fields appear in the entity list diff --git a/docs/modules/ROOT/pages/entities/intro.adoc b/docs/modules/ROOT/pages/entities/intro.adoc index 401a2a2..42cd355 100644 --- a/docs/modules/ROOT/pages/entities/intro.adoc +++ b/docs/modules/ROOT/pages/entities/intro.adoc @@ -9,7 +9,9 @@ A very popular use case that entities were designed for was for `container` enti Entities are just loaded from files on disk, OliveTin will also watch these files for updates while OliveTin is running, and update entities. -Entities can have properties defined in those files, and those can be used in your configuration as variables. For example; `container.status`, or `vm.hostname`. +Entity data files can contain any fields you need. Those values are available in action templates as `{{ .CurrentEntity.field }}` — for example, `{{ .CurrentEntity.status }}` or `{{ .CurrentEntity.hostname }}`. + +To control which fields appear in the Entities page table and entity details view, configure `properties` on the entity definition in `config.yaml`. See xref:entities/properties.adoc[Entity properties] for details. [source,yaml] ---- @@ -19,6 +21,12 @@ entities: - file: /etc/OliveTin/servers.yaml name: server + icon: ssh + properties: + - name: hostname + title: Hostname + - name: ip + title: IP ---- Entity Actions can only be used on xref:dashboards/intro.adoc[Dashboards]. @@ -27,6 +35,8 @@ Entity Actions can only be used on xref:dashboards/intro.adoc[Dashboards]. Now that you understand entities, here's how to use them effectively: +* xref:entities/properties.adoc[Configure entity properties] - Choose which fields appear in the UI and API +* xref:entities/icons.adoc[Configure entity icons] - Set an icon for each entity type * xref:entities/yaml.adoc[Create YAML entity files] - Learn the YAML format for entity files * xref:entities/json.adoc[Create JSON entity files] - Learn the JSON format for entity files * xref:entities/examples.adoc[View entity examples] - See complete examples of entity configurations diff --git a/docs/modules/ROOT/pages/entities/properties.adoc b/docs/modules/ROOT/pages/entities/properties.adoc new file mode 100644 index 0000000..4f89c4d --- /dev/null +++ b/docs/modules/ROOT/pages/entities/properties.adoc @@ -0,0 +1,120 @@ +[#entity-properties] += Entity properties + +The `properties` field is configured on each entity definition in `config.yaml`. It does not live in the entity data files themselves. + +Use it to choose which fields from your entity data files are shown in the web UI and API. Property *values* come from the entity file on disk; `properties` only controls which of those values OliveTin exposes when listing or viewing entities. + +== Configuration + +Add `properties` under an entity definition alongside `file`, `name`, and `icon`: + +[source,yaml] +---- +entities: + - file: /etc/OliveTin/servers.yaml + name: server + icon: ssh + properties: + - name: hostname + title: Hostname + - name: ip + title: IP +---- + +Each entry has two fields: + +[cols="1,3", options="header"] +|=== +| Field | Description + +| `name` +| The key to read from each entity instance in the data file. Matching is case-insensitive. + +| `title` +| The column heading shown in the entity list table. If omitted, OliveTin uses `name`. +|=== + +The entity data file supplies the values. For example, with the configuration above and this data file: + +[source,yaml] +.`/etc/OliveTin/servers.yaml` +---- +- name: server1 + hostname: server1.example.com + ip: 192.168.0.1 +- name: server2 + hostname: server2.example.com + ip: 192.168.0.2 +---- + +OliveTin shows `server1` and `server2` as instance names (from the `name` field) and displays `hostname` and `ip` in the configured columns. + +== Effects + +=== Entity list in the web UI + +When `properties` is configured, the Entities page shows a searchable, paginated table for that entity type. Columns are: + +* **Name** — the instance title (derived from fields such as `name`, `title`, `hostname`, and so on) +* One column per configured property, labelled with `title` + +When `properties` is omitted or empty, the Entities page shows a simple list of instance names and a total count instead of a table. + +=== Entity details page + +The entity details view shows only the fields listed in `properties`, plus type and title. + +If `properties` is not configured, all top-level fields from the entity data file are shown. + +=== API responses + +`properties` controls which fields appear in `fields` on entity instances returned by the API: + +* `GetEntity` — returns only configured property values in `fields` when `properties` is set; otherwise returns all top-level fields from the data file. +* `GetEntities` — always includes the property definitions on `EntityDefinition`. When `properties` is set, instance rows in list responses include only those configured fields. The unfiltered list request omits instance rows (it returns `totalInstances` only); use a filtered request with `entityType` to fetch paginated instances for the table view. + +Search and pagination on the entity list operate over instance titles and the configured property values. + +=== What `properties` does not affect + +`properties` is a display and API filtering setting. It does **not** limit what you can use in action templates. + +Actions bound to an entity still have access to the full entity record through `{{ .CurrentEntity.field }}`, including fields you did not list under `properties`. See xref:args/templates.adoc[Templates in actions] and xref:action_customization/enabledExpression.adoc[Enabled Expression]. + +Legacy template syntax such as `{{ server.hostname }}` is still migrated automatically to `{{ .CurrentEntity.hostname }}`. + +== Example + +This configuration pairs with the server data file shown above: + +[source,yaml] +---- +entities: + - file: entities/servers.yaml + name: server + icon: ssh + properties: + - name: hostname + title: Hostname + - name: ip + title: IP +---- + +An action can still reference any field from the data file, even ones not listed in `properties`: + +[source,yaml] +---- +actions: + - title: Wake server + shell: wakeonlan {{ .CurrentEntity.ip }} + entity: server +---- + +== What's next? + +* xref:entities/yaml.adoc[YAML entity files] — format for entity data files +* xref:entities/json.adoc[JSON entity files] — line-delimited JSON entity files +* xref:entities/icons.adoc[Entity icons] — configure an icon for each entity type +* xref:entities/intro.adoc[Entities] — overview of entities in OliveTin +* xref:dashboards/entity-directories.adoc[Entity directories] — generate per-entity dashboards