Modify dashboards using Simple XML extensions

Was this page helpful?

On this page

Splunk is no longer actively developing new features or adding guidance to the SplunkJS stack component.
If you develop applications using the Splunk Web Framework, Splunk encourages new development using the Splunk UI Toolkit (SUIT) instead. SUIT provides component and application development tools, visualizations, a dashboard framework, and documentation. Built with ReactJS, SUIT provides a modern approach for Splunk app front-end development, and is used across Splunk's product suite. SUIT packages provide an alternative to using Simple XML extensions to modify dashboards. Instead of adding extensions to existing dashboards, you can build a page from the ground up using ReactJS. For more information, contact webplatform@splunk.com.

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.

When you use Simple XML extensions for JavaScript libraries or CSS in a dashboard, then you run the risk of breaking that dashboard when you or someone you shared it with upgrades their Splunk Enterprise instance. This is because these dependencies are dynamically linked to Splunk Enterprise and any changes to the CSS or JavaScript libraries might not be compatible with Splunk Enterprise changes. These inconsistencies can be very difficult to find and fix.

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
Add cascading style sheets
Create JavaScript extensions

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: $SPLUNKHOME/etc/apps/users/admin/<app_name>/local/data/ui/views/_dashboard_name.xml
- Shared in app: $SPLUNKHOME/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
...

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,
...

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,
...

Next steps:

To learn about working with search managers, see Add searches with search managers.
To learn about working with views, see Display data with Splunk views.
For the library path, properties, and code examples for each component, see the Splunk Web Framework Component Reference.

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/>
...

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
...

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.