Walkthrough of the autogenerated HTML dashboard code

When you convert a Simple XML dashboard to HTML, code is autogenerated for the dashboard that contains HTML and JavaScript. This topic walks through each section of the autogenerated code for a converted dashboard and explains what it does.

First, create a dashboard to convert using the following search that displays a result table:

  1. In Splunk Web, from any app, run this search:
  2. index=_internal | head 5 | table host, source
    
  3. Click Save As > Dashboard Panel.
  4. Enter a Dashboard ID (such as "example"), click Save, then click View Dashboard.
  5. Click ..., then click Convert to HTML, then click Convert Dashboard.
  6. Click Edit HTML to view the autogenerated code.

Let's review the interesting parts of this code, broken down into these basic sections:

Section 1: Style sheets and URL prefix

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <title>example HTML</title>
    <link rel="shortcut icon" href="{{SPLUNKWEB_URL_PREFIX}}/static/img/favicon.ico" />
        <link rel="stylesheet" type="text/css" href="/en-US/static/@387cc49a8ed8/css/build/bootstrap.min.css" />
        <link rel="stylesheet" type="text/css" href="/en-US/static/@387cc49a8ed8/css/build/pages/dashboard-simple-bootstrap.min.css" />
    <link rel="stylesheet" type="text/css" media="all" href="{{SPLUNKWEB_URL_PREFIX}}/static/app/search/dashboard.css" />
</head>

Here's the beginning of the HTML page:

  • The <head> section links to style sheets for formatting and layout, including Bootstrap and Splunk's dashboard styles.
  • A placeholder {{SPLUNKWEB_URL_PREFIX}} is used for the prefix of all internal URLs. When the dashboard is rendered, this placeholder is replaced with the correct URL for users, including their locale.

Here, you can insert links to your own style sheets, and insert a <style> section if you want to define page styles.

Section 2: Layout

<body class="simplexml preload locale-en">
<!-- 
BEGIN LAYOUT
This section contains the layout for the dashboard. Splunk uses proprietary
styles in <div> tags, similar to Bootstrap's grid system. 
-->
<header>
<a class="navSkip" href="#navSkip" tabindex="1">Screen reader users, click here to skip the navigation bar</a>
<div class="header splunk-header">
        <div id="placeholder-splunk-bar">
            <a href="{{SPLUNKWEB_URL_PREFIX}}/app/launcher/home" class="brand" title="splunk > listen to your data">splunk<strong>></strong></a>
        </div>
            <div id="placeholder-app-bar"></div>
</div>
<a id="navSkip"></a>
</header>
<div class="dashboard-body container-fluid main-section-body" data-role="main">
    <div class="dashboard-header clearfix">
        <h2>example HTML</h2>
    </div>


    <div id="row1" class="dashboard-row dashboard-row1">
        <div id="panel1" class="dashboard-cell" style="width: 100%;">
            <div class="dashboard-panel clearfix">
                
                <div class="panel-element-row">
                    <div id="element1" class="dashboard-element table" style="width: 100%">
                        <div class="panel-body"></div>
                    </div>
                </div>
            </div>
        </div>
    </div>
</div>

<!-- 
END LAYOUT
-->

This section contains the layout for the dashboard panel, including the Splunk header (with the navigation bar) and footer.

The layout is created using Splunk's styles, similar to Bootstrap styles. Splunk uses nested <div> tags to create containers in a layout of rows, columns, and cells in a grid system. If you want to maintain Splunk's dashboard look and feel, learn more about using these styles in Splunk dashboard styles.

However, you don't have to use these styles or layout at all―you can format the page however you want. For example, let's say you just want to just display the table and heading. At a minimum, you need to associate the table ID with a tag on the page, so you could replace the entire section above with this:

<body class="simplexml preload">
<p id="element1" />

Section 3: Library requirements

<script src="{{SPLUNKWEB_URL_PREFIX}}/config?autoload=1"></script>
<script src="{{SPLUNKWEB_URL_PREFIX}}/static/js/i18n.js"></script>
<script src="{{SPLUNKWEB_URL_PREFIX}}/i18ncatalog?autoload=1"></script>
<script src="{{SPLUNKWEB_URL_PREFIX}}/static/build/simplexml/index.js"></script>
<script type="text/javascript">
// <![CDATA[
// <![CDATA[

//
// LIBRARY REQUIREMENTS
//
// In the require function, we include the necessary libraries and modules for
// the HTML dashboard. Then, we pass variable names for these libraries and
// modules as function parameters, in order.
// 
// When you add libraries or modules, remember to retain this mapping order
// between the library or module and its function parameter. You can do this by
// adding to the end of these lists, as shown in the commented examples below.

