docs: Extra entities fields
This commit is contained in:
jamesread
parent
8eda67a39e
commit
5f0d7d2392
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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: <iconify-icon icon="logos:docker-icon"></iconify-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 `<img>` tag pointing at `/custom-webui/`. For example, `icons/server.png` becomes an image served from `<config-dir>/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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue