Custom visualization API reference

The custom visualization API has been updated for Splunk software version 6.5 and is now fully supported. If you are building a new custom visualization app, use the latest version of the API. Developers whose apps use the experimental API offered with software version 6.4 are encouraged to update their apps. See API updates and migration advice for more information.

Use this reference to review custom visualization requirements, components, and configuration information.

App directory structure

To add a custom visualization to an app, put the required visualization package and configuration files into the app directory. The following layout shows required custom visualization components within an app directory. It includes Webpack configuration files.

 
appname
    appserver
        static
            visualizations
                <visualization_name>
                    src
                        visualization_source.js
                    webpack.config.js
                    visualization.js
                    visualization.css
                    formatter.html
                    package.json
                    preview.png
    default
        visualizations.conf
        savedsearches.conf
    metadata
        default.meta
    README
        savedsearches.conf.spec

---

App packaging

Webpack

Use Webpack to package custom visualization apps to run on the Splunk platform.

Webpack is a resource packaging tool that can build multiple app dependencies into a single package. This functionality provides isolation, encapsulation, and improved performance.

To learn more about Webpack, see https://webpack.github.io.

Template Webpack configuration

You can use or extend the custom visualization app template to build any custom visualization app. This template includes a visualization_source.js file and an initial Webpack configuration that works with npm (node.js package manager).

Webpack configuration details

The template Webpack configuration is located in the stand-in visualization package. You can find it in the following folder.
$TEMPLATE_APP_ROOT/appserver/static/visualizations/standin/.

The configuration contains the following two files.

File	Description	Details
package.json	npm package file.	Declares the visualization package dependencies and useful shortcuts for running build tasks.
webpack.config.js	Webpack configuration file.	Defines the build entry point and the output location Can be extended to load various resources into a visualization package. By default, webpack.config.js defines the source entry point of the package as src/visualization_source.js and the output file as visualization.js . When Webpack runs in the same directory as this configuration file, it builds the JavaScript and its dependencies together and produces a built visualization.js file.

Webpack a custom visualization

Use the Webpack configuration in the custom visualization template to build custom visualizations. After Webpack builds the custom visualization visualization.js file, the template app package can be run as an app on the Splunk platform.

Prerequisites

• Make sure that npm is installed. To install npm, see www.npmjs.com.
• Download the custom visualization template and review the Webpack configuration files.

Steps

1. In the custom visualization template, rename the /standin visualization directory for the custom visualization you are building.
2. Add your custom visualization code to visualization_source.js file.
3. Update package.json
   • Change the visualization name to match the custom visualization you are building.
   • Add any custom visualization dependencies to the dependencies list.
   • Change the description and any other details relevant to your custom visualization.
4. From your custom visualization directory run $ npm install.
5. From the same directory run $ npm run build.

These steps should produce the following built visualization file.

$TEMPLATE_APP_ROOT/appserver/static/visualizations/<visualization_name>/visualization.js

---

Logic

Use these components to build custom visualization logic.

visualization.js

By default, this file is built from the visualization_source.js source code using Webpack.

visualization_source.js

Description
This visualization source code file contains the central logic for capturing and rendering data in the visualization. It is an AMD (Asynchronous Module Definition) module that returns an object extending SplunkVisualizationBase.

Requirements

Component	Requirement details	For more information see
SplunkVisualizationBase	visualization_source.js must override the following functions and options in this class. getInitialDataParams. Indicates how the visualization framework fetches data for the visualization. updateView. Function called to render the visualization.	SplunkVisualizationBase
SplunkVisualizationUtils	Security requirement visualization_source.js must include this utility library for safely incorporating dynamic content in visualizations.	Security utilities

---

SplunkVisualizationBase

The SplunkVisualizationBase class offers an API for access and communication with the Splunk platform.

Requirements

visualization_source.js extends this class. It must override the following methods and options.

updateView

This function is called whenever search results are updated or the visualization format changes. It handles visualization rendering using the following two parameters.

• data. An object containing search result data.
• config. An object containing visualization format information.
  

getInitialDataParams

This function is required for data to be returned from the search. It specifies the data output format for search results. You can also use this function to specify the maximum number of results. Use any of the following data output options.

