github.com/esnet/gdg@v0.6.1-0.20240412190737-6b6eba9c14d8/website/content/docs/templating/description.md (about)

     1  ---
     2  title: "Usage Guide"
     3  weight: 1
     4  ---
     5  
     6  GDG has now introduced a new supporting tool that works in conjunction with GDG. It is currently dependent on the GDG
     7  configuration
     8  since it will operate on the currently selected context. You can confirm what the current context is by
     9  running `gdg tools ctx show`
    10  
    11  For example, my current output is as follows:
    12  
    13  ```yaml
    14  context_name:
    15    storage: ""
    16    enterprise_support: true
    17    url: http://localhost:3000
    18    token: ""
    19    user_name: admin
    20    password: admin
    21    organization_name: Main Org.
    22    watched_folders_override: [ ]
    23    watched:
    24      - General
    25      - Other
    26    connections:
    27      credential_rules:
    28        - rules:
    29            - field: name
    30              regex: misc
    31            - field: url
    32          secure_data: "misc.json"
    33        - rules:
    34            - field: url
    35              regex: .*esproxy2*
    36          secure_data: "proxy.json"
    37        - rules:
    38            - field: name
    39              regex: .*
    40          secure_data: "default.json"
    41    filter_override:
    42      ignore_dashboard_filters: false
    43    output_path: test/data
    44  ```
    45  
    46  Most of the config isn't that interesting, except the output_path will be used to determine where the newly generated
    47  dashboards will be. Make sure you have a valid configuration before continuing.
    48  
    49  ### What does gdg-generate do?
    50  
    51  There are use cases where an almost identical dashboard is needed except we need to replace certain parts of it.
    52  
    53  For example, parts of a query need to be different, a different title, brand it to specific customer with a different
    54  logo, or footer. All of these are difficult to control from grafana itself and even in the best case scenario it's not
    55  great user experience. This allows you to configure and generate a new dashboard with any set of variables and
    56  dictionaries that you will seed to the tool.
    57  
    58  ### Configuration
    59  
    60  The configuration that drives this application is `templates.yml`. You can see an example below.
    61  
    62  ```yaml
    63  entities:
    64    dashboards:
    65      - template_name: "template_example"  ##Matches the name to a file under ouput_path/templates/*.go.tmpl
    66        output: ## The section below defines one or multiple destination and the associated configuration
    67          ## that goes with it.
    68          - folder: "General"  ## Name of the new folder where the template will be created
    69            organization_name: "Main Org."
    70            dashboard_name: ""  ## Optional, defaults to template_name.json
    71            template_data: ## Template Data the dictionary of datasets that can be used in the template,
    72              # it's basically your 'seed data'.  Everything is contains is absolutely arbitrary
    73              # and can have any structure as long as it's valid yaml
    74              Title: "Bob Loves Candy"  ## Dashboard Titlte
    75              enabledlight: false  ## Boolean check to enable/disable behavior
    76              lightsources: ## some arbitrary list we get to play with
    77                - sun
    78                - moon
    79                - lightbulb
    80                - office lights
    81  ```
    82  
    83  One caveat. The "Keys" will all be lowercased due to how the data is being read in. Meaning, even though
    84  `Title` is specified, the template will see the value under "title" instead.
    85  
    86  ### Available Functions
    87  
    88  Additionally, there a few functions exposed and available to you that allows you to modify
    89  
    90  ```
    91  | Function Name    | Example                                 | Input                | Output                   |
    92  |------------------|-----------------------------------------|----------------------|--------------------------|
    93  | ToSlug           | {{ .title \| ToSlug }}                  | Bob Candy            | bob-candy                |
    94  | QuotedStringJoin | {{ .lightsources \| QuotedStringJoin }} | [sun,moon,lightbulb] | "sun","moon","lightbulb" |
    95  ```
    96  
    97  There is also a large collection of functions that have been imported from [sprig](https://masterminds.github.io/sprig/)
    98  and are available for use.
    99  
   100  ### Example Templating Snippets
   101  
   102  Data Injection
   103  
   104  ```json
   105  {
   106    "annotations": {
   107      "list": [
   108        {
   109          "$$hashKey": "{{ .title | lower | ToSlug}}",
   110          // Inserting data and piping it to two different functions.  In this case, ToLower is redundant, but it serves as a chained example.
   111          "builtIn": 1,
   112          "datasource": "Grafana",
   113          "enable": true,
   114          "hide": true,
   115          "iconColor": "rgba(0, 211, 255, 1)",
   116          "name": "Annotations Alerts",
   117          "type": "dashboard"
   118        }
   119      ]
   120    }
   121  }
   122  ```
   123  
   124  Iterating and conditionals.
   125  
   126  ```json
   127  {
   128    "link_text": [
   129      {{ if .enabledlight }}
   130      // conditional to check if to insert or not
   131        {{ range $v: = .lightsources }}
   132          // Iterating through list
   133          {{ $v }}
   134        // Inserting value
   135        {{ end }}
   136      {{ end }}
   137    ]
   138  }
   139  ```
   140  
   141  Inserting a comma delimited list
   142  
   143  ```json
   144  "link_url": [
   145    "{{ .lightsources | join ", " }}",
   146    "/grafana/d/000000003/bandwidth-dashboard",
   147    "/grafana/d/xk26IFhmk/flow-data",
   148  ]
   149  ```
   150  
   151  ### Usage
   152  
   153  As part of the installation you will have access to gdg-generate.
   154  
   155  
   156  {{< callout note >}}--config, --template-config, and -t are optional parameters.  gdg-generate will fallback on defaults if
   157  none are specified.  If -t is not provided, all templates will be processed
   158   {{< /callout >}}
   159  
   160  ```sh
   161  gdg-generate --config config/importer.yml --template-config config/template.yaml template generate  -t template_example
   162  ```
   163  
   164  Example output:
   165  
   166  ```sh
   167  2023-11-16 09:49:03 INF gen/main.go:16 Reading GDG configuration
   168  2023-11-16 09:49:03 INF gen/main.go:20 Configuration file is:  config=importer.yml
   169  2023-11-16 09:49:03 INF gen/main.go:29 Context is set to:  context=testing
   170  2023-11-16 09:49:03 INF templating/templating.go:83 Processing template template=template_example
   171  2023-11-16 09:49:03 INF templating/templating.go:97 Creating a new template folder=General orgId=2 data="map[enabledlight:false lightsources:[sun moon lightbulb office lights] title:Bob Loves Candy]"
   172  2023-11-16 09:49:03 INF templating/templating.go:100 Writing data to destination output=test/data/org_2/dashboards
   173  2023-11-16 09:49:03 INF templating/templating.go:131 template Path: path=test/data/templates
   174  ```
   175  
   176  A new file has been created under test/data/org_2/dashboards/General/template_example.json