Documentationbreadcrumb arrow Pluginsbreadcrumb arrow Business Formsbreadcrumb arrow Form elementsbreadcrumb arrow Link
Enterprise Open source Grafana Cloud

Link

Note

This feature is supported starting from version 3.2.1 and Grafana 10.1.0.

This element type lets you add links to your Business form. You can customize the link text using the Link Text option. If you don’t specify link text, the link address is displayed.

This element has the following specific options:

  • Link text
  • Open in: The link can open in the same tab or a new tab.
The Link element type.

Change elements model

Note

Use this model to set elements if you use the context.panel.onChangeElements([]) method.

Dynamic element creation and manipulation through the panel fetches the complete element model and sets it through a method. The elements aren’t saved in the panel options.

js 
{
  uid:'',
  id: '',
  title: '',
  type: 'link',
  linkText: '',
  target : '_blank',
  labelWidth: 10,
  width: 30,
  tooltip: '',
  section: '',
  unit: '',
  value: '',
  disabled: false,
  background: '',
  labelBackground:'',
  labelColor: '',
  helpers: {
    showIf: () => true,
    disableIf: () => false,
    getOptions: () => [],
  }
}

Code example

JavaScript 
/**
 * Hardcoded element
 */
const element = {
  uid: "uid-123",
  id: "element-123",
  title: "Element",
  type: "link",
  linkText: "",
  target: "_blank",
  labelWidth: 15,
  width: 150,
  tooltip: "",
  section: "",
  unit: "",
  value: "",
  background: "",
  labelBackground: "",
  labelColor: "",
  helpers: {
    showIf: () => true,
    disableIf: () => false,
    getOptions: () => [],
  },
};

const elementsForUI = [];
elementsForUI.push(element);

context.panel.onChangeElements(elementsForUI);

Code example with query action for initial request

Initial Request
js 
/**
 * Convert JSON to form elements array
 */
const formElements = JSON.parse(
  context.panel.data.series[0].fields[0].values[0]
);
/**
 * Set elements with helpers
 */
context.panel.onChangeElements(
  formElements.map((element) => {
    const elementInForm = context.panel.elements.find(
      (item) => item.uid === element.uid
    );
    let value = element.value;

    if (element.uid === "comment" && elementInForm) {
      value = elementInForm.value;
    }

    return {
      ...element,
      value,
      helpers: {
        showIf: () => true,
        disableIf: () => false,
        getOptions: () => element.options,
      },
    };
  })
);

Element parameters

  • value

    string. Optional.
    Current element value.

  • type

    string. Required.
    Element type: ’link'.

  • linkText

    string. Required.
    Link text.

  • target

    string. Required.
    Open link in new tab or on the same tab. ‘_blank’ | ‘_self’

  • uid

    string. Required.
    A unique identifier used for correct mapping on the UI.

  • id

    string. Required.
    The unique identifier of the element.

  • title

    string. Required.
    The title or label of the element. Equivalent to the ‘Label’ in the UI editor.

Label field

  • labelWidth

    Number | null . Required.
    The element label width.

  • width

    Number | null. Required.
    The element width.

  • tooltip

    string. Required.
    The element tooltip. Leave as an empty string (’’) if not displayed.

  • section

    string. Required.
    The unique section identifier (section ID). Specify this if the element is in a section. Leave as an empty string (’’) if the element has no section.

  • unit

    string. Required.
    The units of measurement. Located to the right of the element. Leave as an empty string (’’) if the element has no unit.

Unit of measurement

  • background

    string. Optional.
    The background color as a hex color code.

  • labelBackground

    string. Optional. The label background color as a hex color code.

  • labelColor

    string. Optional.
    The label color as a hex color code.

  • helpers

    Helpers provide information about the item display or its disabled state and return options.

js 
 {
  showIf: () => true,
  disableIf: () => false,
  getOptions: () => options || [],
 }

  • helpers.showIf

    Function. Required. Returns true or false. Controls whether the element displays on the UI.

  • helpers.disableIf

    Function. Required. Returns true or false. Controls whether the element is disabled on the UI.

  • helpers.getOptions

    Function. Required. Returns an array of options.

    Each option contains the following properties:

    • value.
      string. Required. The option value.

    • label.
      string. Required. The option label.

The link element does not support options for selection. However, they must be specified in the element object

Change options model

Note

Use this model to set elements if you use the context.panel.onOptionsChange({}) method.

Elements added through this method are added to the panel options. The element’s operation might not match the expected behavior.

If you use this method in the initial request, disable the Synchronize option. Enabling the Synchronize option with context.panel.onOptionsChange() in the Initial Request causes the panel to reload constantly.

Disable Synchronize with data to avoid endless reloading of the panel if onOptionsChange() is used in the initial request.
js 
{
  uid:'',
  id: '',
  title: '',
  type: "link",
  linkText: "",
  target: "_blank",
  labelWidth: 10,
  width: 35,
  tooltip: '',
  section: '',
  unit: '',
  value: '',
  showIf: '',
  disableIf: '',
  fieldName: '',
  queryField: {},
  background: '',
  labelBackground:'',
  labelColor: '',
}

Code example

JavaScript 
context.panel.onOptionsChange({
  ...context.panel.options,
  elements: context.panel.options.elements.map((element) => {
    return element.id === "name" ? { ...element, value: "test" } : element;
  }),
});
JavaScript 
const formElements = JSON.parse(
  context.panel.data.series[0].fields[0].values[0]
);

context.panel.onOptionsChange({
  ...context.panel.options,
  elements: formElements,
});

  • value

    string. Optional.
    Current element value.

  • type

    string. Required.
    Element type: ’link’.

  • linkText

    string. Required.
    Link text.

  • target

    string. Required.
    Open link in new tab or on the same tab. ‘_blank’ | ‘_self’

  • uid

    string. Required.
    A unique identifier used for correct mapping on the UI.

  • id

    string. Required.
    The unique identifier of the element.

  • title

    string. Required.
    The title or label of the element. Equivalent to the ‘Label’ in the UI editor.

    Label field

  • labelWidth

    Number | null . Required.
    The element label width.

  • width

    Number | null. Required.
    The element width.

  • tooltip

    string. Required.
    The element tooltip. Leave as an empty string (’’) if not displayed.

  • section

    string. Required.
    The unique section identifier (section ID). Specify this if the element is in a section. Leave as an empty string (’’) if the element has no section.

  • unit

    string. Required.
    The units of measurement. Located to the right of the element. Leave as an empty string (’’) if the element has no unit.

    Unit of measurement

  • background

    string. Optional.
    The background color as a hex color code.

  • labelBackground

    string. Optional.
    The label background color as a hex color code.

  • labelColor

    string. Optional.
    The label color as a hex color code.

  • showIf

    string. Optional.
    The “Show if” function of the element returns true or false. Controls whether the element displays on the UI.

    js 
    {
  showIf: "if (condition) {\n  return true\n}\n return false";
}

  • disableIf

    string. Optional.
    The “Disable if” function of the element returns true or false. Controls whether the element is disabled on the UI.

    js 
    {
  disableIf: "if (condition) {\n  return true\n}\n return false";
}

  • fieldName

    string. Optional.
    The name field from the DataSource initial request. Use for the initial value. We recommend using value instead.

  • queryField

    object. Optional.
    The name query from the Query initial request. Use for the initial value. We recommend using value instead.

    Parameters:

    • refId
      string. The frame refId.

    • value
      string. The field name.

    • label
      string. The format: refId:value (for example, A:time).