Mode	Example
Row-major List field values as they appear in each row of the raw JSON results object array. Returns a field name array and a row array. Each row array index contains an array representing all field values for one result. getInitialDataParams option name SplunkVisualizationBase.ROW_MAJOR_OUTPUT_MODE	{ fields: [ { name: 'store_id' }, { name: 'qty' }, { name: 'product' } ], rows: [ ['west', 400, 'shirt'], ['east', 625, 'mug'], ['north', 812, 'hat'] ] }
Column-major List field values as they appear in each column of the raw JSON results object array. Returns a field name array and a column array. Each column array index contains an array representing all results values for one field. getInitialDataParams option name SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE	{ fields: [ { name: 'store_id' }, { name: 'qty' }, { name: 'product' } ], columns: [ ['west', 'east', 'north'], [400, 625, 812], ['shirt', 'mug', 'hat'] ] }
Raw format Raw JSON object. Returns a field name array and a results array in which each index contains a result object showing all fields and field values as key value pairs. getInitialDataParams option name SplunkVisualizationBase.RAW_OUTPUT_MODE	{ fields: [ { name: 'store_id' }, { name: 'qty' }, { name: 'product' } ], results: [ { store_id: 'west', qty: 400, product: 'shirt'}, { store_id: 'east', qty: 625, product: 'mug'}, { store_id: 'north', qty: 812, product: 'hat'}, ] }

Interface methods

The following methods are available in SplunkVisualizationBase. See the interface code to review parameters for each method.

Method	Description	Override required?
initialize	Override to define initial data parameters that the framework should use to fetch data for the visualization. The code in this method can assume that the visualization root DOM (Document Object Model) element is available as this.el.	Optional
getInitialDataParams	Override to define the initial data parameters used to fetch data for the visualization.	Required
onConfigChange	Override to implement custom handling of the config attribute changes. The default behavior is to mark formatData invalid.	Optional
formatData	Override to implement custom data processing logic. The return value passes to updateView. The data return value includes a data.meta.done Boolean flag indicating that the search job is complete. Do not call this method directly in visualization_source.js. Call invalidateFormatData instead to indicate that formatData needs to run again. The framework batches all invalidation methods to update the visualization efficiently.	Optional
setupView	Override to implement the initial view setup logic. This method is called immediately before the first call to updateView. Do not call this method directly in visualization_source.js.	Optional
updateView	Override to implement visualization rendering logic. Do not call this method directly in visualization_source.js. Call invalidateUpdateView instead to indicate that updateView needs to run again. The framework batches all invalidation methods to update the visualization efficiently.	Required
reflow	Override to implement visualization resizing logic. This method is called whenever the container dimensions change. Measure this.el to determine current dimensions. Do not call this method directly in visualization_source.js. Call invalidateReflow instead to indicate that reflow needs to run again. The framework batches all invalidation methods to update the visualization efficiently.	Optional
remove	Override to perform necessary disassembly logic.	Optional
updateDataParams	Call this method to update the data parameters to use when fetching data. The framework fetches an updated data set.	Do not override. Treat this method as final.
drilldown	Call this method when a drilldown interaction happens.	Do not override. Treat this method as final.
invalidateFormatData	Call this method to indicate that formatData needs to run again. The framework batches all invalidation methods to update the visualization efficiently.	Do not override. Treat this method as final.
invalidateUpdateView	Call this method to indicate that updateView needs to run again. The framework batches all invalidation methods to update the visualization efficiently.	Do not override. Treat this method as final.
invalidateReflow	Call this method to indicate that reflow needs to run again. The framework batches all invalidation methods to update the visualization efficiently.	Do not override. Treat this method as final.
getCurrentData	Call this method to get the current data returned by formatData.	Do not override. Treat this method as final.
getCurrentConfig	Call this method to get current configuration attributes.	Do not override. Treat this method as final.
getPropertyNamespaceInfo	Call this method to get visualization namespace information.	Do not override. Treat this method as final.
setCurrentData	Reserved method name.	Do not call or override.
setCurrentConfig	Reserved method name.	Do not call or override.

SplunkVisualizationBase public interface

SplunkVisualizationBase

