|
2 | 2 |
|
3 | 3 |  |
4 | 4 |
|
5 | | -[](https://www.grafana.com) |
| 5 | +[](https://www.grafana.com) |
6 | 6 |  |
7 | 7 | [](https://codecov.io/gh/VolkovLabs/volkovlabs-dynamictext-panel) |
8 | 8 | [](https://github.com/VolkovLabs/volkovlabs-dynamictext-panel/actions/workflows/codeql-analysis.yml) |
9 | 9 |
|
10 | 10 | ## Introduction |
11 | 11 |
|
12 | | -A Dynamic Text panel is a plugin for Grafana for dynamic, data-driven text with Markdown and Handlebars support. |
| 12 | +A Dynamic Text visualization panel is a Grafana plugin that transforms monotone text/table data into vibrant, easy-to-read information cards. The panel supports variables, Markdown and Handlebars. |
13 | 13 |
|
14 | | -While the built-in Text panel in Grafana does support variables, that's about as dynamic it gets. This panel lets you define a text template using the data from your data source query. |
| 14 | +The Dynamic Text visualization panel lets you define a text template using the data from your data source query. |
15 | 15 |
|
16 | 16 | [](https://youtu.be/MpNZ4Yl-p0U) |
17 | 17 |
|
18 | | -### Requirements |
| 18 | +## Requirements |
19 | 19 |
|
20 | | -- **Grafana 8.5+**, **Grafana 9.0+** is required for version 2.X. |
21 | | -- **Grafana 7.0+** is required for version 1.X. |
| 20 | +- **Grafana 8.5+**, **Grafana 9.0+** is required for major versions 2 and 3. |
| 21 | +- **Grafana 7.0+** is required for major version 1. |
22 | 22 |
|
23 | 23 | ## Getting Started |
24 | 24 |
|
25 | | -The Dynamic Text panel can be installed from the [Grafana Catalog](https://grafana.com/grafana/plugins/marcusolsson-dynamictext-panel/) or use the `grafana-cli` tool to install from the command line: |
| 25 | +The Dynamic Text visualization panel can be installed from the [Grafana Catalog](https://grafana.com/grafana/plugins/marcusolsson-dynamictext-panel/) or utilizing the Grafana command line tool. |
| 26 | + |
| 27 | +For the latter, use the following command. |
26 | 28 |
|
27 | 29 | ```bash |
28 | 30 | grafana-cli plugins install marcusolsson-dynamictext-panel |
29 | 31 | ``` |
30 | 32 |
|
31 | 33 | ## Features |
32 | 34 |
|
33 | | -- Uses Monaco Code Editor with Auto formatting to update Templates. |
| 35 | +- Uses Monaco Code Editor with Auto formatting to update Templates, JavaScript Code and Styles. |
34 | 36 | - Supports [Markdown](https://commonmark.org/help/) and [Handlebars](https://handlebarsjs.com/guide/expressions.html#basic-usage). |
35 | 37 | - Uses [markdown-it](https://github.com/markdown-it/markdown-it) for rendering Markdown to HTML. |
36 | | -- HTML inside templates is sanitized using [XSS](https://jsxss.com/en/index.html) through `textUtil`. |
37 | | -- Allows to display Time global variables (`__to` and `__from`) as seconds, ISO, and formatted using `dayjs`. |
38 | | -- Supports disable Sanitizing using Grafana configuration `disable_sanitize_html`. |
39 | | - |
40 | | -## Content |
41 | | - |
42 | | -To display data from your query result, enter the name of the field surrounded by double braces. For example, to display the value from the `Time` field: |
43 | | - |
44 | | -``` |
45 | | -{{Time}} |
46 | | -``` |
| 38 | + - Supports Code syntax highlight using a11y styles. |
| 39 | +- Sanitizing |
| 40 | + - HTML inside templates is sanitized using [XSS](https://jsxss.com/en/index.html). |
| 41 | + - Can be disabled using Grafana configuration `disable_sanitize_html`. |
| 42 | +- Allows to display nested objects using `{{json object}}` Handlebars helper. |
| 43 | +- Allows displaying Time global variables (`__to` and `__from`) as seconds, ISO, and formatted using `dayjs`. |
| 44 | +- Allows adding Handlebars helpers and Event handlers. |
| 45 | +- Allows adding CSS styles. |
| 46 | +- Supports Internationalization using custom helpers. |
47 | 47 |
|
48 | | -Panels renders the template for every row in the query result. If a query returns multiple query results, you can select the query result you wish to display from a drop-down menu. |
| 48 | +## Documentation |
49 | 49 |
|
50 | | -Template support text processing using one or more helpers and recipies: |
| 50 | +| Section | Description | |
| 51 | +| ------------------------ | -------------------------------------------------------------- | |
| 52 | +| [Content](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/content) | Explains how to create a visualization template for your data. | |
| 53 | +| [Recipes](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/recipes) | Useful snippets that you can use in your templates. | |
| 54 | +| [Release Notes](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/release) | Stay up to date with the latest features and updates. | |
51 | 55 |
|
52 | | -- [Helpers](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/helpers) - functions that let you perform text transformation within your template. |
53 | | -- [Recipes](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/recipes) - useful snippets that you can use in your templates. |
| 56 | +### Features |
54 | 57 |
|
55 | | -The panel renders Handlebars → Markdown → Sanitized HTML and displays the final result. |
| 58 | +| Section | Description | |
| 59 | +| ----------------------- | ------------------------------------------------------------------------------------------ | |
| 60 | +| [Data](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/data) | Demonstrates how to use the Every Row and All Rows options. | |
| 61 | +| [JavaScript Code](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/code) | Demonstrates how to add Handlebars helpers and Event handlers. | |
| 62 | +| [Styles](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/styles) | Demonstrates how to add CSS styles. | |
| 63 | +| [Helpers](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/helpers) | Helpers are functions that let you perform basic text transformation within your template. | |
| 64 | +| [Variables](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/variables) | Demonstrates how to use variables. | |
56 | 65 |
|
57 | | -### Default content |
| 66 | +## Tutorial |
58 | 67 |
|
59 | | -Whenever the data source query returns an empty result, Grafana displays the template in **Default content**. This can be useful to provide users with instructions on what to do, or who to contact, when the query returns an empty result. |
| 68 | +This video outlines all the new features we implemented, including the most asked-for JavaScript area code. |
60 | 69 |
|
61 | | -Even though there's no data from the data source, you can still use the available [helpers](https://volkovlabs.io/plugins/volkovlabs-dynamictext-panel/helpers). |
62 | | - |
63 | | -### Sanitizing |
64 | | - |
65 | | -Sanitizing is enabled by default and some elements like `<button>` are unavailable in the content. |
66 | | - |
67 | | -To disable sanitizing, panel depends on the Grafana configuration option [`disable_sanitize_html`](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#disable_sanitize_html). For Docker container and Docker Compose, use as: |
68 | | - |
69 | | -```bash |
70 | | -- GF_PANELS_DISABLE_SANITIZE_HTML=true |
71 | | -``` |
72 | | - |
73 | | -## Every row vs All rows |
74 | | - |
75 | | -By default, the template configured in the **Content** field is rendered for each record in the result. You can render this template only once by selecting `All rows`. In this case, the query results are passed in as the `data` field to the template. |
76 | | - |
77 | | -Handlebars provides a [builtin-helper](https://handlebarsjs.com/guide/builtin-helpers.html#each) to iterate over these records. |
78 | | - |
79 | | -If your data source returns the following data: |
80 | | - |
81 | | -```md |
82 | | -| app | description | cluster | tier | |
83 | | -| ---- | ---------------------------- | ------- | -------- | |
84 | | -| auth | Handles user authentication. | prod | frontend | |
85 | | -``` |
86 | | - |
87 | | -You can then write Markdown with placeholders for the data you want to use. The value inside each double brace expression refers to a field in the query result. |
88 | | - |
89 | | -```md |
90 | | -# {{app}} |
91 | | - |
92 | | -{{description}} |
93 | | - |
94 | | -{{#if (eq tier "frontend")}} |
95 | | -Link: <a href='https://{{cluster}}.example.com/{{app}}'>https://{{cluster}}.example.com/{{app}}</a> |
96 | | -{{/if}} |
97 | | -``` |
| 70 | +[](https://youtu.be/lJqk5Gobec4) |
98 | 71 |
|
99 | 72 | ## Feedback |
100 | 73 |
|
101 | | -We love to hear from users, developers, and the whole community interested in this plugin. These are various ways to get in touch with us: |
| 74 | +We love to hear from you. There are various ways to get in touch with us. |
102 | 75 |
|
103 | 76 | - Ask a question, request a new feature, and file a bug with [GitHub issues](https://github.com/volkovlabs/volkovlabs-dynamictext-panel/issues/new/choose). |
104 | 77 | - Sponsor our open-source plugins for Grafana with [GitHub Sponsor](https://github.com/sponsors/VolkovLabs). |
105 | 78 | - Star the repository to show your support. |
106 | 79 |
|
107 | 80 | ## License |
108 | 81 |
|
109 | | -- Apache License Version 2.0, see [LICENSE](https://github.com/volkovlabs/volkovlabs-dynamictext-panel/blob/main/LICENSE). |
| 82 | +Apache License Version 2.0, see [LICENSE](https://github.com/volkovlabs/volkovlabs-dynamictext-panel/blob/main/LICENSE). |
0 commit comments