feat(custom): add helpers for dealing with panel IDs (#179)

* fix(custom): allow to disable setting the panel ID

* feat(custom): add parameter to disable overriding existing ids

* feat(custom): add helpers for dealing with panel IDs

custom/dashboard.libsonnet

@@ -13,13 +13,19 @@ local d = import 'github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet';
     + self.time.withFrom('now-6h')
     + self.time.withTo('now'),
 
-  withPanels(value): {
+  withPanels(value, setPanelIDs=true): {
     _panels:: if std.isArray(value) then value else [value],
-    panels: util.panel.setPanelIDs(self._panels),
+    panels:
+      if setPanelIDs
+      then util.panel.setPanelIDs(self._panels)
+      else self._panels,
   },
-  withPanelsMixin(value): {
+  withPanelsMixin(value, setPanelIDs=true): {
     _panels+:: if std.isArray(value) then value else [value],
-    panels: util.panel.setPanelIDs(self._panels),
+    panels:
+      if setPanelIDs
+      then util.panel.setPanelIDs(self._panels)
+      else self._panels,
   },
 
   graphTooltip+: {

custom/util/panel.libsonnet

@@ -4,19 +4,19 @@ local xtd = import 'github.com/jsonnet-libs/xtd/main.libsonnet';
 {
   local this = self,
 
+  // used in ../dashboard.libsonnet
   '#setPanelIDs':: d.func.new(
     |||
-      `setPanelIDs` ensures that all `panels` have a unique ID, this functions is used in
-      `dashboard.withPanels` and `dashboard.withPanelsMixin` to provide a consistent
-      experience.
+      `setPanelIDs` ensures that all `panels` have a unique ID, this function is used in `dashboard.withPanels` and `dashboard.withPanelsMixin` to provide a consistent experience.
 
-      used in ../dashboard.libsonnet
+      `overrideExistingIDs` can be set to not replace existing IDs, consider validating the IDs with `validatePanelIDs()` to ensure there are no duplicate IDs.
     |||,
     args=[
       d.arg('panels', d.T.array),
+      d.arg('overrideExistingIDs', d.T.bool, default=true),
     ]
   ),
-  setPanelIDs(panels):
+  setPanelIDs(panels, overrideExistingIDs=true):
     local infunc(panels, start=1) =
       std.foldl(
         function(acc, panel)
@@ -31,7 +31,12 @@ local xtd = import 'github.com/jsonnet-libs/xtd/main.libsonnet';
 
             panels+: [
               panel
-              + { id: acc.index }
+              + (
+                if overrideExistingIDs
+                   || std.get(panel, 'id', null) == null
+                then { id: acc.index }
+                else {}
+              )
               + (
                 if panel.type == 'row'
                    && 'panels' in panel
@@ -51,6 +56,38 @@ local xtd = import 'github.com/jsonnet-libs/xtd/main.libsonnet';
       ).panels;
     infunc(panels),
 
+  '#getPanelIDs':: d.func.new(
+    |||
+      `getPanelIDs` returns an array with all panel IDs including IDs from panels in rows.
+    |||,
+    args=[
+      d.arg('panels', d.T.array),
+    ]
+  ),
+  getPanelIDs(panels):
+    std.flattenArrays(
+      std.map(
+        function(panel)
+          [panel.id]
+          + (if panel.type == 'row'
+             then this.getPanelIDs(std.get(panel, 'panels', []))
+             else []),
+        panels
+      )
+    ),
+
+  '#validatePanelIDs':: d.func.new(
+    |||
+      `validatePanelIDs` validates returns `false` if there are duplicate panel IDs in `panels`.
+    |||,
+    args=[
+      d.arg('panels', d.T.array),
+    ]
+  ),
+  validatePanelIDs(panels):
+    local ids = this.getPanelIDs(panels);
+    std.set(ids) == std.sort(ids),
+
   '#sanitizePanel':: d.func.new(
     |||
       `sanitizePanel` ensures the panel has a valid `gridPos` and row panels have `collapsed` and `panels`. This function is recursively applied to panels inside row panels.

docs/API/util.md

@@ -11,16 +11,18 @@ Helper functions that work well with Grafonnet.
   * [`fn wrapPanels(panels, panelWidth, panelHeight, startY)`](#fn-gridwrappanels)
 * [`obj panel`](#obj-panel)
   * [`fn calculateLowestYforPanel(panel, panels)`](#fn-panelcalculatelowestyforpanel)
+  * [`fn getPanelIDs(panels)`](#fn-panelgetpanelids)
   * [`fn getPanelsBeforeNextRow(panels)`](#fn-panelgetpanelsbeforenextrow)
   * [`fn groupPanelsInRows(panels)`](#fn-panelgrouppanelsinrows)
   * [`fn mapToRows(func, panels)`](#fn-panelmaptorows)
   * [`fn normalizeY(panels)`](#fn-panelnormalizey)
   * [`fn normalizeYInRow(rowPanel)`](#fn-panelnormalizeyinrow)
   * [`fn resolveCollapsedFlagOnRows(panels)`](#fn-panelresolvecollapsedflagonrows)
   * [`fn sanitizePanel(panel, defaultX=0, defaultY=0, defaultHeight=8, defaultWidth=8)`](#fn-panelsanitizepanel)
-  * [`fn setPanelIDs(panels)`](#fn-panelsetpanelids)
+  * [`fn setPanelIDs(panels, overrideExistingIDs=true)`](#fn-panelsetpanelids)
   * [`fn sortPanelsByXY(panels)`](#fn-panelsortpanelsbyxy)
   * [`fn sortPanelsInRow(rowPanel)`](#fn-panelsortpanelsinrow)
+  * [`fn validatePanelIDs(panels)`](#fn-panelvalidatepanelids)
 * [`obj string`](#obj-string)
   * [`fn slugify(string)`](#fn-stringslugify)
 
@@ -105,6 +107,18 @@ PARAMETERS:
 
 `calculateLowestYforPanel` calculates Y for a given `panel` from the `gridPos` of an array of `panels`. This function is used in `normalizeY`.
 
+#### fn panel.getPanelIDs
+
+```jsonnet
+panel.getPanelIDs(panels)
+```
+
+PARAMETERS:
+
+* **panels** (`array`)
+
+`getPanelIDs` returns an array with all panel IDs including IDs from panels in rows.
+
 #### fn panel.getPanelsBeforeNextRow
 
 ```jsonnet
@@ -205,18 +219,18 @@ The default values for x,y,h,w are only applied if not already set.
 #### fn panel.setPanelIDs
 
 ```jsonnet
-panel.setPanelIDs(panels)
+panel.setPanelIDs(panels, overrideExistingIDs=true)
 ```
 
 PARAMETERS:
 
 * **panels** (`array`)
+* **overrideExistingIDs** (`bool`)
+   - default value: `true`
 
-`setPanelIDs` ensures that all `panels` have a unique ID, this functions is used in
-`dashboard.withPanels` and `dashboard.withPanelsMixin` to provide a consistent
-experience.
+`setPanelIDs` ensures that all `panels` have a unique ID, this function is used in `dashboard.withPanels` and `dashboard.withPanelsMixin` to provide a consistent experience.
 
-used in ../dashboard.libsonnet
+`overrideExistingIDs` can be set to not replace existing IDs, consider validating the IDs with `validatePanelIDs()` to ensure there are no duplicate IDs.
 
 #### fn panel.sortPanelsByXY
 
@@ -242,6 +256,18 @@ PARAMETERS:
 
 `sortPanelsInRow` applies `sortPanelsByXY` on the panels in a rowPanel.
 
+#### fn panel.validatePanelIDs
+
+```jsonnet
+panel.validatePanelIDs(panels)
+```
+
+PARAMETERS:
+
+* **panels** (`array`)
+
+`validatePanelIDs` validates returns `false` if there are duplicate panel IDs in `panels`.
+
 ### obj string