define([
            'underscore',
            'backbone'
        ],
        function(
            _,
            Backbone
        ) {

    var VisualizationError = function(message) {
        this.name = 'SplunkVisualizationError';
        this.message = message || '';
        Error.apply(this, arguments);
    };

    VisualizationError.prototype = new Error();

    var SplunkVisualizationBase = function(el, appName, vizName) {
        this.el = el;
        this._config = null;
        this._data = null;
        this._appName = appName;
        this._vizName = vizName;
        this.initialize();
    };

    _.extend(SplunkVisualizationBase.prototype, Backbone.Events, {

        /**
         * Override to perform constructor logic.
         *
         * Code in initialize can assume that the visualization has been assigned
         * a root DOM element, available as `this.el`.
         */
        initialize: function() {},

        /**
         * Override to define initial data parameters that the framework should use to
         * fetch data for the visualization.
         *
         * Allowed data parameters:
         *
         * outputMode (required) the data format that the visualization expects, one of
         * - SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE
         *     {
         *         fields: [
         *             { name: 'x' },
         *             { name: 'y' },
         *             { name: 'z' }
         *         ],
         *         columns: [
         *             ['a', 'b', 'c'],
         *             [4, 5, 6],
         *             [70, 80, 90]
         *         ]
         *     }
         * - SplunkVisualizationBase.ROW_MAJOR_OUTPUT_MODE
         *     {
         *         fields: [
         *             { name: 'x' },
         *             { name: 'y' },
         *             { name: 'z' }
         *         ],
         *         rows: [
         *             ['a', 4, 70],
         *             ['b', 5, 80],
         *             ['c', 6, 90]
         *         ]
         *     }
         * - SplunkVisualizationBase.RAW_OUTPUT_MODE
         *     {
         *         fields: [
         *             { name: 'x' },
         *             { name: 'y' },
         *             { name: 'z' }
         *         ],
         *         results: [
         *             { x: 'a', y: 4, z: 70 },
         *             { x: 'b', y: 5, z: 80 },
         *             { x: 'c', y: 6, z: 90 }
         *         ]
         *     }
         *
         * count (optional) how many rows of results to request, default is 1000
         *
         * offset (optional) the index of the first requested result row, default is 0
         *
         * sortKey (optional) the field name to sort the results by
         *
         * sortDirection (optional) the direction of the sort, one of:
         * - SplunkVisualizationBase.SORT_ASCENDING
         * - SplunkVisualizationBase.SORT_DESCENDING (default)
         *
         * search (optional) a post-processing search to apply to generate the results
         *
         * @param {Object} config The initial config attributes
         * @returns {Object}
         *
         */
        getInitialDataParams: function(config) {
            return {};
        },

        /**
         * Override to implement custom handling of config attribute changes.
         *
         * Default behavior is to mark the formatData routine invalid.
         *
         * @param {Object} configChanges The changed config attributes, an object with
         *     changed keys mapping to their new values
         * @param {Object} previousConfig The previous config attributes
         */
        onConfigChange: function(configChanges, previousConfig) {
            this.invalidateFormatData();
        },

        /**
         * Override to implement custom data processing logic.
         *
         * The return value of this method will be passed to the updateView routine.
         * This method should not be called directly by visualization code, call
         * invalidateFormatData instead to notify the framework that the formatData
         * routine needs to be run again.
         *
         * @param {Object} rawData The data in its raw form
         * @param {Object} config The current config attributes
         * @returns {*}
         */
        formatData: function(rawData, config) {
            return rawData;
        },

        /**
         * Override to implement one-time view setup logic.
         *
         * This method will be called immediately before the first call to the
         * updateView routine.
         * This method should not be called directly by visualization code.
         */
        setupView: function() {},

        /**
         * Override to implement visualization rendering logic.
         *
         * This method should not be called directly by visualization code, call
         * invalidateUpdateView instead to notify the framework that the updateView
         * routine needs to be run again.
         *
         * @param {*} data The formatted data, as returned by the formatData routine
         * @param {Object} config The current config attributes
         * @param {Function} async A function that notifies the framework that the
         *    visualization will update asynchronously.
         *    If all updates are occurring synchronously within updateView,
         *    the `async` parameter can be ignored.
         *    If any updates are asynchronous (e.g. animations), call async() and
         *    use the return value as a callback to signal that the update has completed:
         *
         *    updateView: function(data, config, async) {
         *        var done = async();
         *        this.performAsyncUpdates({
         *            onComplete: done
         *        });
         *    }
         */
        updateView: function(data, config, async) {},

        /**
         * Override to implement visualization resizing logic.
         *
         * This method will be called whenever the container dimensions change.
         * The current container dimensions can be obtained by measuring `this.el`.
         * This method should not be called directly by visualization code, call
         * invalidateReflow instead to notify the framework that the reflow
         * routine needs to be run again.
         *
         */
        reflow: function() {},

        /**
         * Override to perform all necessary teardown logic.
         */
        remove: function() {},

        /**
         * Call this method to update the data parameters to be used when fetching data,
         * the framework will fetch an updated data set.
         *
         * This method should be treated as final.
         *
         * @param {Object} newParams New data parameters, to be merged with the existing ones.
         *     See getInitialData above for a description of allowed inputs.
         */
        updateDataParams: function(newParams) {
            this.trigger('updateDataParams', newParams);
        },

        /**
         * Call this method to notify the framework of a drilldown interaction.
         *
         * @param payload {Object} a description of the "intention" of the drilldown interaction.
         *
         * Two different type of drilldown action are supported:
         *
         * 1) Field-value pair drilldown, where the "intention" is to filter the results by
         *    setting one or more field-value pairs as constraints, e.g.
         *
         *    this.drilldown({
         *        action: SplunkVisualizationBase.FIELD_VALUE_DRILLDOWN,
         *        data: {
         *            fieldOne: valueOne,
         *            fieldTwo: valueTwo,
         *            ...
         *        }
         *    });
         *
         * 2) Geo-spatial drilldown, where the "intention" is to filter the results to a
         *    geo-spatial region, e.g.
         *
         *    this.drilldown({
         *        action: SplunkVisualizationBase.GEOSPATIAL_DRILLDOWN,
         *        data: {
         *            lat: {
         *                name: <name of latitude field>
         *                value: <value of latitude field>
         *            },
         *            lon: {
         *                name: <name of longitude field>
         *                value: <value of longitude field>
         *            },
         *            bounds: [<south>, <west>, <north>, <east>]
         *        }
         *    });
         *
         * Additionally, the "intention" can filter the results to a specific time range.
         * The time range can be combined with any of the actions above, e.g.
         *
         *    this.drilldown({
         *        earliest: '1981-08-18T00:00:00.000-07:00',
         *        latest: '1981-08-19T00:00:00.000-07:00'
         *        // optionally an `action` and `data`
         *    });
         *
         * The `earliest` and `latest` values can be ISO timestamps in the
         * format above, or as epoch times.
         *
         * @param originalEvent {Event} (optional) the original browser event that initiated the
         *     interaction, used to support keyboard modifiers.
         *
         * This method should be treated as final.
         */

        drilldown: function(payload, originalEvent) {
            this.trigger('drilldown', payload, originalEvent);
        },

        /**
         * Call this method to notify the framework that the formatData routine needs to run again.
         *
         * The framework batches calls to this and other invalidation methods so that
         * the visualization will be updated efficiently.
         *
         * This method should be treated as final.
         */
        invalidateFormatData: function() {
            this.trigger('invalidateFormatData');
        },

        /**
         * Call this method to notify the framework that the updateView routine needs to run again.
         *
         * The framework batches calls to this and other invalidation methods so that
         * the visualization will be updated efficiently.
         *
         * This method should be treated as final.
         */
        invalidateUpdateView: function() {
            this.trigger('invalidateUpdateView');
        },

        /**
         * Call this method to notify the framework that the reflow routine needs to run again.
         *
         * The framework batches calls to this and other invalidation methods so that
         * the visualization will be updated efficiently.
         *
         * This method should be treated as final.
         */
        invalidateReflow: function() {
            this.trigger('invalidateReflow');
        },

        /**
         * Call this method to get the current data, as returned by the formatData routine.
         * Cannot be called in initialize.
         *
         * This method should be treated as final.
         *
         * @returns {*}
         */
        getCurrentData: function() {
            return this._data;
        },

        /**
         * Call this method to get the current config attributes.
         * Cannot be called in initialize.
         *
         * This method should be treated as final.
         *
         * @returns {Object}
         */
        getCurrentConfig: function() {
            return this._config;
        },

        /**
         * Call this method to get info about the viz namespace.
         *
         * This method should be treated as final.
         *
         * @returns {
         *     appName: <string>,
         *     vizName: <string>,
         *     propertyNamespace: <string>
         * }
         */
        getPropertyNamespaceInfo: function() {
            return {
                appName: this._appName,
                vizName: this._vizName,
                propertyNamespace: 'display.visualizations.custom.' + this._appName + '.' + this._vizName + '.'
            };
        },        

        /**
         * Used internally for communication between the framework and the visualization.
         *
         * This method should be treated as final, and should not be called by visualization code.
         */
        setCurrentData: function(data) {
            this._data = data;
        },

        /**
         * Used internally for communication between the framework and the visualization.
         *
         * This method should be treated as final, and should not be called by visualization code.
         */
        setCurrentConfig: function(config) {
            this._config = config;
        }

    });

    _.extend(SplunkVisualizationBase, {
        extend: Backbone.View.extend,

        COLUMN_MAJOR_OUTPUT_MODE: 'json_cols',
        ROW_MAJOR_OUTPUT_MODE: 'json_rows',
        RAW_OUTPUT_MODE: 'json',

        FIELD_VALUE_DRILLDOWN: 'fieldvalue',
        GEOSPATIAL_DRILLDOWN: 'geoviz',

        SORT_ASCENDING: 'asc',
        SORT_DESCENDING: 'desc',

        // Defines a custom error type to be thrown by sub-class in order to
        // propagate an error message up to the user of the visualization, e.g.
        //
        // if (data.columns.length < 2) {
        //     throw new SplunkVisualizationBase.VisualizationError(
        //         'This visualization requires at least two columns of data.'
        //     );
        // }
        VisualizationError: VisualizationError
    });

    return SplunkVisualizationBase;
});

