From 3e7a142d8692ddb6d029c86c28a573866d9ea045 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 16 Feb 2024 11:31:45 +0100 Subject: [PATCH 1/5] Stub for docs --- docs/manifest.json | 10 +++++----- docs/templates/resource-ordering.md | 1 + 2 files changed, 6 insertions(+), 5 deletions(-) create mode 100644 docs/templates/resource-ordering.md diff --git a/docs/manifest.json b/docs/manifest.json index 12a5e3cfcca91..12b5d9890ffc5 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -177,6 +177,11 @@ "title": "Resource metadata", "description": "Show information in the workspace about template resources", "path": "./templates/resource-metadata.md" + }, + { + "title": "UI Resource Ordering", + "description": "Learn how to manage the order of Terraform resources in UI", + "path": "./templates/resource-ordering.md" } ] }, @@ -236,11 +241,6 @@ "path": "./templates/process-logging.md", "state": "enterprise" }, - { - "title": "Workspace Scheduling", - "description": "Set workspace scheduling policies", - "path": "./templates/schedule.md" - }, { "title": "Icons", "description": "Coder includes icons for popular cloud providers and programming languages for you to use", diff --git a/docs/templates/resource-ordering.md b/docs/templates/resource-ordering.md new file mode 100644 index 0000000000000..c0481352e7850 --- /dev/null +++ b/docs/templates/resource-ordering.md @@ -0,0 +1 @@ +# UI Resource Ordering From d6033b7164681d71c207d699a1547ed331723550 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 16 Feb 2024 12:48:09 +0100 Subject: [PATCH 2/5] Content --- docs/templates/resource-ordering.md | 180 ++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) diff --git a/docs/templates/resource-ordering.md b/docs/templates/resource-ordering.md index c0481352e7850..a5c2d89fe3e67 100644 --- a/docs/templates/resource-ordering.md +++ b/docs/templates/resource-ordering.md @@ -1 +1,181 @@ # UI Resource Ordering + +In Coder templates, managing the order of UI elements is crucial for a seamless +user experience. This page outlines how resources can be aligned using the +`order` Terraform property or inherit the natural order from the file. + +The resource with the lower `order` is presented before the one with greater +value. A missing `order` property defaults to 0. + +## Using `order` property + +### Coder parameters + +The `coder_parameter` resource allows specifying the order of parameters in UI +forms using the `order` property. For example: + +```hcl +resource "coder_parameter" "project_id" { + name = "project_id" + display_name = "Project ID" + description = "Specify cloud provider project ID." + order = 2 +} + +resource "coder_parameter" "account_id" { + name = "account_id" + display_name = "Account ID" + description = "Specify cloud provider account ID." + order = 1 +} +``` + +### Agents + +Agent resources within the UI left pane are sorted based on the `order` +property, followed by `name`, ensuring a consistent and intuitive arrangement. + +```hcl +resource "coder_agent" "primary" { + ... + + order = 1 +} + +resource "coder_agent" "secondary" { + ... + + order = 2 +} +``` + +The agent with the lowest order is presented as the main agent in the workspace +view. + +### Agent metadata + +The `coder_agent` exposes metadata to present operational metrics in the UI. +Metrics defined with Terraform `metadata` blocks can be ordered using additional +`order` property; otherwise, they are sorted by `key`. + +```hcl +resource "coder_agent" "main" { + ... + + metadata { + display_name = "CPU Usage" + key = "cpu_usage" + script = "coder stat cpu" + interval = 10 + timeout = 1 + order = 1 + } + metadata { + display_name = "CPU Usage (Host)" + key = "cpu_usage_host" + script = "coder stat cpu --host" + interval = 10 + timeout = 1 + order = 2 + } + metadata { + display_name = "RAM Usage" + key = "ram_usage" + script = "coder stat mem" + interval = 10 + timeout = 1 + order = 1 + } + metadata { + display_name = "RAM Usage (Host)" + key = "ram_usage_host" + script = "coder stat mem --host" + interval = 10 + timeout = 1 + order = 2 + } +} +``` + +### Applications + +Similarly to Cocer agents, `coder_app` resources incorporate the `order` +property to organize button apps in the app bar within the workspace view. + +Only template defined applications can be arranged. _VS Code_ or _Terminal_ +buttons are static. + +```hcl +resource "coder_app" "code-server" { + agent_id = coder_agent.main.id + slug = "code-server" + display_name = "code-server" + ... + + order = 2 +} + +resource "coder_app" "filebrowser" { + agent_id = coder_agent.main.id + display_name = "File Browser" + slug = "filebrowser" + ... + + order = 1 +} +``` + +## Inherit order from file + +### Coder parameter options + +The options for Coder parameters maintain the same order as in the file +structure. This simplifies management and ensures consistency between +configuration files and UI presentation. + +```hcl +data "coder_parameter" "databse_region" { + name = "database_region" + display_name = "Database Region" + + icon = "/icon/database.svg" + description = "These are options." + mutable = true + default = "us-east1-a" + + // The order of options is stable and inherited from .tf file. + option { + name = "US Central" + description = "Select for central!" + value = "us-central1-a" + } + option { + name = "US East" + description = "Select for east!" + value = "us-east1-a" + } + ... +} +``` + +### Agent metadata items + +In cases where multiple item properties exist, the order is inherited from the +file, facilitating seamless integration between a Coder template and UI +presentation. + +```hcl +resource "coder_metadata" "attached_volumes" { + resource_id = docker_image.main.id + + // Items will be presented in the UI in the following order. + item { + key = "disk-a" + value = "60 GiB" + } + item { + key = "disk-b" + value = "128 GiB" + } +} +``` From 0e804f8dfedc99052159190877529b687f4c38c4 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 16 Feb 2024 12:51:46 +0100 Subject: [PATCH 3/5] fix: lint --- docs/templates/resource-ordering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/templates/resource-ordering.md b/docs/templates/resource-ordering.md index a5c2d89fe3e67..75a3cf97656b9 100644 --- a/docs/templates/resource-ordering.md +++ b/docs/templates/resource-ordering.md @@ -134,7 +134,7 @@ structure. This simplifies management and ensures consistency between configuration files and UI presentation. ```hcl -data "coder_parameter" "databse_region" { +data "coder_parameter" "database_region" { name = "database_region" display_name = "Database Region" From fe6cecccd841dd8df0b82a5693db46e7692fca9d Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 16 Feb 2024 13:06:07 +0100 Subject: [PATCH 4/5] Atif's proofreading --- docs/templates/resource-ordering.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/templates/resource-ordering.md b/docs/templates/resource-ordering.md index 75a3cf97656b9..f4b359cf8fc54 100644 --- a/docs/templates/resource-ordering.md +++ b/docs/templates/resource-ordering.md @@ -11,18 +11,18 @@ value. A missing `order` property defaults to 0. ### Coder parameters -The `coder_parameter` resource allows specifying the order of parameters in UI -forms using the `order` property. For example: +The `order` property of `coder_parameter` resource allows specifying the order +of parameters in UI forms. For example: ```hcl -resource "coder_parameter" "project_id" { +data "coder_parameter" "project_id" { name = "project_id" display_name = "Project ID" description = "Specify cloud provider project ID." order = 2 } -resource "coder_parameter" "account_id" { +data "coder_parameter" "account_id" { name = "account_id" display_name = "Account ID" description = "Specify cloud provider account ID." @@ -49,8 +49,7 @@ resource "coder_agent" "secondary" { } ``` -The agent with the lowest order is presented as the main agent in the workspace -view. +The agent with the lowest order is presented at the top in the workspace view. ### Agent metadata @@ -99,8 +98,9 @@ resource "coder_agent" "main" { ### Applications -Similarly to Cocer agents, `coder_app` resources incorporate the `order` -property to organize button apps in the app bar within the workspace view. +Similarly to Coder agents, `coder_app` resources incorporate the `order` +property to organize button apps in the app bar within a `coder_agent` in the +workspace view. Only template defined applications can be arranged. _VS Code_ or _Terminal_ buttons are static. @@ -158,7 +158,7 @@ data "coder_parameter" "database_region" { } ``` -### Agent metadata items +### Coder metadata items In cases where multiple item properties exist, the order is inherited from the file, facilitating seamless integration between a Coder template and UI From 6981b835c25198e8b04991295eaf7c83c1b86f5f Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 16 Feb 2024 13:14:05 +0100 Subject: [PATCH 5/5] Cian's review --- docs/templates/resource-ordering.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/templates/resource-ordering.md b/docs/templates/resource-ordering.md index f4b359cf8fc54..5626dcdf4073d 100644 --- a/docs/templates/resource-ordering.md +++ b/docs/templates/resource-ordering.md @@ -5,14 +5,16 @@ user experience. This page outlines how resources can be aligned using the `order` Terraform property or inherit the natural order from the file. The resource with the lower `order` is presented before the one with greater -value. A missing `order` property defaults to 0. +value. A missing `order` property defaults to 0. If two resources have the same +`order` property, the resources will be ordered by property `name` (or `key`). ## Using `order` property ### Coder parameters The `order` property of `coder_parameter` resource allows specifying the order -of parameters in UI forms. For example: +of parameters in UI forms. In the below example, `project_id` will appear +_before_ `account_id`: ```hcl data "coder_parameter" "project_id" {