Docs (#114)

new sections for feature exploration and ide setup

CHANGELOG.md

@@ -13,6 +13,14 @@ TimeSlider label
 Improvements made to the timeSlider timezone application and label positioning to remove artifacts
 seen when not using browser-time or the 24 hour clock.
 
+Getting Started Docs Improvements
+---------------------------------
+Two new sections have been added to the docs:
+
+[Environment Setup & Editing Workflow](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/src/README.md#environment-setup--editing-workflow)
+
+[Feature Exploration](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/src/README.md#feature-exploration)
+
 ## 1.16.4
 
 SVG 'marker' element support

provisioning/dashboardData/backgroundColor.yaml

@@ -0,0 +1,5 @@
+---
+
+background:
+  darkThemeColor: "yellow"
+  lightThemeColor: "green"

src/README.md

@@ -111,6 +111,18 @@ These links take you to yaml files where each of the settings are documented:
 - [panelConfig yaml](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/yaml_defs/panelConfig.yaml)
 - [siteConfig yaml](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/yaml_defs/siteConfig.yaml)
 
+### Environment Setup & Editing Workflow
+Creating panels is best achieved by using using three IDEs together as a holistic set in the followng way:
+- Install the draw.io app and add the svgdata plugin by going to *Extras->plugins->Add->svgdata.js*. Using the app rather than the online version makes it much easier to load and save from/to your local disk.
+- Create a github repo for your svg and yaml files. This gives many things but the really big one is providing a central hub from where the files can be loaded and edited.
+- Install VSCode for viewing and editing the above repo. It offers yaml syntax highlighting and gives a place to copy out the svg for pasting into the panel.
+- With the above setup, follow an iterative workflow of:
+  - draw.io: Edit the svg -> save as svg. *Note that if using Flow Animations or widgets containing embedded images you have to `Export as -> SVG...` rather than just save.*
+  - vscode: Copy the svg -> paste into the grafana panel
+  - vscode: Edit the panelConfig yaml -> Copy the yaml -> paste the yaml into the grafana panel
+  - repeat
+With this workflow all three editors (draw.io/vscode/grafana) remain open and just act as specialised windows. Although you could edit yaml or the svg directly in the grafana panel, you'll find it much simpler to copy/paste into the panel and use the gihub repo as the underlying main version.
+
 ### First Panel
 Once your familiar with the controls creating your first proper panel boils down to this process:
 - In draw.io, create an SVG and edit the cell IDs to meaningful names. Keep it minimal in the first instance.
@@ -124,6 +136,36 @@ Once your familiar with the controls creating your first proper panel boils down
 - Use the time-slider to see your value being correctly echoed in the SVG.
 - Rinse / Repeat. 
 
+## Feature Exploration
+The API for all the panel features is detailed in the [yaml_defs](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/yaml_defs). The features are also demonstrated in the provisioning dashboards. The associated SVG and yaml files used in those dashboards, linked below in the `Data Files` column, are a good starting point to explore the feature drives. Note when clicking on the SVG links you initially land on the `Preview` tab. Just switch to the `Code` tab to be able to copy out the SVG.
+
+To explore each feature, copy/paste the SVG and yaml data into your panel. That gives you a working starting point from which to explore as you read the associated API. Exploring these features is best done by following the workflow described above in [Environment Setup & Editing Workflow](#environment-setup--editing-workflow). With the majority of them the functionality is best seen by moving the time-slider back and forth.
+
+|Feature|Description|Setup|Data Files|
+|-------|-----------|-----|----------|
+|Background Color|Background is normally left untouched but the panel yaml can define a darkTheme and a lightTheme color. If the yaml field is present the background color is driven. Go to user -> profile to change the theme from dark to light.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/backgroundColor.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/backgroundColor.yaml)|
+|Bespoke Drive|The bespoke drive demonstrates how to drive any svg attribute via mathjs formulas. See the [Bespoke Drive Example](#Bespoke-drive-example) below for details.|Variable `myVar`|[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/bespokeDrive.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/bespokeDrive.yaml)|
+|Compound Color|This demonstrates compound colors, the ability to drive a cell color field based off of an aggregation of dataRefs. The panel shows labelColor, fillColor and strokeColor being driven based off of aggregation functions 'max' and 'min'. By default thresholds inherit their array position as their order but the order term can be explicitly set. The 'inverse' box demonstrates an inverted threshold order resulting in min-data displaying as max color. Where the single 'color' drive is defined alongside a compound drive, the single drive is prepended to the compound in element 0. This is demonstrated in the 'both' cell.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/compoundColor.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/compoundColor.yaml)|
+|Decimal Points|This demonstrates the panel level decimalPoints overrides. Each box has a different decimalPoint setting at the cell level with the last box being undefined at the cell level and so falling back on the panel level default.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/decimalPointTest.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/decimalPointTest.yaml)|
+|Fill Level|Fill levels are underpinned by the SVG clip-path feature. The yaml maps the data to fill percentages and that then drives an applied clip-path rect to achieve the desired fill level. The panel demonstrates the following features: (1) A range of ellipse, rect and path shapes all being filled correctly. (2) The four rects-in-a-cross demonstrate the four fill directions. (3) The 'blue' demonstrates a static fill color defined in the SVG. (4) The bottom four rects show the percentage capping, the optional 'off' setting and the own-dataref. Note that shapes with complex inner detail such as the DB and circle-inner-cross do not render perfectly as they contain multiple path elements and so have multiple overlapping clip and fill regions.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/fillLevel.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/fillLevel.yaml)|
+|Flow Animation|draw.io has a line property called 'flow animation'. When selected the line animates in a particular direction at a particular rate to visualize flow. For these animations to be available in the panel you must use the draw.io `Export As -> SVG` rather than `Save`. The yaml data assumes directionality based on sign but that can be overriden by marking it as unidirectional. The animation duration is defined with three bounds: off, lower and upper. Whenever animations are present in the yaml data, a control is visible in the bottom left corner. This is on the timeSlider -> highlighter -> own section depending on visibility. The panel options also allows the initial animation state to be selectable.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/flowAnim.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/flowAnim.yaml)|
+|Links|This shows widgets with absolute and relative links, with and without time. The third row shows variable substitutions as defined in the site and panel config. The fourth row shows the `${cell.name}` reserved variable substitution. This yaml really only works with this repos provisioning setup as relative links have to be to something in the same site. It's included here because it does offer a set of worked examples to help demonstrate how the functionality is configured. Note that for time-variable forwarding to work, the `from` and `to` variables must be in the original url.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/links.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/links.yaml), [siteConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/linksSite.yaml)|
+|stroke Color|This demonstrates stroke-color. It shows how shapes and lines can have their stroke component colored based on thresholds and incoming data.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/flowAnim.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/strokeColor_flowAnim.yaml)|
+|Units|This demonstrates normal units with associated grafana scaling alongside custom units specified using the unitsPostfix yaml field. It demonstrates normal ascii alongside unicode characters.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/examples/darkThemeSvg1.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/units.yaml)||
+|Value Mappings|This demonstrates value mappings via range based substitution of numbers at both the panelConfig level and the siteConfig level. Grafana variable substitutions are applied to the text values in the 'low' state.|Variable `exampleVar`|[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/valueMappings.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/valueMappings.yaml), [siteConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/valueMappingsSite.yaml)|
+|Zoom Pan Pinch|This demonstrates the Zoom-Pan-Pinch configurability which supports enablement along with wheel activation keys. The activation keys are helpful as there's a clash of interests between dashboard scroll and panel zoom.|Pan / Zoom Enabled|[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/examples/darkThemeSvg1.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/provisioning/dashboardData/zoomPanPinch.yaml)|
+
+### Bespoke Drive Example
+This panel demonstrates the bespoke drive in the following ways:
+- Top Left Rect - scales with data around the top left corner
+- Middle Rect - demonstrates rect label driven from bespoke data with grafana-variable replacement.
+- Bottom Left Range Ring - scales with data around the center with aligned label again driven from a bespokeDataRef as shown by the value aliasing. label.
+- Middle Clocks - Hands rotate around the centre demonstrating namespacing alongside normal stroke color drives. The second clock leverages the same formulas as the first clock but with different data, courtesy of dataRef name setup in the per-clock constants.
+- Middle Bottom Arrow - Shows head (aka direction) configurability based off of data.
+- Left 'column of rects' - Shows all the normal drives being driven from bespokeDataRefs as defined at the drive level.
+- Right 'column of rects' - Shows all the normal drives being driven from bespokeDataRefs as defined at the cell level.
+- Right Propeller - Shows two paths, one for each blade, rotating around a set origin, both with coherent fillLevel drives.
+
 ## Want to make changes?
 Go to the [Grafana Getting Started](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/grafana-getting-started.md) guide to get going with downloading a fork and setting up your test environment.
 Once up you'll find dashboards available (sourced from the provisioning directory) that act as demonstrators for the functionality.