Formatter API reference

Use the Formatter API to build a custom visualization format menu. The Formatter API supports user experience consistency with the Splunk Web visualization Format menu.

Custom HTML element overview

The Splunk platform supports a set of custom HTML elements that manage the behavior and rendering of user interface controls. Here is an overview of the available elements.

Custom HTML element	Description
<splunk-select>	Selection control that takes options in HTML.
<splunk-radio-input>	Radio group that takes options in HTML.
<option>	Declares an option for select and radio group elements. Child element of these input elements.
<splunk-text-area>	Resizable text area.
<splunk-text-input>	Text input.
<splunk-color-picker>	Color picker element with built-in defaults. Also allows string-specified colors.

These elements have styling consistent with standard Splunk Web elements, although they do not have the standard Splunk Web layout by default.

---

Selection elements

The following elements present options and a selection interface to users.

splunk-select

Description

Use the <splunk-select> element to create a selection control. Options appear in a list.

Requirements

• Specify one or more <option> child elements defining the options that appear in the list.

---

splunk-radio-input

Description

Use the <splunk-radio-input> element to declare a radio group control.
There are three <splunk-radio-input> elements in this example.

Requirements

• Specify one or more <option> child elements to indicate the options that appear as radio buttons.

---

option

Description

Use an <option> child element with a <splunk-select> or <splunk-radio-input> to specify available options. The <option> enclosed text appears as the option label. When a user selects an option, the <option> value is set as the control value.

This example shows an option list for specifying decimal precision. Each precision level is an option.

---

Examples

Example splunk-select

<splunk-select name="display.visualizations.custom.myapp.myviz.legendPosition" value="right">
    <option value="right">Right</option>
    <option value="bottom">Bottom</option>
    <option value="left">Left</option>
    <option value="top">Top</option>
    <option value="none">None</option>
</splunk-select>

Example splunk-radio-input

<splunk-radio-input name="display.visualizations.custom.myapp.myviz.theme" value="light">
    <option value="light">Light</option>
    <option value="dark">Dark</option>
</splunk-radio-input>

---

Text entry elements

The following elements let users add text to a visualization.

splunk-text-input

Description

Use a <splunk-text-input> element to create a text input control.

This example text input lets users specify a visualization caption.

Guidelines

Users can enter up to a single line of text in a splunk-text-input control.

---

splunk-text-area

Description

Use a <splunk-text-area> element to create a text area control.

Guidelines

Users can enter multiple lines of text in a <splunk-text-area> control.

---

Examples

Example splunk-text-input

<splunk-text-input name="display.visualizations.custom.myapp.myviz.yAxisMaximum"></splunk-text-input>

Example splunk-text-area

<splunk-text-area name="display.visualizations.custom.myapp.myviz.xAxisTitle"></splunk-text-area>

---

Color configuration element

This element lets users customize colors in a visualization.

splunk-color-picker

Description

Use this element to provide a color configuration user interface.

Guidelines

• <splunk-color-picker> includes several default colors consistent with those offered in Splunk Web visualization format menus.

• In addition to default colors, the element accepts colors specified as CSS hex values. For example, #00FFFF.

Example

<splunk-color-picker name="display.visualizations.custom.viz_app.radial_meter.mainColor"></splunk-color-picker>

---

Format menu groupings and tabs

Description

Developers can customize the format menu to group different form elements into sections. Each section renders as a separate tab in the format menu.

This example shows a format menu with tabs for different format option groups.

Guidelines

• Use the schema to implement multiple form elements at the top level of the HTML hierarchy.
• Each form element should have the class splunk-formatter-section and a section-label attribute to indicate the tab label.

Example

<form class="splunk-formatter-section" section-label="Tab 1">
    ...
    <splunk-select>...</splunk-select>
    ...
</form>
<form class="splunk-formatter-section" section-label="Tab 2">
    ...
    <splunk-text-input>...</splunk-text-input>
    ...
</form>

---

CSS classes for input elements and labels

Input elements

The format menu interface uses HTML div tags and CSS control classes to structure and style input elements.

Wrap all format menu input elements with this div and class.

<div class="control-group">...</div>

Inside this div, wrap each format menu input element with the following div and classes.

Input element	Wrap with
<splunk-select>	<div class="controls controls-block"> </div>
<splunk-radio-input>	<div class="controls controls-fill"> </div>
<splunk-text-area>	<div class="controls controls-block"> </div>
<splunk-text-input>	<div class="controls controls-block"> </div>
<splunk-color-picker>	<div class="controls controls-fill"> </div>

Labels

Add the control-label class to standalone labels that appear in the format menu.

For example, within the General settings panel, you might include a radio button input to configure relative change calculation. Add a label using the following markup before the button control group.

<label class="control-label">Calculate relative change</label>

---

Complete formatter.html example

Here is an example including a radio button, text input, and a color picker.

<form class="splunk-formatter-section" section-label="General">
    <div class="control-group">
        <label class="control-label">Calculate relative change</label>
            <div class="controls controls-fill">
                <splunk-radio-input name="display.visualizations.custom.viz_tutorial_app.radial_meter.relative" value="true">
                    <option value="true" selected>Yes</option>
                    <option value="false">No</option>
                </splunk-radio-input> 
            </div>
    </div>
</form>

<form class="splunk-formatter-section" section-label="Max value">
	<div class="control-group">
     	    <label class="control-label">Max value</label>
    		<div class="controls controls-block">  
    		    <splunk-text-input name="display.visualizations.custom.viz_tutorial_app.radial_meter.maxValue"
                    </splunk-text-input>
	       </div>
	</div>
</form>
<form class="splunk-formatter-section" section-label="Dial color">
	<div class="control-group">
   		<label class="control-label">Color</label>
    		    <div class="controls controls-fill">  
        		<splunk-color-picker name="display.visualizations.custom.viz_tutorial_app.radial_meter.mainColor">
                        </splunk-color-picker>
    		   </div>
	</div>
</form>