---

Drilldown options

Use the provided drilldown function in SplunkVisualizationBase to implement a time based or field-value drilldown. You can also combine these drilldown types.

Time based drilldown

A time based drilldown lets users click on the visualization to open a search over the time range that the clicked area represents. Determine the earliest and latest time. Call this.drilldown and pass the time parameters to the drilldown function.

Here is an example that incorporates a helper function.

/**
 * To be called from the visualization's click handler, after computing the
 * correct time range from the target of the click.
 *
 * @param earliestTime - the lower bound of the time range,
 *          can be an ISO-8601 timestamp or an epoch time in seconds.
 * @param latestTime - the upper bound of the time range,
 *          can be an ISO-8601 timestamp or an epoch time in seconds.
 * @param browserEvent - the original browser event that caused the drilldown
 *
 * example usage:
 *
 * this.drilldownToTimeRange('1981-08-18T00:00:00.000-07:00', '1981-08-19T00:00:00.000-07:00', e);
 */
drilldownToTimeRange: function(earliestTime, latestTime, browserEvent) {
    this.drilldown({
        earliest: earliestTime,
        latest: latestTime
    }, browserEvent);
}

Field-value drilldown
A field-value drilldown lets users click on the visualization to open a search using one or more category name and value pairs that the clicked area represents. Determine the category names and values. Call this.drilldown and pass the name and value parameters to the drilldown function.

