Skip to content

Commit 8e15c28

Browse files
oneirocosmoneirocosm
authored
Custom Widget Fixes (#1253)
Addresses: - Table formatting - Adds an info section explaining font awesome icons
1 parent 045405a commit 8e15c28

1 file changed

Lines changed: 27 additions & 11 deletions

File tree

‎docs/docs/customwidgets.mdx‎

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ All widgets share a similar structure that roughly looks like the example below:
1414

1515
```json
1616
"<widget name>": {
17-
"icon": "<fontawesome icon name>",
17+
"icon": "<font awesome icon name>",
1818
"label": "<the text label of the widget>",
1919
"color": "<the color of the label>",
2020
"blockdef": {
@@ -29,20 +29,36 @@ All widgets share a similar structure that roughly looks like the example below:
2929

3030
This consists of a couple different parts. First and foremost, each widget has a unique identifying name. The value associated with this name is the outer `WidgetConfigType`. It is outlined in red below:
3131

32+
![An example of a widget with outer keys labeled as WidgetConfigType and inner keys labeled as MetaTSType. In the example, the outer keys are icon, label, color, and blockdef. The inner keys are view, controller, and cmd.](/img/widget-example.png)
33+
3234
This `WidgetConfigType` is shared between all types of widgets. That is to say, all widgets&mdash;regardless of type&mdash; will use the same keys for this. The accepted keys are:
3335

3436
| Key | Description |
3537
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
3638
| "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. |
37-
| "icon" | (optional) The name of a fontawesome icon. Defaults to `"browser"`. |
39+
| "icon" | (optional) The name of a [font awesome icon](#font-awesome-icons). Defaults to `"browser"`. |
3840
| "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"`. |
3941
| "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. |
4042
| "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. |
4143
| "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. |
4244

43-
The other options are part of the inner `MetaTSType`. This contains all of the details about how the widget actually works. The valid keys vary with each type of widget. They will be individually explored in more detail below.
45+
<a name="font-awesome-icons" />
46+
:::info
4447

45-
![An example of a widget with outer keys labeled as WidgetConfigType and inner keys labeled as MetaTSType. In the example, the outer keys are icon, label, color, and blockdef. The inner keys are view, controller, and cmd.](/img/widget-example.png)
48+
**Font Awesome Icons**
49+
50+
[Font Awesome](https://fontawesome.com/search) provides a ton of useful icons that you can use as a widget icon in your app. At it's simplest, you can just provide the icon name and it will be used. For example, the string `"house"`, will provide an icon containing a house. We also allow you to apply a few different styles to your icon by modifying the name as follows:
51+
52+
| format | description |
53+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54+
| &lt;icon&nbsp;name&gt; | The plain icon with no additional styles applied. |
55+
| solid@&lt;icon&nbsp;name&gt; | Adds the `fa-solid` class to the icon to fill in the content with a fill color rather than leaving it a background. |
56+
| regular@&lt;icon&nbsp;name&gt; | Adds the `fa-regular` class to the icon to ensure the content will not have a fill color and will use a standard outline instead. |
57+
| brands@&lt;icon&nbsp;name&gt; | This is required to add the required `fa-brands` class to an icon associated with a brand. Without this, brand icons will not render properly. This will not work with icons that aren't brand icons. |
58+
59+
:::
60+
61+
The other options are part of the inner `MetaTSType` (outlined in blue in the image). This contains all of the details about how the widget actually works. The valid keys vary with each type of widget. They will be individually explored in more detail below.
4662

4763
# Terminal and CLI Widgets
4864

@@ -52,7 +68,7 @@ A terminal widget, or CLI widget, is a widget that simply opens a terminal and r
5268
{
5369
<... other widgets go here ...>,
5470
"<widget name>": {
55-
"icon": "<fontawesome icon name>",
71+
"icon": "<font awesome icon name>",
5672
"label": "<the text label of the widget>",
5773
"color": "<the color of the label>",
5874
"blockdef": {
@@ -140,7 +156,7 @@ Sometimes, it is desireable to open a page directly to a website. That can easil
140156
{
141157
<... other widgets go here ...>,
142158
"<widget name>": {
143-
"icon": "<fontawesome icon name>",
159+
"icon": "<font awesome icon name>",
144160
"label": "<the text label of the widget>",
145161
"color": "<the color of the label>",
146162
"blockdef": {
@@ -211,8 +227,8 @@ The Sysinfo Widget is intentionally kept to a very small subset of possible valu
211227
"blockdef": {
212228
"meta": {
213229
"view": "sysinfo",
214-
"graph:numpoints": <the max number of points in the graph>,
215-
"sysinfo:type": <the name of the plot collection>,
230+
"graph:numpoints": <the max number of points in the graph>,
231+
"sysinfo:type": <the name of the plot collection>,
216232
}
217233
}
218234
},
@@ -238,8 +254,8 @@ Suppose you have a build process that lasts 3 minutes and you'd like to be able
238254
"blockdef": {
239255
"meta": {
240256
"view": "sysinfo",
241-
"graph:numpoints": 180,
242-
"sysinfo:type": "CPU + Mem"
257+
"graph:numpoints": 180,
258+
"sysinfo:type": "CPU + Mem"
243259
}
244260
}
245261
},
@@ -258,7 +274,7 @@ Now, suppose you are fine with the default 100 points (and 100 seconds) but woul
258274
"blockdef": {
259275
"meta": {
260276
"view": "sysinfo",
261-
"sysinfo:type": "All CPU"
277+
"sysinfo:type": "All CPU"
262278
}
263279
}
264280
},

0 commit comments

Comments
 (0)