Skip to content

Commit ba015d2

Browse files
cdr-robotclaude
cdr-robot
and
claude
committed
docs: add documentation and examples for list(string) parameters
This commit addresses issue #17 with: 1. New detailed documentation on list(string) parameters usage and styling 2. A complete example template showcasing different UI styling options 3. Example code for dynamically generated options, form types, and best practices 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent aacb11d commit ba015d2

4 files changed

Lines changed: 755 additions & 0 deletions

File tree

‎docs/admin/templates/extending-templates/list-string-parameters.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# Working with list(string) Parameters
2+
3+
This guide explores the usage of `list(string)` parameters in Coder templates, providing examples and best practices for their implementation.
4+
5+
## Introduction to list(string) Parameters
6+
7+
The `list(string)` parameter type allows users to select multiple string values from a predefined set of options. This is useful for scenarios where multiple selections are needed, such as:
8+
9+
- Selecting multiple security groups
10+
- Choosing programming languages or tools
11+
- Applying tags to resources
12+
- Selecting features to enable
13+
14+
## Basic Usage
15+
16+
To define a basic `list(string)` parameter:
17+
18+
```tf
19+
data "coder_parameter" "security_groups" {
20+
name = "security_groups"
21+
display_name = "Security Groups"
22+
description = "Select security groups to apply to your workspace"
23+
type = "list(string)"
24+
default = jsonencode(["default-sg", "ssh-sg"])
25+
mutable = true
26+
}
27+
```
28+
29+
Key points:
30+
- Use the `jsonencode()` function to specify default values
31+
- The default values must be a JSON array of strings
32+
- Users can select zero, one, or multiple values
33+
34+
## UI Rendering Options
35+
36+
### Form Types
37+
38+
Coder supports two main form types for `list(string)` parameters:
39+
40+
#### 1. Multi-select (default)
41+
42+
The standard multi-select dropdown:
43+
44+
```tf
45+
data "coder_parameter" "languages" {
46+
name = "languages"
47+
display_name = "Programming Languages"
48+
description = "Select languages you'll work with"
49+
type = "list(string)"
50+
default = jsonencode(["python", "javascript"])
51+
form_type = "multi-select" # This is the default
52+
}
53+
```
54+
55+
#### 2. Tag-select
56+
57+
A more tag-focused interface, useful for parameters representing tags or labels:
58+
59+
```tf
60+
data "coder_parameter" "tags" {
61+
name = "tags"
62+
display_name = "Resource Tags"
63+
description = "Tags to apply to your workspace resources"
64+
type = "list(string)"
65+
default = jsonencode(["development", "testing"])
66+
form_type = "tag-select"
67+
}
68+
```
69+
70+
### Adding Icons and Descriptions
71+
72+
You can enhance the UI by adding icons and descriptions to both the parameter and individual options:
73+
74+
```tf
75+
data "coder_parameter" "environments" {
76+
name = "environments"
77+
display_name = "Deployment Environments"
78+
description = "Select which environments this workspace can deploy to"
79+
type = "list(string)"
80+
default = jsonencode(["dev"])
81+
icon = "/emojis/1f30e.png"
82+
83+
option {
84+
name = "Development"
85+
value = "dev"
86+
icon = "/emojis/1f3ed.png"
87+
description = "Development environment with debugging tools"
88+
}
89+
90+
option {
91+
name = "Production"
92+
value = "prod"
93+
icon = "/emojis/1f6eb.png"
94+
description = "Production-grade environment"
95+
}
96+
}
97+
```
98+
99+
## Working with Selected Values
100+
101+
To use the selected values in your template:
102+
103+
```tf
104+
resource "aws_instance" "workspace" {
105+
// Other configuration...
106+
107+
// Use jsondecode() to convert the JSON string back to a list
108+
security_groups = jsondecode(data.coder_parameter.security_groups.value)
109+
}
110+
```
111+
112+
For displaying in metadata:
113+
114+
```tf
115+
resource "coder_metadata" "workspace_info" {
116+
resource_id = aws_instance.workspace.id
117+
118+
item {
119+
key = "Environments"
120+
value = join(", ", jsondecode(data.coder_parameter.environments.value))
121+
}
122+
}
123+
```
124+
125+
## Dynamic Options
126+
127+
You can dynamically generate options for a `list(string)` parameter:
128+
129+
```tf
130+
locals {
131+
available_regions = {
132+
"us-east-1" = {
133+
name = "US East (N. Virginia)",
134+
icon = "/emojis/1f1fa-1f1f8.png"
135+
},
136+
"eu-west-1" = {
137+
name = "EU West (Ireland)",
138+
icon = "/emojis/1f1ea-1f1fa.png"
139+
}
140+
// Additional regions...
141+
}
142+
}
143+
144+
data "coder_parameter" "regions" {
145+
name = "regions"
146+
display_name = "AWS Regions"
147+
description = "Select AWS regions to deploy to"
148+
type = "list(string)"
149+
default = jsonencode(["us-east-1"])
150+
151+
dynamic "option" {
152+
for_each = local.available_regions
153+
content {
154+
name = option.value.name
155+
value = option.key
156+
icon = option.value.icon
157+
}
158+
}
159+
}
160+
```
161+
162+
## Empty Defaults
163+
164+
To create a parameter with no default selections:
165+
166+
```tf
167+
data "coder_parameter" "features" {
168+
name = "features"
169+
display_name = "Optional Features"
170+
description = "Select optional features to enable"
171+
type = "list(string)"
172+
default = jsonencode([]) // Empty array means no default selection
173+
}
174+
```
175+
176+
## Ephemeral List Parameters
177+
178+
For operations that should only apply during workspace creation or updates:
179+
180+
```tf
181+
data "coder_parameter" "startup_tasks" {
182+
name = "startup_tasks"
183+
display_name = "Startup Tasks"
184+
description = "Tasks to run during workspace startup"
185+
type = "list(string)"
186+
default = jsonencode(["update_packages"])
187+
ephemeral = true
188+
189+
option {
190+
name = "Update Packages"
191+
value = "update_packages"
192+
}
193+
option {
194+
name = "Run Migrations"
195+
value = "run_migrations"
196+
}
197+
}
198+
```
199+
200+
## Command Line Usage
201+
202+
Using `list(string)` parameters on the command line requires careful quoting:
203+
204+
```bash
205+
coder create --parameter "\"security_groups=[\"\"web-sg\"\",\"\"db-sg\"\"]\""
206+
```
207+
208+
Alternatively, use a parameter file for a cleaner approach:
209+
210+
```yaml
211+
# params.yaml
212+
security_groups:
213+
- web-sg
214+
- db-sg
215+
```
216+
217+
```bash
218+
coder create --rich-parameter-file params.yaml
219+
```
220+
221+
## Best Practices
222+
223+
1. **Provide Clear Descriptions**: Ensure each option has a clear description
224+
2. **Use Appropriate Icons**: Visual cues help users quickly identify options
225+
3. **Group Related Parameters**: Keep related parameters together using the `order` attribute
226+
4. **Consider Default Selections**: Choose sensible defaults to minimize user effort
227+
5. **Use Form Types Appropriately**: Use `tag-select` for tags, `multi-select` for other selections
228+
6. **Limit Option Count**: Avoid overwhelming users with too many options
229+
7. **Use Dynamic Options**: Generate options programmatically when the list might change
230+
231+
## Full Example
232+
233+
See the [list-string-parameters example template](https://github.com/coder/coder/tree/main/examples/parameters-list-string) for a complete implementation showcasing various styling and configuration options.
234+
235+
```tf
236+
data "coder_parameter" "environments" {
237+
name = "environments"
238+
display_name = "Deployment Environments"
239+
description = "Select which environments this workspace can deploy to"
240+
type = "list(string)"
241+
default = jsonencode(["dev"])
242+
mutable = true
243+
icon = "/emojis/1f30e.png"
244+
form_type = "multi-select"
245+
246+
option {
247+
name = "Development"
248+
value = "dev"
249+
icon = "/emojis/1f3ed.png"
250+
description = "Development environment with debugging tools"
251+
}
252+
253+
option {
254+
name = "Staging"
255+
value = "staging"
256+
icon = "/emojis/1f6a7.png"
257+
description = "Pre-production environment for testing"
258+
}
259+
260+
option {
261+
name = "Production"
262+
value = "prod"
263+
icon = "/emojis/1f6eb.png"
264+
description = "Production-grade environment"
265+
}
266+
}
267+
```

‎examples/parameters-list-string/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# List(string) Parameter Examples
2+
3+
This template demonstrates various styling and usage patterns for `list(string)` parameters in Coder templates.
4+
5+
## Examples Included
6+
7+
1. **Basic list(string) parameter** - A simple multi-select with default values
8+
2. **Tag-select form type** - Uses the tag-select UI style for a more tag-focused interface
9+
3. **Multi-select form type** - Explicitly sets the multi-select form type with custom icons per option
10+
4. **Custom icons with no defaults** - Shows how to create a parameter with no default selections
11+
5. **Many options** - Demonstrates how the UI handles a larger number of options
12+
6. **Ephemeral parameters** - For operations that only need to apply during startup/update
13+
7. **Dynamically generated options** - Shows how to generate options using Terraform locals
14+
15+
## Usage
16+
17+
This template is designed to work with Docker. To use it:
18+
19+
1. Create a new template in Coder pointing to this directory
20+
2. Create a new workspace using the template
21+
3. Experiment with the different parameter types
22+
23+
## Working with list(string) Values
24+
25+
The examples also show how to:
26+
27+
- Set default values using `jsonencode()`
28+
- Access selected values using `jsondecode()`
29+
- Display values in workspace metadata
30+
- Generate dynamic options
31+
32+
## Command Line Usage
33+
34+
When using `list(string)` parameters on the command line, you need to be careful with quoting:
35+
36+
```bash
37+
coder create --parameter "\"security_groups=[\"\"web-sg\"\",\"\"db-sg\"\"]\""
38+
```
39+
40+
Alternatively, use a parameter file for a cleaner approach:
41+
42+
```yaml
43+
# params.yaml
44+
security_groups:
45+
- web-sg
46+
- db-sg
47+
```
48+
49+
```bash
50+
coder create --rich-parameter-file params.yaml
51+
```
52+
53+
## Parameter UI Rendering
54+
55+
The multi-select control in Coder renders differently based on:
56+
57+
- The number of options (scrollable when many options exist)
58+
- Whether `form_type` is set to `multi-select` or `tag-select`
59+
- Whether icons are provided for options
60+
- The presence of descriptions for each option

‎examples/parameters-list-string/build/Dockerfile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
FROM ubuntu:jammy
2+
3+
ARG USER=coder
4+
5+
RUN apt-get update && apt-get install -y \
6+
curl \
7+
git \
8+
jq \
9+
sudo \
10+
vim \
11+
wget
12+
13+
# Add a user `coder` with sudo access
14+
RUN useradd --groups sudo --shell /bin/bash ${USER} \
15+
&& echo "${USER} ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/${USER} \
16+
&& chmod 0440 /etc/sudoers.d/${USER}
17+
18+
USER ${USER}
19+
WORKDIR /home/${USER}

0 commit comments

Comments
 (0)