Here is an example that incorporates a helper function. This example uses one field-value pair but the custom visualizations API supports using multiple pairs.

/**
 * To be called from the visualization's click handler, after computing the
 * correct category name and value from the target of the click.
 *
 * @param categoryName - the field name for the category
 * @param categoryFieldValue - the value for the category
 * @param browserEvent - the original browser event that caused the drilldown
 *
 * example usage:
 *
 * this.drilldownToTimeRange('State', 'Oregon', e);
 */
drilldownToCategory: function(categoryName, categoryFieldValue, browserEvent) {
    var data = {};
    data[categoryName] = categoryFieldValue;

    this.drilldown({
        action: SplunkVisualizationBase.FIELD_VALUE_DRILLDOWN,
        data: data
    }, browserEvent);
}

Time based and field-value drilldown example

You can combine the two drilldown options as shown in this example.

drilldownToTimeRangeAndCategory: function(earliestTime, latestTime, categoryName, categoryValue, browserEvent) {
    var data = {};
    data[categoryName] = categoryValue;

    this.drilldown({
        action: SplunkVisualizationBase.FIELD_VALUE_DRILLDOWN,
        data: data,
        earliest: earliestTime,
        latest: latestTime
    }, browserEvent);
}

---

Utility functions

The SplunkVisualizationUtils class provides utility and security functions for custom visualizations. In addition to the following utility functions, see Security utilities for information on required security functions.

