Docs2 (#116)

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update CHANGELOG.md

CHANGELOG.md

@@ -15,12 +15,14 @@ seen when not using browser-time or the 24 hour clock.
 
 Getting Started Docs Improvements
 ---------------------------------
-Two new sections have been added to the docs:
+Three 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)
 
+[Troubleshooting FAQ](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/src/README.md#troubleshooting-faq)
+
 ## 1.16.4
 
 SVG 'marker' element support

src/README.md

@@ -151,6 +151,7 @@ To explore each feature, copy/paste the SVG and yaml data into your panel. That
 |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)|
+|Thread Highlighting|This demonstrates thread highlighting. The cells are tagged with attribute type and technology type allowing the data to be higlighted across these dimensions. The intent behind this is to make it easier to spot correlations.||[svg](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/examples/darkThemeSvg3.svg), [panelConfig](https://github.com/andymchugh/andrewbmchugh-flow-panel/blob/main/examples/panelConfig3.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)|
@@ -166,6 +167,20 @@ This panel demonstrates the bespoke drive in the following ways:
 - 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.
 
+## Troubleshooting FAQ
+- When I edit the SVG and resave nothing works anymore?
+  - This is most likely caused by not having the svgdata plugin loaded in draw.io which results in all the IDs being stripped off the SVG. If unsure look at the difference between the two versions of the SVG.
+- My label isn't being driven even though 'Debugging Mappings' says it's correctly mapped?
+  - This is most likely caused by having a multi-line label in the SVG. Multi-line isn't drivable. Your labels can be multi-word but can't contain <CRs>.
+- I've added a rect and it maps correctly to yaml but the label doesn't appear?
+  - It's not enough to just add a rect. You must also double click in it and type some text to add a label. Then the label is drivable.
+- My flow animation looks great in draw.io but doesn't work in the panel?
+  - This is most likely due to the way you saved the SVG. Flow animations have to be 'exported as svg' from draw.io, they can't just be 'saved as svg'.
+- My widget renders well in draw.io but is missing detail in the panel or just not there?
+  - This is most likely due to the way you saved the SVG. More complex widgets have to be 'exported as svg' from draw.io, they can't just be 'saved as svg'.
+- My timeseries is sparse and often the last value is null resulting in the widgets not showing a label value?
+  - By default the 'datapoint' selection is 'last' but this can be changed to 'lastNotNull'. In 'lastNotNull' mode the datapoint is walked back from the current time until it hits a non-null data value.
+
 ## 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.