Units: Custom unit suffix and docs for custom units (#25710)

* Units: Custom units updates and docs

* Fixed codespell

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Peter Holmberg <peterholmberg@users.noreply.github.com>

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

Co-authored-by: Peter Holmberg <peterholmberg@users.noreply.github.com>
Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

docs/sources/panels/field-configuration-options.md

@@ -12,7 +12,7 @@ This page explains what field configurations and field overrides in Grafana are
 
 > **Note:** This documentation refers to a Grafana 7.0 beta feature. This documentation will be frequently updated to reflect updates to the feature, and it will probably be broken into smaller sections when the feature moves out of beta.
 
-The data model behind Grafana, the [data frame]({{< relref "../developers/plugins/data-frames.md" >}}), is a columnar-oriented table structure. 
+The data model behind Grafana, the [data frame]({{< relref "../developers/plugins/data-frames.md" >}}), is a columnar-oriented table structure.
 
 Each column within this structure is called a _field_. Grafana allows to customize how a particular field is displayed in the visualization.
 
@@ -71,13 +71,13 @@ To change how all fields display data, you apply a [field option](#field-options
 
 ## Override a field
 
-Field overrides allow you to change the settings for one field (column in tables) to be different than the others. Field options for overrides are exactly the same as the field options available in a particular visualization. The only difference is that you choose which field to apply them to. 
+Field overrides allow you to change the settings for one field (column in tables) to be different than the others. Field options for overrides are exactly the same as the field options available in a particular visualization. The only difference is that you choose which field to apply them to.
 
 1. Navigate to the panel you want to edit, click the panel title, and then click **Edit**.
 1. Click the **Overrides** tab.
 1. Click **Add override**.
-1. Select a filter option to choose which fields the override applies to. 
-   
+1. Select a filter option to choose which fields the override applies to.
+
    **Note:** Currently you can only match by name, so after you choose the filter, select which field it applies to from the dropdown list.
 
 1. Click **Add override property**.
@@ -109,6 +109,7 @@ By default, Grafana automatically chooses display settings. You can override the
 This custom field option applies only to table visualizations.
 
 Choose how Grafana should align cell contents:
+
 - Auto (default)
 - Left
 - Center
@@ -138,7 +139,7 @@ For more information and instructions, refer to [Data links]({{< relref "../link
 
 Lets you set the display title of all fields. You can use [variables]({{< relref "../variables/templates-and-variables.md" >}}) in the field title.
 
-When multiple stats are shown, this field controls the title in each stat. By default this is the series name and field name. You can use expressions like ${__series.name} or ${__field.name} to use only series name or field name in title or ${__cell_2} to refer to other fields (2 being field/column with index 2).
+When multiple stats are shown, this field controls the title in each stat. By default this is the series name and field name. You can use expressions like ${__series.name} or ${**field.name} to use only series name or field name in title or \${**cell_2} to refer to other fields (2 being field/column with index 2).
 
 ### Max
 
@@ -154,7 +155,26 @@ Enter what Grafana should display if the field value is empty or null.
 
 ### Unit
 
-Lets you choose what unit a field should use. Click in the **Unit** field, then drill down until you find the unit you want. The unit you select is applied to all fields except time. 
+Lets you choose what unit a field should use. Click in the **Unit** field, then drill down until you find the unit you want. The unit you select is applied to all fields except time.
+
+### Custom units
+
+You can use the unit dropdown to also specify custom units, custom prefix or suffix and date time formats.
+
+To select a custom unit enter the unit and select the last `Custom: xxx` option in the dropdown.
+
+- If y u want a space -> If you want a space
+- `suffix:<suffix>` for custom unit that should go after value.
+- `time:<format>` For custom date time formats type for example `time:YYYY-MM-DD`. See [formats](https://momentjs.com/docs/#/displaying/) for the format syntax and options.
+- `si:<base scale><unit characters>` for custom SI units. For example: `si: mF`. This one is a bit more advanced as you can specify both a unit and the
+  source data scale. So if your source data is represented as milli (thousands of) something prefix the unit with that
+  SI scale character.
+- `count:<unit>` for a custom count unit.
+- `currency:<unit>` for custom a currency unit.
+
+You can also paste a native emoji in the unit picker and pick it as a custom unit:
+
+{{< docs-imagebox img="/img/docs/v66/custom_unit_burger2.png" max-width="600px" caption="Custom unit emoji" >}}
 
 ### Thresholds
 
@@ -179,34 +199,34 @@ Here are some examples of how you might use this feature.
 
 Let’s assume that our result set is a data frame that consists of two fields: time and temperature.
 
-| time | temperature |
-|:--:|:--:|
-| 2020-01-02 03:04:00 | 45.0 |
-| 2020-01-02 03:05:00 | 47.0 |
-| 2020-01-02 03:06:00 | 48.0 |
+|        time         | temperature |
+| :-----------------: | :---------: |
+| 2020-01-02 03:04:00 |    45.0     |
+| 2020-01-02 03:05:00 |    47.0     |
+| 2020-01-02 03:06:00 |    48.0     |
 
 Each field(column) of this structure can have field options applied that alter the way its values are displayed. This means that you can, for example, set the Unit to Temperature > Celsius, resulting in the following table:
 
-| time | temperature |
-|:--:|:--:|
-| 2020-01-02 03:04:00 | 45.0 °C |
-| 2020-01-02 03:05:00 | 47.0 °C |
-| 2020-01-02 03:06:00 | 48.0 °C |
+|        time         | temperature |
+| :-----------------: | :---------: |
+| 2020-01-02 03:04:00 |   45.0 °C   |
+| 2020-01-02 03:05:00 |   47.0 °C   |
+| 2020-01-02 03:06:00 |   48.0 °C   |
 
 While we're at it, the decimal place doesn't add anything to this display. You can change the Decimals from `auto` to zero (`0`), resulting in the following table:
 
-| time | temperature |
-|:--:|:--:|
-| 2020-01-02 03:04:00 | 45 °C |
-| 2020-01-02 03:05:00 | 47 °C |
-| 2020-01-02 03:06:00 | 48 °C |
+|        time         | temperature |
+| :-----------------: | :---------: |
+| 2020-01-02 03:04:00 |    45 °C    |
+| 2020-01-02 03:05:00 |    47 °C    |
+| 2020-01-02 03:06:00 |    48 °C    |
 
 ## Field override example
 
 Let’s assume that our result set is a data frame that consists of four fields: time, high temp, low temp, and humidity.
 
 | time                | high temp | low temp | humidity |
-|---------------------|-----------|----------|----------|
+| ------------------- | --------- | -------- | -------- |
 | 2020-01-02 03:04:00 | 45.0      | 30.0     | 67       |
 | 2020-01-02 03:05:00 | 47.0      | 34.0     | 68       |
 | 2020-01-02 03:06:00 | 48.0      | 31.0     | 68       |
@@ -214,15 +234,15 @@ Let’s assume that our result set is a data frame that consists of four fields:
 Let's apply the field options from the [field option example](#field-option-example) to apply the Celsius unit and get rid of the decimal place. This results in the following table:
 
 | time                | high temp | low temp | humidity |
-|---------------------|-----------|----------|----------|
-| 2020-01-02 03:04:00 | 45 °C  | 30 °C  | 67 °C    |
-| 2020-01-02 03:05:00 | 47 °C  | 34 °C  | 68 °C    |
-| 2020-01-02 03:06:00 | 48 °C  | 31 °C  | 68 °C    |
+| ------------------- | --------- | -------- | -------- |
+| 2020-01-02 03:04:00 | 45 °C     | 30 °C    | 67 °C    |
+| 2020-01-02 03:05:00 | 47 °C     | 34 °C    | 68 °C    |
+| 2020-01-02 03:06:00 | 48 °C     | 31 °C    | 68 °C    |
 
 The temperature fields look good, but the humidity is nonsensical. We can fix this by applying a field option override to the humidity field and change the unit to Misc > percent (0-100). This results in a table that makes a lot more sense:
 
 | time                | high temp | low temp | humidity |
-|---------------------|-----------|----------|----------|
-| 2020-01-02 03:04:00 | 45 °C  | 30 °C  | 67%    |
-| 2020-01-02 03:05:00 | 47 °C  | 34 °C  | 68%    |
-| 2020-01-02 03:06:00 | 48 °C  | 31 °C  | 68%    |
+| ------------------- | --------- | -------- | -------- |
+| 2020-01-02 03:04:00 | 45 °C     | 30 °C    | 67%      |
+| 2020-01-02 03:05:00 | 47 °C     | 34 °C    | 68%      |
+| 2020-01-02 03:06:00 | 48 °C     | 31 °C    | 68%      |

packages/grafana-data/src/valueFormats/valueFormats.test.ts

@@ -48,6 +48,7 @@ const formatTests: ValueFormatTest[] = [
 
   // Prefix (unknown units append to the end)
   { id: 'prefix:b', value: 1532.82, result: 'b1533' },
+  { id: 'suffix:d', value: 1532.82, result: '1533 d' },
 
   // SI Units
   { id: 'si:µF', value: 1234, decimals: 2, result: '1.23 mF' },

packages/grafana-data/src/valueFormats/valueFormats.ts

@@ -198,6 +198,10 @@ export function getValueFormat(id?: string | null): ValueFormatter {
         return toFixedUnit(sub, true);
       }
 
+      if (key === 'suffix') {
+        return toFixedUnit(sub, false);
+      }
+
       if (key === 'time') {
         return toDateTimeValueFormatter(sub);
       }