mirror of
https://github.com/podman-desktop/podman-desktop
synced 2026-04-21 17:47:22 +00:00
37909ac142
Signed-off-by: Markus Eisele <markus@redhat.com> Co-authored-by: Markus Eisele <markus@redhat.com>
121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
title: When clause contexts
|
|
description: Podman Desktop when clause contexts reference
|
|
tags: [podman-desktop, extension, writing, when clause]
|
|
keywords: [podman desktop, extension, writing, when clause]
|
|
---
|
|
|
|
# When clause contexts
|
|
|
|
Podman Desktop uses when clauses to enable or disable extensions command and UI customizations, such as views.
|
|
|
|
For example, the Kind extension adds a custom icon to a container that has a label equals to `io.x-k8s.kind.cluster` by using the following instruction.
|
|
|
|
```json
|
|
"views": {
|
|
"icons/containersList": [
|
|
{
|
|
"when": "io.x-k8s.kind.cluster in containerLabelKeys",
|
|
"icon": "${kind-icon}"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
A when clause can consist of a context key (such as `isLinux`) or complex expressions to define a specific state.
|
|
|
|
### Available context keys
|
|
|
|
Podman Desktop has a set of context keys that are evaluated to Boolean true/false.
|
|
|
|
| Context key | True when |
|
|
| ----------------------------- | ---------------------------- |
|
|
| **Operating system contexts** | |
|
|
| isLinux | True when the OS is Linux. |
|
|
| isWindows | True when the OS is Windows. |
|
|
| isMac | True when the OS is macOS. |
|
|
|
|
Podman Desktop also provides context keys that return values that can be used to create meaningful expressions
|
|
|
|
| Context key | Value in it |
|
|
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
|
| containerLabelKeys | A list of all labels belonging to the current container. Example: `"value in containerLabelKeys"` |
|
|
| selectedImageId | The image id which the dashboard/image menu opened belong to. Example `"selectedImageId in imagesPushInProgressToKind"` |
|
|
|
|
### Add a custom when clause context
|
|
|
|
If you are creating your own extension and none of the existing keys suit your needs, you can set your own context key by calling the function `setValue(key: string, value: any, scope?: 'onboarding')` provided by the `context` namespace in the Podman Desktop API.
|
|
|
|
The scope, if specified, triggers a custom behavior to avoid any type of collisions between different extensions for that specific scope. Podman Desktop is responsible for handling its state and cleans it accordingly when necessary.
|
|
|
|
If omitted, the key/value is set globally. For this reason it is recommended to use the extension id as part of the key to avoid unexpected collisions with other extensions.
|
|
|
|
The first example below sets the key `"podmanIsInstalled"` to true globally while the second example sets the key `"toolInstalled"` to `oc.exe` using the onboarding scope.
|
|
|
|
```js
|
|
extensionsAPI.context.setValue('podmanIsInstalled', true);
|
|
|
|
extensionsAPI.context.setValue('toolInstalled', 'oc.exe', 'onboarding');
|
|
```
|
|
|
|
After setting the `toolInstalled` to `oc.exe`, you could use this information in the `when` clause to enable something
|
|
|
|
```json
|
|
{
|
|
"when": "onboardingContext:toolInstalled == oc.exe"
|
|
}
|
|
```
|
|
|
|
### Conditional operators
|
|
|
|
To create `when` clauses a bit more complex Podman Desktop offers a set of operators that can be combined with each other.
|
|
|
|
#### Logical operators
|
|
|
|
Logical operators allow combining simple context keys or when-clause expressions that include other operators
|
|
|
|
| Operator | Symbol | Example |
|
|
| -------- | ------ | ----------------------------------------------------------- |
|
|
| Not | `!` | `!podmanIsInstalled` or `!(podmanIsInstalled && isWindows)` |
|
|
| And | `&&` | `podmanIsInstalled && isWindows` |
|
|
| Or | `\|\|` | `isLinux \|\| isWindows` |
|
|
|
|
#### Equality operators
|
|
|
|
Equality operators allow checking for equality of a context key's value against a specified value.
|
|
|
|
**Note:** the right side is a value and not considered as a context key, so no value is searched in the context. If it contains whitespaces, it must be wrapped in single-quotes (for example `'my tool.exe'`)
|
|
|
|
| Operator | Symbol | Example |
|
|
| ---------- | ------ | ------------------------------------------- |
|
|
| Equality | `==` | `onboardingContext:toolInstalled == oc.exe` |
|
|
| Inequality | `!=` | `onboardingContext:toolInstalled != oc.exe` |
|
|
|
|
#### Comparison operators
|
|
|
|
Comparison operator allow comparing a context key's value against a number.
|
|
|
|
**Note:** the left and right side of the operator must be separated by whitespace - `bar < 2`, but not `bar<2`
|
|
|
|
| Operator | Symbol | Example |
|
|
| ------------ | --------- | -------------------------------------- |
|
|
| Greater than | `>`, `>=` | `onboardingContext:toolInstalled > 2` |
|
|
| Less than | `<`, `<=` | `onboardingContext:toolInstalled <= 3` |
|
|
|
|
#### In and not in
|
|
|
|
The `in`/`not in` operators allow checking if a value exists/not exists within the other. The right should be a context key, which value is retrieved in the context. The left can be a value or a context key.
|
|
|
|
| Operator | Symbol | Example |
|
|
| -------- | -------- | --------------------------------- |
|
|
| In | `in` | `label in containerLabelKeys` |
|
|
| Not | `not in` | `label not in containerLabelKeys` |
|
|
|
|
#### Match operator
|
|
|
|
The match operator allow treating the right side item as a regular expression literal to match against the left side.
|
|
|
|
| Operator | Symbol | Example |
|
|
| -------- | ------ | -------------------- |
|
|
| Matches | `=~` | `label =~ /podman$/` |
|