|
| 1 | +--- |
| 2 | +sidebar_position: 6 |
| 3 | +id: "customwidgets" |
| 4 | +title: "Custom Widgets" |
| 5 | +--- |
| 6 | + |
| 7 | +# Custom Widgets |
| 8 | + |
| 9 | +Wave allows users to create their own widgets to uniquely customize their experience for what works for them. While we plan on greatly expanding on this in the future, it is already possible to make terminal/cli widgets that you can access at the press of a button. |
| 10 | + |
| 11 | +# Terminal and CLI Widgets |
| 12 | + |
| 13 | +A terminal widget, or CLI widget, is a widget that simply opens a terminal and runs a CLI command. |
| 14 | +These widgets are managed in the `~/.config/waveterm/widgets.json` file. |
| 15 | + |
| 16 | +## Designing a Widget |
| 17 | + |
| 18 | +Each widget is a key-value pair of a json object where the key is the name of the widget, and the value is an object responsible for configuring the widget. As a whole, it looks like: |
| 19 | +```json |
| 20 | +{ |
| 21 | + <... other widgets go here ...>, |
| 22 | + "<widget name>": { |
| 23 | + "icon": "<fontawesome icon name>", |
| 24 | + "label": "<the text label of the widget>", |
| 25 | + "color": "<the color of the label>", |
| 26 | + "blockdef": { |
| 27 | + "meta": { |
| 28 | + "view": "term", |
| 29 | + "controller": "cmd" |
| 30 | + "cmd": "<the actual cli command>" |
| 31 | + } |
| 32 | + } |
| 33 | + }, |
| 34 | + <... other widgets go here ...> |
| 35 | +} |
| 36 | +``` |
| 37 | +In essence, there are two places that require customization. The first is the outer `WidgetConfigType` which is directly in the object that corresponds with the widget name. In the example above, it contains `"icon"`, `"label"`, and `"color"`. Valid options for this type include: |
| 38 | +| Key | Description | |
| 39 | +|-----|-------------| |
| 40 | +|"display:order"| (optional) Overrides the order of widgets with a number in case you want the widget to be different than the order provided in the `widgets.json` file. Defaults to 0. | |
| 41 | +|"icon"| (optional) The name of a fontawesome icon. Defaults to `"browser"`.| |
| 42 | +|"color"| (optional) A string representing a color as would be used in CSS. Hex codes and custom CSS properties are included. This defaults to `"var(--secondary-text-color)"` which is a color wave uses for text that should be differentiated from other text. Out of the box, it is `"#c3c8c2"`.| |
| 43 | +|"label"| (optional) A string representing the label that appears underneath the widget. It will also act as a tooltip on hover if the `"description"` key isn't filled out. It is null by default.| |
| 44 | +|"description"| (optional) A description of what the widget does. If it is specified, this serves as a tooltip on hover. It is null by default.| |
| 45 | +|"blockdef"| This is where the the non-visual portion of the widget is defined. Note that all further definition takes place inside a meta object inside this one.| |
| 46 | + |
| 47 | + |
| 48 | +The other part to configure is the `MetaTSType` associated with the widget. The topic of the `MetaTSType` is vast and deserves it's own documentation, but here is a subset that is relevant to creating terminal widgets. |
| 49 | +| Key | Description | |
| 50 | +|-----|-------------| |
| 51 | +| "view" | A string that specifies the general type of widget. In the case of custom terminal widgets, this must be set to `"term"`.| |
| 52 | +| "controller" | A string that specifies the type of command being used. For more persistent shell sessions, set it to "shell". For one off commands, set it to "cmd". Note that it is often possible to achieve the same result through each depending on the command being used.| |
| 53 | +| "cmd" | (optional) When the `"controller"` is set to `"cmd"`, this option provides the actual command to be run. Note that because it is run as a command, there is no shell session unless you are launching a command that contains a shell session itself. Defaults to an empty string. | |
| 54 | +| "cmd:interactive" | (optional) When the `"controller"` is set to `"term", this boolean adds the interactive flag to the launched terminal. Defaults to false.| |
| 55 | +| "cmd:login" | (optional) When the `"controller"` is set to `"term"`, this boolean adds the login flag to the term command. Defaults to false.| |
| 56 | +| "cmd:runonstart" | (optional) The command will rerun when the app is started. Without it, you must manually run the command. Defaults to true.| |
| 57 | +| "cmd:clearonstart" | (optional) When the cmd starts, the contents of the block are cleared out. Defaults to false. | |
| 58 | +| "cmd:clearonrestart" | (optional) When the app restarts, the contents of the block are cleared out. Defaults to false. | |
| 59 | +| "cmd:env" | (optional) A key-value object represting environment variables to be run with the command. Currently only works locally. Defaults to an empty object. | |
| 60 | +| "cmd:cwd" | (optional) A string representing the current working directory to be run with the command. Currently only works locally. Defaults to the home directory. | |
| 61 | +| "cmd:nowsh" | (optional) A boolean that will turn off wsh integration for the command. Defaults to false. | |
| 62 | +| "term:localshellpath" | (optional) Sets the shell used for running your widget command. Only works locally. If left blank, wave will determine your system default instead. | |
| 63 | +| "term:localshellopts" | (optional) Sets the shell options meant to be used with `"term:localshellpath"`. This is useful if you are using a nonstandard shell and need to provide a specific option that we do not cover. Only works locally. Defaults to an empty string. | |
| 64 | + |
| 65 | + |
| 66 | + |
| 67 | +## Example Widgets |
| 68 | + |
| 69 | +Here are a few simple widgets to serve as examples. |
| 70 | + |
| 71 | +Suppose I want a widget that will run speedtest-go when opened. Then, I can define a widget as |
| 72 | +```json |
| 73 | +{ |
| 74 | + <... other widgets go here ...>, |
| 75 | + "speedtest" : { |
| 76 | + "icon": "gauge-high", |
| 77 | + "label": "speed", |
| 78 | + "blockdef": { |
| 79 | + "meta": { |
| 80 | + "view": "term", |
| 81 | + "controller": "cmd", |
| 82 | + "cmd": "speedtest-go --unix", |
| 83 | + "cmd:clearonstart" |
| 84 | + } |
| 85 | + } |
| 86 | + }, |
| 87 | + <... other widgets go here ...> |
| 88 | +} |
| 89 | +``` |
| 90 | +Using `"cmd"` for the `"controller"` is the simplest way to accomplish this. `"cmd:clearonstart"` isn't necessary, but it makes it so every time the command is run (which can be done by right clicking the header and selecting `Force Controller Restart`), the previous contents are cleared out. |
| 91 | + |
| 92 | +Now suppose I wanted to run a TUI app, for instance, `dua`. Well, it turns out that you can more or less do the same thing: |
| 93 | +```json |
| 94 | + <... other widgets go here ...>, |
| 95 | + "dua" : { |
| 96 | + "icon": "brands@linux", |
| 97 | + "label": "dua", |
| 98 | + "blockdef": { |
| 99 | + "meta": { |
| 100 | + "view": "term", |
| 101 | + "controller": "cmd", |
| 102 | + "cmd": "dua" |
| 103 | + } |
| 104 | + } |
| 105 | + }, |
| 106 | + <... other widgets go here ...> |
| 107 | +``` |
| 108 | +Because this is a TUI app that does not return anything when closed, the `"cmd:clearonstart"` option doesn't change the behavior, so it has been excluded. |
0 commit comments