IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Canvas visualization refactor (#97211)

Browse Source
This commit is contained in:
Isabel Matwawana 2024-12-02 11:53:11 -05:00 committed by GitHub
parent 4a29708f02
commit 0bc8848c85
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 252 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

312
docs/sources/panels-visualizations/visualizations/canvas/index.md
View File

@ -61,13 +61,34 @@ You can tie [Elements](#elements) and [Connections](#connections) to data throug
Elements are the basic building blocks of a canvas and they help you visualize data with different shapes and options. You can rotate and move elements around the canvas. When you move elements, snapping and alignment guides help you create more precise layouts.
Add elements in the [Layer](#layer-options) section of canvas options.
{{% admonition type="note" %}}
Element snapping and alignment only works when the canvas is not zoomed in.
{{% /admonition %}}
When you select an element that you've added to a canvas, you can access editing options for it that are dependent on the element type. The following sections describe the different elements available.
### Element types
### Basic shapes
When you select an element that you've added to a canvas, you can access [configuration options](#selected-element-options) for it that are dependent on the element type.
The following sections describe the different elements available.
{{< column-list >}}
- [Metric value](#metric-value)
- [Text](#text)
- [Ellipse](#basic-shapes)
- [Rectangle](#basic-shapes)
- [Icon](#icon)
- [Server](#server)
- [Triangle](#basic-shapes)
- [Cloud](#basic-shapes)
- [Parallelogram](#basic-shapes)
- [Button](#button)
{{< /column-list >}}
#### Basic shapes
A basic shape element can display text (both fixed and field data) and its background color can be changed based on data thresholds. You can add the following basic shapes to a canvas:
@ -77,23 +98,19 @@ A basic shape element can display text (both fixed and field data) and its backg
- Rectangle
- Triangle
### Metric value
#### Metric value
The metric value element lets you easily select the data you want to display on a canvas. This element has a unique “edit” mode that can be triggered either through the context menu “Edit” option or by double clicking. When in edit mode you can select which field data that you want to display.
The metric value element lets you select the data you want to display on a canvas. This element has a unique “edit” mode that can be triggered either through the context menu “Edit” option or by double clicking. When in edit mode you can select which field data that you want to display.
{{< video-embed src="/static/img/docs/canvas-panel/canvas-metric-value-9-2-0.mp4" max-width="750px" caption="Metric value element demo" >}}
#### Text
### Text
The text element lets you add text to the canvas. The element also supports an editing mode, triggered via either double clicking or the edit menu option in the context menu.
The text element lets you easily add text to the canvas. The element also supports an editing mode, triggered via either double clicking or the edit menu option in the context menu.
{{< video-embed src="/static/img/docs/canvas-panel/canvas-text-9-2-0.mp4" max-width="750px" caption="Text element demo" >}}
### Icon
#### Icon
The icon element lets you add a supported icon to the canvas. Icons can have their color set based on thresholds or value mappings.
#### Add a custom icon
##### Add a custom icon
You can add a custom icon by referencing an SVG file. To add a custom icon, follow these steps:
@ -102,32 +119,48 @@ You can add a custom icon by referencing an SVG file. To add a custom icon, foll
1. In the dialog box that opens, click the **URL** tab.
1. Enter the URL in the field below the **URL** tab.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="300px" alt="Add a custom image URL" >}}
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="250px" alt="Add a custom image URL" >}}
1. Click **Select**.
1. (Optional) Add a background image to your icon with the **Background (icon)** option by following the steps to [add a custom image](#add-custom-images-to-elements).
If you don't have an SVG file, you can use a rectangle element instead of an icon and set its background image to an image file type. To add a custom image for another element type, follow the steps to [add a custom image](#add-custom-images-to-elements).
### Server
#### Server
The server element lets you easily represent a single server, a stack of servers, a database, or a terminal. Server elements support status color, bulb color, and a bulb blink rate all configurable by fixed or field values.
{{< figure src="/media/docs/grafana/canvas-server-element-9-4-0.png" max-width="750px" caption="Canvas server element" >}}
{{< figure src="/media/docs/grafana/canvas-server-element-9-4-0.png" max-width="650px" alt="Canvas server element" >}}
### Button
#### Button
The button element lets you add a basic button to the canvas. Button elements support triggering basic, unauthenticated API calls. API settings are found in the button element editor. You can also pass template variables in the API editor.
The button element lets you add a basic button to the canvas. Button elements support triggering basic, unauthenticated API calls. [API settings](#button-api-options) are found in the button element editor. You can also pass template variables in the API editor.
{{% admonition type="note" %}}
A button click will only trigger an API call when [inline editing](#inline-editing) is disabled.
{{% /admonition %}}
{{< video-embed src="/media/docs/grafana/2023-20-10-Canvas-Button-Element-Enablement-Video.mp4" max-width="750px" caption="Canvas button element demo" >}}
{{< video-embed src="/media/docs/grafana/2023-20-10-Canvas-Button-Element-Enablement-Video.mp4" max-width="650px" alt="Canvas button element demo" >}}
{{< docs/play title="Canvas Visualization: Buttons" url="https://play.grafana.org/d/c9ea65f5-ed5a-45cf-8fb7-f82af7c3afdf/" >}}
## Add custom images to elements
##### Button API options
The following options let you configure basic, unauthenticated API calls:
<!-- prettier-ignore-start -->
| Option | Description |
| ------- | ------------ |
| Endpoint | Enter the endpoint URL. |
| Method | Choose from **GET**, **POST**, and **PUT**. |
| Content-Type | Select an option in the drop-down list. Choose from: JSON, Text, JavaScript, HTML, XML, and x-www-form-urlencoded. |
| Query parameters | Enter as many **Key**, **Value** pairs as you need. |
| Header parameters | Enter as many **Key**, **Value** pairs as you need. |
| Payload | Enter the body of the API call. |
<!-- prettier-ignore-end -->
### Add custom images to elements
You can add custom background images to all elements except **Button** by referencing an image URL.
The image must be hosted at a URL that allows requests from your Grafana instance.
@ -142,53 +175,92 @@ To upload a custom image, follow these steps:
1. In the dialog box that opens, click the **URL** tab.
1. Enter the URL in the field below the **URL** tab.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="300px" alt="Add a custom image URL" >}}
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="250px" alt="Add a custom image URL" >}}
1. Click **Select**.
## Connections
When building a canvas, you can connect elements together to create more complex visualizations. Connections are created by dragging from the connection anchor of one element to the connection anchor of another element. You can also create connections to the background of the canvas. Connection anchors are displayed when you hover over an element and inline editing is turned on.
When building a canvas, you can connect elements together to create more complex visualizations. You can also create connections to the background of the canvas.
To remove a connection, simply click on the connection directly and then press the "Delete" or "Backspace" key.
To create a connection, follow these steps:
{{< video-embed src="/media/docs/grafana/canvas-connections-9-4-0.mp4" max-width="750px" caption="Canvas connections demo" >}}
1. In the panel edit pane, expand the **Canvas** options section.
1. Toggle on the **Inline editing** switch.
1. Hover the cursor over an element you want to connect to display the connection anchors:
### Adjust connectors
![Element with connection anchors displayed](/media/docs/grafana/panels-visualizations/screenshot-connection-anchors-v11.3.png)
You can adjust connectors, adding angles to them, to fit the canvas you're working in. When you move connected elements, the connector resizes to fit the space. To adjust a connector, click it to display the midpoint controls and move those as needed. To make a connector a straight line again, move the midpoint back until the midpoint controls disappear.
1. Drag the cursor from a connection anchor on that element to one on another element.
If you move a connector so that it's almost a right angle or a straight line, the connector snaps into that angle or into a straight line.
To remove a connection, click the connection and then press the `Delete` or `Backspace` key.
<!-- TODO: Use updated demo from what's new when uploaded to YouTube -->
### Connection adjustments
{{< video-embed src="/media/docs/grafana/panels-visualizations/gif-canvas-connector-vertex-control-v11.0.mp4" alt="Changing a connector from a straight line to a right angle" >}}
You can adjust connections, adding angles to them, to fit the canvas you're working in. When you move connected elements, the connection resizes to fit the space.
### Style connectors
- To adjust a connection, click it to display the midpoint controls and move those as needed.
- To make a connection a straight line again, move the midpoint back until the midpoint controls disappear.
You can set the size, color, direction, and style of connections based on fixed or field values. To do so, enter into panel edit mode, select the connection, and modify the connection's properties in the panel editor.
If you move a connection so that it's almost a right angle or a straight line, the connection snaps into that angle or into a straight line.
{{< figure src="/media/docs/grafana/screenshot-grafana-10-0-canvas-service-graph.png" max-width="750px" caption="Canvas service graph" >}}
### Connection styles
You can set the size, color, direction, and style of connections based on fixed or field values. To do so, enter into panel edit mode, select the connection, and modify the connection's properties in the panel editor. For more information on connection styles, refer to [Selected connection options](#selected-connection-options).
{{< youtube id="0iO2gqv0XNA" >}}
## Canvas editing
You can make changes to a canvas visualization while in the context of the dashboard, or in dashboard mode. The following sections describe the editing options available in dashboard mode.
### Inline editor
You can edit your canvas inline while in the context of dashboard mode.
You can edit your canvas inline while in dashboard mode. The inline editor menu displays the options relevant to the part of the canvas that you've selected. You can also move the editor window around.
{{< video-embed src="/static/img/docs/canvas-panel/canvas-inline-editor-9-2-0.mp4" max-width="750px" caption="Inline editor demo" >}}
{{< video-embed src="/static/img/docs/canvas-panel/canvas-inline-editor-9-2-0.mp4" max-width="750px" alt="Inline editor demo" >}}
### Pan and zoom
### Context menu
The context menu lets you perform common tasks quickly and efficiently. Supported functionality includes opening and closing the inline editor, duplicating an element, deleting an element, and more.
The context menu is triggered by a right click action over the panel or over a given canvas element. When right clicking the panel, you are able to set a background image and easily add elements to the canvas.
{{< figure src="/static/img/docs/canvas-panel/canvas-panel-context-menu-9-3-0.png" max-width="350px" alt="Canvas panel context menu" >}}
When right clicking an element, you are able to edit, delete, duplicate, and modify the element's layer positioning.
{{< figure src="/static/img/docs/canvas-panel/canvas-context-menu-9-2-0.png" max-width="250px" alt="Canvas element context menu" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Canvas options
#### Inline editing
The inline editing toggle lets you lock or unlock the canvas. When turned off the canvas becomes “locked”, freezing elements in place and preventing unintended modifications.
{{< video-embed src="/static/img/docs/canvas-panel/canvas-inline-editing-toggle-9-2-0.mp4" max-width="750px" alt="Inline editing toggle demo" >}}
#### Experimental Element types
Toggle the switch to include experimental element types in the available selections.
#### Pan and zoom
You can enable panning and zooming in a canvas. This allows you to both create and navigate more complex designs.
{{< docs/public-preview product="Canvas pan and zoom" featureFlag="`canvasPanelPanZoom`" >}}
{{< figure src="/media/docs/grafana/screenshot-grafana-10-3-canvas-pan-zoom-setting.png" max-width="300px" alt="Canvas pan zoom control" >}}
{{< video-embed src="/media/docs/grafana/2024-01-05-Canvas-Pan-&-Zoom-Enablement-Video.mp4" max-width="750px" alt="Canvas pan and zoom enablement video" >}}
{{< video-embed src="/media/docs/grafana/2024-01-05-Canvas-Pan-&-Zoom-Enablement-Video.mp4" max-width="750px" caption="Canvas pan and zoom enablement video" >}}
#### Infinite panning
##### Infinite panning
You can enable infinite panning in a canvas when pan and zoom is enabled. This allows you to pan and zoom the canvas and uncover larger designs.
@ -196,29 +268,137 @@ You can enable infinite panning in a canvas when pan and zoom is enabled. This a
Infinite panning is an experimental feature that may not work as expected in all scenarios. For example, elements that are not top-left constrained may experience unexpected movement when panning.
{{% /admonition %}}
<!-- TODO: Add gif -->
### Layer options
### Context menu
The **Layer** options let you add elements to the canvas and control its appearance:
The context menu lets you perform common tasks quickly and efficiently. Supported functionality includes opening / closing the inline editor, duplicating an element, deleting an element, and more.
- [Elements](#elements-layer)
- [Background](#background-canvas)
- [Border](#border-canvas)
The context menu is triggered by a right click action over the panel / over a given canvas element. When right clicking the panel, you are able to set a background image and easily add elements to the canvas.
#### Elements (layer)
{{< figure src="/static/img/docs/canvas-panel/canvas-panel-context-menu-9-3-0.png" max-width="750px" caption="Canvas panel context menu" >}}
Use the **Add item** button to open the [element type](#element-types) drop-down list. Elements are listed in the reverse order that you add them to the canvas:
When right clicking an element, you are able to edit, delete, duplicate, and modify the element's layer positioning.
![Canvas elements added in the Layer options](/media/docs/grafana/panels-visualizations/screenshot-canvas-elements-v11.3.png)
{{< figure src="/static/img/docs/canvas-panel/canvas-context-menu-9-2-0.png" max-width="750px" caption="Canvas element context menu" >}}
By default, elements have numbered names, like "Element 1", and those numbers correspond to the order in which the elements were added, but you can [change the default names](#rename-an-element).
## Canvas options
You can also take the following actions on elements:
### Inline editing
- Change the order of elements by clicking and holding the row of the element while moving it up and down in the element list.
- Duplicate or remove elements by clicking the icons on the element row.
- Access the element editing options by clicking the element row. This displays the [Selected element](#selected-element-options) section of options. Click **Clear selection** to remove the element from focus and stop displaying that section of options.
The inline editing toggle lets you lock or unlock the canvas. When turned off the canvas becomes “locked”, freezing elements in place and preventing unintended modifications.
##### Rename an element
{{< video-embed src="/static/img/docs/canvas-panel/canvas-inline-editing-toggle-9-2-0.mp4" max-width="750px" caption="Inline editing toggle demo" >}}
To update the name of an element, follow these steps:
### Data links
1. Hover the cursor over the element name so the **Edit layer name** (pencil) icon is displayed.
1. Click the **Edit layer name** icon.
1. Enter a new name.
1. Click outside of the name field.
#### Background (canvas)
Use the following options to control the background of the canvas:
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| Color | Set the background color. |
| Image | Use one of the provided background images or [add your own custom image](#add-custom-images-to-elements). |
| Image size | Control the size of the image or set it as a tile. |
#### Border (canvas)
Use the following options to control the border of the canvas:
| Option | Description |
| ------ | ----------------------------------------------------------------------------------------------- |
| Width | Set the border width in pixels. |
| Color | Set the border color. This option is only displayed when the border width is greater than zero. |
| Radius | Add rounded corners to the border and control the degree of curve. |
### Selected element options
The following options allow you to control the appearance of the element you've selected. To access an element so that you can edit it, expand the **Layer** section and select the desired element.
| Option | Description |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [Element type](#element-type) | Change the selected element type. |
| [Element](#element) | Control the appearance of text on the element. This section is named based on the element type. |
| [Layout](#layout) | Control the placement of elements on the canvas. |
| [Background (element)](#background-element) | Set the background of the element. |
| [Border (element)](#border-element) | Set the border of the element. |
| [Data links](#data-links) | Configure data links for elements. |
#### Element type
You can change element type by making a new selection in the drop-down list:
![Cursor on the element type selection drop-down](/media/docs/grafana/panels-visualizations/screenshot-element-type-select-v11.3.png)
#### Element
This section is named based on the element type. Control the appearance of text on the element with the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| -------------- | --------------------------------------------------------- |
| Style | Buttons only. Select an option in the **Variant** drop-down list to indicate what kind of action the button initiates. Choose from **primary**, **secondary**, **success**, and **destructive**. |
| Text | Select a **Source**. Choose from **Fixed** or **Field**. If you selected **Fixed**, enter text in the **Value** field. If you selected **Field**, choose the field. |
| Text color | Choose a text color. |
| Align text | Set the horizontal alignment of text within the element. Choose from **Left**, **Center**, and **Right**. |
| Vertical align | Set the vertical alignment of the text within the element. Choose from **Top**, **Middle**, and **Bottom**. |
| Text size | Set the text size. Leave the field empty to allow Grafana to automatically set the text size. |
| API | Buttons only. Configure API options. For more information, refer to [Button API options](#button-api-options). |
<!--prettier-ignore-end -->
<!-- prettier-ignore-start -->
Icons don't have text, so they have different options:
| Option | Description |
| -------------- | --------------------------------------------------------- |
| SVG Path | Choose whether the icon SVG file source is **Fixed** or **Field**. If you selected **Fixed**, choose a provided option or [add a custom icon](#add-a-custom-icon). If you selected **Field**, choose a field. |
| Fill color | Choose a fill color for the icon. |
<!--prettier-ignore-end -->
#### Layout
Control the placement of elements on the canvas with the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| --------------- | --------------- |
| Quick placement | Select an alignment option to automatically place the element. Choose from:<ul><li>Align left</li><li>Align horizontal centers</li><li>Align right</li><li>Align top</li><li>Align vertical centers</li><li>Align bottom</li></ul> |
| Constraints | Set element constraints. Choose from: **Left**, **Right**, **Left & Right**, **Center**, and **Scale**.<br></br>Use the **Scale** option to ensure that elements are automatically resized when the panel size changes. |
| Position | Use these settings to manually set the position of an element. Set any or all of the following options: **top**, **left**, **width**, **height**, and **rotation**. |
<!-- prettier-ignore-end -->
#### Background (element)
Use the following options to set the background of the element:
- **Color** - Set the background color.
- **Image** - Use one of the provided background images or [add your own custom image](#add-custom-images-to-elements).
This option doesn't apply to the button element.
#### Border (element)
Use the following options to set the border of the element:
- **Width** - Set the border width in pixels.
- **Color** - Set the border color. This option is only displayed when the border width is greater than zero.
- **Radius** - Add rounded corners to the element border and control the degree of curve.
#### Data links
Canvases support [data links](ref:data-links) for all elements except drone and button elements. You can add a data link by following these steps:
@ -238,7 +418,7 @@ Canvases support [data links](ref:data-links) for all elements except drone and
If you add multiple data links, you can control the order in which they appear in the visualization. To do this, click and drag the data link to the desired position.
#### One-click data link
##### One-click data link
You can configure a canvas data link to open with a single click on the element. To enable this feature, follow these steps:
@ -253,22 +433,34 @@ The first data link in the list will be configured as your one-click data link.
{{< video-embed src="/media/docs/grafana/panels-visualizations/canvas-one-click-datalink-.mp4" >}}
## Panel options
### Selected connection options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
You can style the selected connection using the following options:
## Standard options
- **Color** - Set the connection color.
- **Size** - Control the size of the connection by entering a number in the **Value** field.
- **Radius** - Add curve to the connection by entering a value to represent the degree.
- **Arrow Direction** - Control the appearance of the arrow head. Choose from:
- **Forward** - The arrow head points in the direction in which the connection was drawn.
- **Reverse** - The arrow head points in the opposite direction of which the connection was drawn.
- **Both** - Adds arrow heads to both ends of the connection.
- **None** - Removes the arrow head.
- **Line style** - Choose from the following line styles: **Solid**, **Dashed**, and **Dotted**.
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
## Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
## Value mappings
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
## Field overrides
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}