require([
    "splunkjs/mvc",
    "splunkjs/mvc/utils",
    "splunkjs/mvc/tokenutils",
    "underscore",
    "jquery",
    "splunkjs/mvc/simplexml",
    "splunkjs/mvc/layoutview",
    "splunkjs/mvc/simplexml/dashboardview",
    "splunkjs/mvc/simplexml/dashboard/panelref",
    "splunkjs/mvc/simplexml/element/chart",
    "splunkjs/mvc/simplexml/element/event",
    "splunkjs/mvc/simplexml/element/html",
    "splunkjs/mvc/simplexml/element/list",
    "splunkjs/mvc/simplexml/element/map",
    "splunkjs/mvc/simplexml/element/single",
    "splunkjs/mvc/simplexml/element/table",
    "splunkjs/mvc/simpleform/formutils",
    "splunkjs/mvc/simplexml/eventhandler",
    "splunkjs/mvc/simplexml/searcheventhandler",
    "splunkjs/mvc/simpleform/input/dropdown",
    "splunkjs/mvc/simpleform/input/radiogroup",
    "splunkjs/mvc/simpleform/input/linklist",
    "splunkjs/mvc/simpleform/input/multiselect",
    "splunkjs/mvc/simpleform/input/checkboxgroup",
    "splunkjs/mvc/simpleform/input/text",
    "splunkjs/mvc/simpleform/input/timerange",
    "splunkjs/mvc/simpleform/input/submit",
    "splunkjs/mvc/searchmanager",
    "splunkjs/mvc/savedsearchmanager",
    "splunkjs/mvc/postprocessmanager",
    "splunkjs/mvc/simplexml/urltokenmodel"
    // Add comma-separated libraries and modules manually here, for example:
    // ..."splunkjs/mvc/simplexml/urltokenmodel",
    // "splunkjs/mvc/checkboxview"
    ],
    function(
        mvc,
        utils,
        TokenUtils,
        _,
        $,
        DashboardController,
        LayoutView,
        Dashboard,
        PanelRef,
        ChartElement,
        EventElement,
        HtmlElement,
        ListElement,
        MapElement,
        SingleElement,
        TableElement,
        FormUtils,
        EventHandler,
        SearchEventHandler,
        DropdownInput,
        RadioGroupInput,
        LinkListInput,
        MultiSelectInput,
        CheckboxGroupInput,
        TextInput,
        TimeRangeInput,
        SubmitButton,
        SearchManager,
        SavedSearchManager,
        PostProcessManager,
        UrlTokenModel

        // Add comma-separated parameter names here, for example: 
        // ...UrlTokenModel, 
        // CheckboxView
        ) {

        var pageLoading = true;

This section begins the JavaScript code, and loads the required JavaScript libraries and components.

The require statement specifies libraries for Simple XML and SplunkJS Stack components, and utilities such as Underscore and jQuery libraries. All of the Simple XML wrappers are required, too.

For the most part, you should leave this code as is, although you can require additional libraries as needed. If you want to add a SplunkJS Stack view to your page, you'll need to manually add it to the require section and also add a variable to the function as a parameter, without stepping on the existing code. Let's say you want to work with advanced token manipulation―you'll need to require the TokenForwarder library (the path is "splunkjs/mvc/tokenforwarder") as follows, separating new items with commas:

...

require([
    "splunkjs/mvc",
    "splunkjs/mvc/utils",
    "splunkjs/mvc/tokenutils",
    "underscore",
    "jquery",
    "splunkjs/mvc/simplexml",
    "splunkjs/mvc/layoutview",
    "splunkjs/mvc/simplexml/dashboardview",
    "splunkjs/mvc/simplexml/element/chart",
    "splunkjs/mvc/simplexml/element/event",
    "splunkjs/mvc/simplexml/element/html",
    "splunkjs/mvc/simplexml/element/list",
    "splunkjs/mvc/simplexml/element/map",
    "splunkjs/mvc/simplexml/element/single",
    "splunkjs/mvc/simplexml/element/table",
    "splunkjs/mvc/simpleform/formutils",
    "splunkjs/mvc/simpleform/input/dropdown",
    "splunkjs/mvc/simpleform/input/radiogroup",
    "splunkjs/mvc/simpleform/input/multiselect",
    "splunkjs/mvc/simpleform/input/checkboxgroup",
    "splunkjs/mvc/simpleform/input/text",
    "splunkjs/mvc/simpleform/input/timerange",
    "splunkjs/mvc/simpleform/input/submit",
    "splunkjs/mvc/searchmanager",
    "splunkjs/mvc/savedsearchmanager",
    "splunkjs/mvc/postprocessmanager",
    "splunkjs/mvc/simplexml/urltokenmodel",
    "splunkjs/mvc/tokenforwarder"  // Add the view manually
    ],
    function(
        mvc,
        utils,
        TokenUtils,
        _,
        $,
        DashboardController,
        LayoutView,
        Dashboard,
        ChartElement,
        EventElement,
        HtmlElement,
        ListElement,
        MapElement,
        SingleElement,
        TableElement,
        FormUtils,
        DropdownInput,
        RadioGroupInput,
        MultiSelectInput,
        CheckboxGroupInput,
        TextInput,
        TimeRangeInput,
        SubmitButton,
        SearchManager,
        SavedSearchManager,
        PostProcessManager,
        UrlTokenModel,
        TokenForwarder   // Add the parameter manually
) {
...

Section 4: Tokens

        // 
        // TOKENS
        //
        
        // Create token namespaces
        var urlTokenModel = new UrlTokenModel();
        mvc.Components.registerInstance('url', urlTokenModel);
        var defaultTokenModel = mvc.Components.getInstance('default', {create: true});
        var submittedTokenModel = mvc.Components.getInstance('submitted', {create: true});

        urlTokenModel.on('url:navigate', function() {
            defaultTokenModel.set(urlTokenModel.toJSON());
            if (!_.isEmpty(urlTokenModel.toJSON()) && !_.all(urlTokenModel.toJSON(), _.isUndefined)) {
                submitTokens();
            } else {
                submittedTokenModel.clear();
            }
        });

        // Initialize tokens
        defaultTokenModel.set(urlTokenModel.toJSON());

        function submitTokens() {
            // Copy the contents of the defaultTokenModel to the submittedTokenModel and urlTokenModel
            FormUtils.submitForm({ replaceState: pageLoading });
        }

        function setToken(name, value) {
            defaultTokenModel.set(name, value);
            submittedTokenModel.set(name, value);
        }

        function unsetToken(name) {
            defaultTokenModel.unset(name);
            submittedTokenModel.unset(name);
        }

This section sets up the token namespaces and token models for visualizations and searches.

  • For those tokens that use the default token model, when a token value changes, the value is updated immediately.
  • For those tokens that use the submitted token model, when a token value changes, the changed value is added to a queue and values are not updated until they are submitted.

You can specify which token model to use for individual visualizations and searches. But for the most part, you should leave the code in this section as is.

For more about tokens and how they're used, see Binding data with tokens.

Section 5: Search managers

        //
        // SEARCH MANAGERS
        //

        var search1 = new SearchManager({
            "id": "search1",
            "search": "index=_internal | head 5 | table host, source",
            "earliest_time": "$earliest$",
            "cancelOnUnload": true,
            "latest_time": "$latest$",
            "status_buckets": 0,
            "app": utils.getCurrentApp(),
            "auto_cancel": 90,
            "preview": true,
            "runWhenTimeIsUndefined": false
        }, {tokens: true, tokenNamespace: "submitted"});

Search managers are defined in this section, where you can customize and create new search managers.

  • You can change the properties as needed. For example, you could change the latest time for the search as follows:
  • "latest_time": "now",

    For a reference of the different types of search managers and the properties you can set, see the Splunk Web Framework Component Reference.

  • You can change which token model to use. In the code above, the submitted token model is used, which means that the search does not run again until token value changes are submitted. If you wanted to use the default token model and run the search as soon as a token value changes, you could make the change like this:
  • }, {tokens: true, tokenNamespace: "default"});
    

    Because the default model is "default" as the name implies, you don't even have to specify it explicitly:

    }, {tokens: true});
    

