Modify dashboards using Simple XML extensions

You can add custom functionality to dashboards by using Simple XML extensions, which are cascading style sheets and JavaScript files that you add to your app. You can modify layout, add new visualizations, and customize behaviors for a dashboard. By using extensions, the original dashboard is still available, and you can continue to use the built-in Dashboard Editor and PDF generation features.

To add extensions

Add an /appserver/static/ directory to your app under $SPLUNK_HOME/etc/apps/app_name/ for static CSS and JavaScript resource files. This directory is not created by default when you create an app using the "barebones" template. Restart Splunk Enterprise after you add this directory to your app.

Then, to add extensions to Simple XML:

Edit the dashboard source code

To use extensions, you'll need to edit the Simple XML source code of the dashboard:

  • To edit the Simple XML source code in Splunk Enterprise, from the dashboard click Edit, and then click Source.
  • To edit the Simple XML source code directly, open the source files in a text editor. The file location depends on the permissions you set for the dashboard:
    • Private: $SPLUNK_HOME/etc/apps/users/admin/app_name/local/data/ui/views/dashboard_name.xml
    • Shared in app: $SPLUNK_HOME/etc/apps/app_name/local/data/ui/views/dashboard_name.xml

Add references to your CSS and JavaScript extension files in your dashboard's source code as follows:

<dashboard script="filename.js" stylesheet="filename.css">

To access a visualization or form input from the dashboard using JavaScript, you must first add a component ID to the visualization or form input in the dashboard's source code, and then use this ID in your JavaScript.

Add an ID to the Simple XML source code using this format, where component corresponds to the visualization, such a chart, table, map, text input, and so forth:

    <component id="component_id">

For more about visualizations and form inputs in Simple XML, see Simple XML Reference in the Dashboards and Visualizations manual.

Add cascading style sheets

To use cascading style sheets, add the CSS files to your app's $SPLUNK_HOME/etc/apps/app_name/appserver/static/ directory.

Create JavaScript extensions

JavaScript extensions for Simple XML are based on SplunkJS Stack, allowing you to create and modify the visualizations in a Simple XML dashboard by working with their view and search manager components in JavaScript. For more about SplunkJS Stack, see Overview of SplunkJS Stack search managers and views.

To work with the SplunkJS Stack libraries, you'll need to use the "splunkjs/mvc/simplexml/ready!" script, which loads the required components and dependencies. For more about loading SplunkJS Stack components, see Load libraries, components, and dependencies.

To use JavaScript to modify your dashboard:

  • Create JavaScript files in your app's $SPLUNK_HOME/etc/apps/app_name/appserver/static/ directory.
  • Add the ready! loader script to your require statement to load the SplunkJS Stack libraries.
  • require([
        "splunkjs/mvc/simplexml/ready!"
    ], function() {
    
        . . .
    
    });
    

    Because the ready! statement does not return a value, you can call it at the end of the requirements and omit the argument from the function.

  • To access an existing component, load the "splunkjs/mvc" library, and use the splunkjs.mvc.Components.get(), settings.get(), and settings.set() methods as follows:
  • require([
        "splunkjs/mvc",
        "splunkjs/mvc/simplexml/ready!"
    ], function(mvc) {
    
        . . . 
        
        // Get the component using the ID you added to the Simple XML tag
        var componentInstance = splunkjs.mvc.Components.get("component_id");
    
    
        // Get a property
        componentInstance.settings.get("property_name");
    
    
        // Set a property
        componentInstance.settings.set("property_name", "new_value");
    
        . . . 
    
    });
    
  • To instantiate a visualization or form input using JavaScript, you'll need to instantiate the corresponding Splunk view and optionally a search manager. Add the component libraries to your require statement and instantiate the components using the following format:
  • require([
        "splunkjs/mvc/component",
        "splunkjs/mvc/simplexml/ready!"
    ], function(component) {
    
        // Instantiate the component
        new componentInstance({
            id: component_id,
            managerid: search_manager_id, // optional
            el: $("#element_location_id")
        }).render();
    
    });
    

    Important  You must position function arguments in the same order as they appear in the require statement. Otherwise, if you do not maintain the same order, you will not see an error but the dashboard will not work. The "splunkjs/mvc/simplexml/ready!" statement does not return a value, so you can call it at the end of the requirements and omit the argument from the function.

    /* The order of requirements and function arguments must match */
    
    require([
        "splunkjs/mvc/component_A",
        "splunkjs/mvc/component_B",
        "splunkjs/mvc/simplexml/ready!"
    ], function(
        component_A,
        component_B
    ) {
    
        . . . 
    
    });

Next steps:

Example

Here's an example of an extension to a dashboard with an events table, showing how to modify the events table properties and respond to click events.

Example code for the dashboard

The code below is for a dashboard that was created using the Dashboard Editor. The source code was modified by adding a reference to the example.js extension file, adding an HTML panel that displays a message, and adding an ID to the <event> tag.

<dashboard script="example.js">
  <label>Example</label>
  <description>A Simple XML dashboard using extensions</description>
  <row>
    <panel>
      <html>
        Click a row in the table to trigger a click event
        <br/><br/>
        <div id="message"/>
      </html>
    </panel>
  </row>
  <row>
    <panel>
      <title>Events table</title>
      <event id="myevents">
        <title>Top 5 results from index = _internal</title>
        <search>
          <query>index=_internal | head 5</query>
          <earliest>0</earliest>
        </search>
        <option name="list.drilldown">outer</option>
        <option name="list.wrap">1</option>
        <option name="maxLines">5</option>
        <option name="raw.drilldown">outer</option>
        <option name="rowNumbers">0</option>
        <option name="table.drilldown">all</option>
        <option name="table.wrap">1</option>
        <option name="type">list</option>
        <option name="wrap">true</option>
        <option name="dataOverlayMode">none</option>
        <option name="count">2</option>
        <fields>["host","source","sourcetype"]</fields>
      </event>
    </panel>
  </row>
</dashboard>

Example code for the JavaScript extension

This JavaScript example shows how to access the events table using the myevents ID, change the "count" property, and respond to a click event on the events table.

/* example.js */

require([
    "splunkjs/mvc",
    "splunkjs/mvc/simplexml/ready!"
], function(mvc) {

    // Get the Events table
    var myEventsTable = mvc.Components.get('myevents');

    // Programmatically change a property in the Events table
    myEventsTable.getVisualization(function(eventsView) {
        eventsView.settings.set("count", 2);
    });

    // Respond to a click event
    myEventsTable.on("click", function(e) {
        // Prevent drilldown from redirecting away from the page
        e.preventDefault();

        // Console feedback
        console.log("Click!"); 

        // Use jQuery to fill in the text in the HTML's <div> tag
        $('#message').text("Clicked!");
    });

});

For end-to-end code examples for Simple XML extensions that show how to instantiate different Splunk views and search managers, use tokens, modify drilldown actions, respond to events and more, see Code examples using the Splunk Web Framework.