Utility

The following utility functions are available in SplunkVisualizationUtils.

Function	Description	Arguments	Returns
getColorPalette	Get a predefined color palette for categorical or semantic colors. See Design guidelines for more details on color palettes.	name(String) Use of the following palette names. splunkCategorical (default) splunkSemantic	Array of color strings in the specified palette. If no argument is provided, the function returns the splunkCategorical color palette.
parseTimestamp	Use this function whenever a date is initialized with a timestamp. The function must be used to show the correct server date and time to a user.	timestamp (ISO string object)	Timezone-corrected javaScript date object. If a non-ISO string is provided, the function returns a date. Timezone correction is not possible in this case.
normalizeBoolean	Use this function for strict normalization of a String to a Boolean. The following values are handled as true. String (case-insensitive): "true", "on", "yes", "1" Integer: 1 Boolean: true The following values are treated as false. String (case-insensitive): "false", "off", "no", "0" Integer: 0 Boolean: false	value (String, Integer, or Boolean). Value to be normalized. options (Object). Default value to return if the expression is not valid.	When a valid boolean expression is submitted, returns the normalized result. If the expression is not valid, returns the options value. If options is not specified, returns false.

Security utilities

It is a best practice to sanitize dynamic content. If you create a custom visualization app and add it to Splunkbase, dynamic content must be sanitized for your app to pass AppInspect.

Splunk platform searches can have unconstrained data outputs. This means that any data that you present in any context might be malicious. The SplunkVisualizationUtils library addresses the following common risks.

• XSS (Cross-site scripting) injection into the DOM (Document Object Model)
• XSS injection using unsafe URL schemes

Requirements

Make sure that visualization_source.js meets the following security requirements.

Requirement	Utility function to use	What to do
Prevent XSS injection.	escapeHtml(inputString)	Before adding any strings to the DOM, pass them through this SplunkVisualizationUtils function. If you are using a framework that handles HTML escaping automatically, you do not have to use this function in addition.
Strip dynamic content from unsafe URL schemes.	makeSafeUrl(inputUrl)	This SplunkVisualizationUtils function is required to pass AppInspect if the custom visualization displays links with dynamic URLs.

Examples

The following examples show you how to use security utility functions in visualization_source.js.

escapeHtml usage example

define([
    'api/SplunkVisualizationBase',
    'api/SplunkVisualizationUtils'
],
function(
    SplunkVisualizationBase,
    SplunkVisualizationUtils
) {
    var SampleViz = SplunkVisualizationBase.extend({
        getInitialDataParams: function() {
            return { outputMode: SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE };
        },
        updateView: function(data, config) {
            // Both the title and the data point are dynamic values that could potentially
            // contain malicious content (e.g. "<script>alert(1)</script>").
            // The escapeHTML function will encode them so that they can safely
            // be inserted into the DOM.
            var title = config['display.visualizations.custom.sampleApp.sampleViz.title'];
            this.el.innerHTML = '<h1>' + SplunkVisualizationUtils.escapeHtml(title) + '</h1>';
            var dataPoint = data.columns[0][0];
            this.el.innerHTML += '<p>' + SplunkVisualizationUtils.escapeHtml(dataPoint) + '</p>';
        }
    });

    return SampleViz;
});

makeSafeUrl usage example