For more about adding search managers, see How to add search managers to an HTML dashboard.

Section 6: Layout and dashboard editor

        //
        // SPLUNK LAYOUT
        //

        $('header').remove();
        new LayoutView({"hideFooter": false, "hideSplunkBar": false, "hideAppBar": false, "hideChrome": false})
            .render()
            .getContainerElement()
            .appendChild($('.dashboard-body')[0]);


        //
        // DASHBOARD EDITOR
        //

        new Dashboard({
            id: 'dashboard',
            el: $('.dashboard-body'),
            showTitle: true,
            editable: true
        }, {tokens: true}).render();

This section defines the layout and dashboard views. There isn't much to customize here.

Section 7: Views

        //
        // VIEWS: VISUALIZATION ELEMENTS
        //

        var element1 = new TableElement({
            "id": "element1",
            "managerid": "search1",
            "el": $('#element1')
        }, {tokens: true, tokenNamespace: "submitted"}).render();


        //
        // VIEWS: FORM INPUTS
        //

        // This section is only included for forms

Any views (elements and form inputs) are defined here. (There are no form inputs in this example dashboard, but the placeholder notes where they would be placed.)

  • You can change the properties as needed. For example, you could add this property to the table to specify how many results to display per page:
  • "pageSize": 3,

    For a reference of the different types of properties you can set for each visualization, see the Splunk Web Framework Component Reference.

  • You can change which token model to use (see Section 5: Search managers for more about the token model).

For more about adding views, see How to add a visualization to an HTML dashboard.

Section 8: Submit data and dashboard ready

        // Initialize time tokens to default
        if (!defaultTokenModel.has('earliest') && !defaultTokenModel.has('latest')) {
            defaultTokenModel.set({ earliest: '0', latest: '' });
        }

        submitTokens();


        //
        // DASHBOARD READY
        //

        DashboardController.ready();
        pageLoading = false;

    }
);
// ]]>
</script>
</body>
</html>

This section finishes by submitting any token values.

You can add more HTML and JavaScript for your own dashboards. For an example of modifying a converted HTML dashboard, see the HTML Dashboard Tutorial.