Skip to content

Commit 41647ca

Browse files
mtojekmtojek
authored
docs: describe resource ordering in UI (#12185)
1 parent df29762 commit 41647ca

File tree

2 files changed

+188
-5
lines changed

2 files changed

+188
-5
lines changed

‎docs/manifest.json

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,11 @@
177177
"title": "Resource metadata",
178178
"description": "Show information in the workspace about template resources",
179179
"path": "./templates/resource-metadata.md"
180+
},
181+
{
182+
"title": "UI Resource Ordering",
183+
"description": "Learn how to manage the order of Terraform resources in UI",
184+
"path": "./templates/resource-ordering.md"
180185
}
181186
]
182187
},
@@ -236,11 +241,6 @@
236241
"path": "./templates/process-logging.md",
237242
"state": "enterprise"
238243
},
239-
{
240-
"title": "Workspace Scheduling",
241-
"description": "Set workspace scheduling policies",
242-
"path": "./templates/schedule.md"
243-
},
244244
{
245245
"title": "Icons",
246246
"description": "Coder includes icons for popular cloud providers and programming languages for you to use",

‎docs/templates/resource-ordering.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# UI Resource Ordering
2+
3+
In Coder templates, managing the order of UI elements is crucial for a seamless
4+
user experience. This page outlines how resources can be aligned using the
5+
`order` Terraform property or inherit the natural order from the file.
6+
7+
The resource with the lower `order` is presented before the one with greater
8+
value. A missing `order` property defaults to 0. If two resources have the same
9+
`order` property, the resources will be ordered by property `name` (or `key`).
10+
11+
## Using `order` property
12+
13+
### Coder parameters
14+
15+
The `order` property of `coder_parameter` resource allows specifying the order
16+
of parameters in UI forms. In the below example, `project_id` will appear
17+
_before_ `account_id`:
18+
19+
```hcl
20+
data "coder_parameter" "project_id" {
21+
name = "project_id"
22+
display_name = "Project ID"
23+
description = "Specify cloud provider project ID."
24+
order = 2
25+
}
26+
27+
data "coder_parameter" "account_id" {
28+
name = "account_id"
29+
display_name = "Account ID"
30+
description = "Specify cloud provider account ID."
31+
order = 1
32+
}
33+
```
34+
35+
### Agents
36+
37+
Agent resources within the UI left pane are sorted based on the `order`
38+
property, followed by `name`, ensuring a consistent and intuitive arrangement.
39+
40+
```hcl
41+
resource "coder_agent" "primary" {
42+
...
43+
44+
order = 1
45+
}
46+
47+
resource "coder_agent" "secondary" {
48+
...
49+
50+
order = 2
51+
}
52+
```
53+
54+
The agent with the lowest order is presented at the top in the workspace view.
55+
56+
### Agent metadata
57+
58+
The `coder_agent` exposes metadata to present operational metrics in the UI.
59+
Metrics defined with Terraform `metadata` blocks can be ordered using additional
60+
`order` property; otherwise, they are sorted by `key`.
61+
62+
```hcl
63+
resource "coder_agent" "main" {
64+
...
65+
66+
metadata {
67+
display_name = "CPU Usage"
68+
key = "cpu_usage"
69+
script = "coder stat cpu"
70+
interval = 10
71+
timeout = 1
72+
order = 1
73+
}
74+
metadata {
75+
display_name = "CPU Usage (Host)"
76+
key = "cpu_usage_host"
77+
script = "coder stat cpu --host"
78+
interval = 10
79+
timeout = 1
80+
order = 2
81+
}
82+
metadata {
83+
display_name = "RAM Usage"
84+
key = "ram_usage"
85+
script = "coder stat mem"
86+
interval = 10
87+
timeout = 1
88+
order = 1
89+
}
90+
metadata {
91+
display_name = "RAM Usage (Host)"
92+
key = "ram_usage_host"
93+
script = "coder stat mem --host"
94+
interval = 10
95+
timeout = 1
96+
order = 2
97+
}
98+
}
99+
```
100+
101+
### Applications
102+
103+
Similarly to Coder agents, `coder_app` resources incorporate the `order`
104+
property to organize button apps in the app bar within a `coder_agent` in the
105+
workspace view.
106+
107+
Only template defined applications can be arranged. _VS Code_ or _Terminal_
108+
buttons are static.
109+
110+
```hcl
111+
resource "coder_app" "code-server" {
112+
agent_id = coder_agent.main.id
113+
slug = "code-server"
114+
display_name = "code-server"
115+
...
116+
117+
order = 2
118+
}
119+
120+
resource "coder_app" "filebrowser" {
121+
agent_id = coder_agent.main.id
122+
display_name = "File Browser"
123+
slug = "filebrowser"
124+
...
125+
126+
order = 1
127+
}
128+
```
129+
130+
## Inherit order from file
131+
132+
### Coder parameter options
133+
134+
The options for Coder parameters maintain the same order as in the file
135+
structure. This simplifies management and ensures consistency between
136+
configuration files and UI presentation.
137+
138+
```hcl
139+
data "coder_parameter" "database_region" {
140+
name = "database_region"
141+
display_name = "Database Region"
142+
143+
icon = "/icon/database.svg"
144+
description = "These are options."
145+
mutable = true
146+
default = "us-east1-a"
147+
148+
// The order of options is stable and inherited from .tf file.
149+
option {
150+
name = "US Central"
151+
description = "Select for central!"
152+
value = "us-central1-a"
153+
}
154+
option {
155+
name = "US East"
156+
description = "Select for east!"
157+
value = "us-east1-a"
158+
}
159+
...
160+
}
161+
```
162+
163+
### Coder metadata items
164+
165+
In cases where multiple item properties exist, the order is inherited from the
166+
file, facilitating seamless integration between a Coder template and UI
167+
presentation.
168+
169+
```hcl
170+
resource "coder_metadata" "attached_volumes" {
171+
resource_id = docker_image.main.id
172+
173+
// Items will be presented in the UI in the following order.
174+
item {
175+
key = "disk-a"
176+
value = "60 GiB"
177+
}
178+
item {
179+
key = "disk-b"
180+
value = "128 GiB"
181+
}
182+
}
183+
```

0 commit comments

Comments
 (0)