define([
    'api/SplunkVisualizationBase',
    'api/SplunkVisualizationUtils'
],
function(
    SplunkVisualizationBase,
    SplunkVisualizationUtils
) {
    var SampleViz = SplunkVisualizationBase.extend({
        getInitialDataParams: function() {
            return { outputMode: SplunkVisualizationBase.COLUMN_MAJOR_OUTPUT_MODE };
        },
        updateView: function(data, config) {
            var dataPoint = data.columns[0][0];
            this.el.innerHTML = '<p>' + SplunkVisualizationUtils.escapeHtml(dataPoint) + '</p>';
            var seeMoreUrl = config['display.visualizations.custom.sampleApp.sampleViz.seeMoreUrl'];
            var seeMoreLink = document.createElement('a');
            seeMoreLink.innerHTML = 'See More';
            // The "see more" URL is a dynamic value that could potentially contain
            // a malicious URL (e.g. "javscript:alert(1)").
            // The makeSafeUrl function will strip out any un-safe URL schemes.
            seeMoreLink.setAttribute('href', SplunkVisualizationUtils.makeSafeUrl(seeMoreUrl));
            this.el.appendChild(seeMoreLink);
        }
    });

    return SampleViz;
});

---

User interface

Use these components to build a custom visualization user interface.

visualization.css

Description
This file contains CSS rules relevant to the visualization.

Guidelines

• The file should contain standard CSS.
• The Splunk platform picks up visualization.css automatically. The CSS file does not need to be pulled in by the visualization.
• Use class attributes instead of id attributes to define CSS rules. Dashboards can contain multiple instances of the same visualization.
• Use namespacing to avoid CSS class name conflict. See the following CSS rule namespacing requirements.

CSS class namespacing requirements
Dashboards can contain multiple visualizations. Scope CSS rules so that they are applied correctly. Use these best practices for constraining CSS rules.

Best practice	What to do
If possible, scope all styles by adding a class name unique to the root DOM element.	Include the app and visualization context in the class name as shown in this example. .splunk-custom-horizon-chart .axis { // axis styles here }
Another option is to create a class name unique to the app and visualization.	For example, use .splunk-horizon-chart-axis instead of .axis.

Example visualization.css
This CSS file contains text rules using prefixed classes.

.custom-radial-meter-chart .center-text {
    font-size: 45px;
    font-weight: 200;
    font-family: "Helvetica Neue", Helvetica, sans-serif;
}
.custom-radial-meter-chart .under-text {
    font-size: 20px;
    font-weight: 100;
    font-family: "Helvetica Neue", Helvetica, sans-serif;
}

---

formatter.html

Description
Contains HTML to render in the visualization format menu. Input elements in the HTML can specify properties to edit. These changes are passed to the visualization.

Guidelines

• The formatter.html file can contain any of the following components.
  • Multiple forms to render multiple tabs.
  • HTML only
  • Splunk platform web components.
• Name input elements according to the namespaced property that they affect. When inputs update the corresponding namespaced property in the page, the changes pass to the visualization.
• Use the following case-sensitive namespace element and syntax to specify a property.
  

  {{VIZ_NAMESPACE}}.<property name>

  The {{VIZ_NAMESPACE}} element is replaced with the namespaced portion of a property name. When combined with the property name, it works equivalently to a fully-qualified namespace.

  The fully-qualified namespace syntax previously used for properties is also still supported.

  display.visualizations.custom.<app name>.<viz name>.<property name>

For complete details, see the Formatter API reference.

---

preview.png

Description
PNG image file used in the Visualization Picker user interface. Users see the image and custom visualization name when choosing a visualization.

Guidelines

• For best results the image size should be 116px wide by 76px high.
• Only PNG formatted images are accepted.
• This file is not used as the app icon. To add an icon, see the following instructions.

Adding an app icon and screenshot image

1. Save a 36px by 36px PNG icon image as appIcon.png. Follow the pixel dimensions and file name case and spelling exactly.
2. (Optional). To add a screenshot, save a 623px by 350px PNG image as screenshot.png. Follow the pixel dimensions and file name case and spelling exactly.
3. Place the appIcon.png and screenshot.png files in the <app_name>/appserver/static directory.

---

Configuration and access control

Use these components to define custom visualization configurations and access control.

visualizations.conf

Description
To make custom visualizations available across a Splunk deployment, declare them in visualizations.conf.

Requirements

• Create a stanza for each visualization in visualizations.conf. Add the settings for loading the visualization and making it available in Splunk Web.
• Every visualization in an app must have a stanza in the visualizations.conf file. The stanza name and the label attribute are required but there are other optional settings. See the following settings list.

---

Available settings

Setting	Description	Required?
label	Public label used throughout Splunk Web to refer to the visualization.	Yes
default_height	Default visualization height.	No. Defaults to 250 if unspecified.
description	Brief description for the visualization, appearing in Splunk Web.	No
search_fragment	Brief search portion to indicate how to structure results for the visualization. Used in Splunk Web.	No
allow_user_selection	Whether the visualization should be available for users to select in Splunk Web.	No. Defaults to true, meaning that the visualization is available. A true setting can be overridden if disabled is set to 1.
disabled	If set to 1, the visualization is not available anywhere in the Splunk platform. In this case, the disabled setting overrides a true setting for allow_user_selection.	No. Defaults to 0 if unspecified, meaning that the visualization is available.
supports_trellis	Indicates whether trellis layout is available for this visualization.	No. Defaults to false
supports_drilldown	Indicates whether drilldown can be configured for this visualization in the drilldown editor user interface.	No. Defaults to false

Example visualizations.conf

This example defines two different visualizations in two stanzas. The first stanza includes all available settings. The second stanza includes only the required settings.

[first_example_visualization]
label = First example
description = Use this visualization for making example charts.
default_height = 500
search_fragment = | stats count by a, b, c, d
 
[second_example_visualization]
label = Second example

---

savedsearches.conf

Description
Use savedsearches.conf to indicate visualization property default values.

• Note: Set property defaults and handle user-configured property values in visualization_source.js.

Requirements

• Specify properties by their complete namespace. See the example below for more details.

Example savedsearched.conf
This example sets default values for two properties.

display.visualizations.custom.viz_sample_app.sample_viz.numericProperty = 100
display.visualizations.custom.viz_sample_app.sample_viz.stringProperty = stringDefault

---

default.meta

Description
Use this file to export visualizations to the system. For additional details, see the default.meta configuration spec file in the Admin Manual.

savedsearches.conf.spec

Description
Use this file to declare visualization properties.

• Note: Set property defaults and handle user-configured property values in visualization_source.js.

Requirements

• Declare all properties in this file to ensure proper handling. Properties not declared in savedsearches.conf.spec are treated as invalid and prompt warnings at startup if they are used in reports.

Example savedsearched.conf.spec
This example declares two properties.

display.visualizations.custom.viz_sample_app.sample_viz.numericProperty = <float>
display.visualizations.custom.viz_sample_app.sample_viz.stringProperty = <string>

---

Documentation

Add documentation for each custom visualization in an app.

Add a README.md file to the <visualization_name> folder. Include details for an admin and end user audience. You can follow this template to cover necessary information.

Documentation template

Documentation area	What to include
Visualization introduction	Visualization title Overview of how the visualization works to represent data Details about what kind of data works best for the visualization Brief use case examples
Search and data formatting	How to write queries that generate results in the proper data structure or format for this visualization Example queries
Visualization components	How different components add meaning or information to the visualization. For example, describe sparklines and trend indicators in a single value visualization.
Customization options	How to use the Format menu to customize and configure the visualization
Simple XML	List and define any visualization-specific Simple XML options Document full option names, data type, and any rules for accepted values Example configuration to demonstrate correct usage
Drilldown	Details of using drilldown with the visualization
Extensions	Details of extending or customizing the visualization using available frameworks.
Permissions or other administrative information	Details for admins about managing the app for end users
Support contact	Developer email or other contact details to use for questions and feedback
Software credits	Include citation details for third party software libraries or other tools used in the app. For example: https://d3js.org/

---

Additional API interactions

You can use custom visualizations in SimpleXML dashboards and SplunkJS.

Simple XML

You can include custom visualizations in Simple XML dashboards. For more information see Use custom visualizations in Simple XML.

SplunkJS

Custom visualization components registered with the system are accessible from SplunkJS. For more information see Use custom visualizations in SplunkJS.

---

Additional resources

For design and data handling best practices, see the following topics.

• Design guidelines
• Data handling guidelines