How to create a custom Splunk view using Django Bindings and SplunkJS Stack

Django Bindings has been deprecated. For more, see the Deprecation Notice.

While the Web Framework provides many built-in views to visualize your data, you can also create your own custom views. With a custom view, you can display Splunk events using a third-party data visualization and encapsulate the process of transforming the data into the format that the data visualization expects.

You can create a custom view in JavaScript as you would any JavaScript object, and for convenience you can also create a Django template tag to access your custom view. A custom template tag is specific to a particular app, but you can access tags from different apps using a namespaced reference.

While you can go it alone and write your custom view from scratch, the Web Framework includes a base class (a Backbone view), SimpleSplunkView, from which you can inherit these built-in features:

  • Methods to create and render the view, and format data.
  • Integration with search managers, including access to the search results model and search progress notifications.
  • Automatic updates to the view whenever its associated search changes. For example, if a search property changes, the search is run again and the view is automatically updated with the new search results.
  • Errors and messages, to help you troubleshoot (for example, console messages indicating when a search fails to run).

Use these features as a starting point, then build on them as you need to.

The basic steps for creating a custom view are as follows:

 Create a Django template tag

Using a Django template tag lets you instantiate your custom view inline in your HTML code, which is a convenient way to place the view in your apps. A custom template tag is not required though—you can also instantiate your custom views in JavaScript code and skip the template tag if you want.

To create a Django template tag, put the definition of the template tag in a Python module and save it in the $SPLUNK_HOME/etc/apps/your_app_name/django/your_app_name/templatetags directory. You'll need to provide the name of your custom template tag, the CSS class name of the custom view (choose a unique name that won't clash with other views), and the JavaScript library containing the code.

Here's the format of a Python module that defines a {% view %} template tag, for a view with a CSS class name of "view_name" and the path to your JavaScript library file view_name.js. Note that these are the only configurable items in the Python module.

# view_name.py
from django import template
from splunkdj.templatetags.tagutils import component_context
register = template.Library()

@register.inclusion_tag("splunkdj:components/component.html", takes_context=True)
def view(context, id, *args, **kwargs): # The template tag
    return component_context(
        context,
        "view_name",                    # The custom view's CSS class name
        id,
        "view",
        "your_app_name/view_name",       # Path to the JavaScript class/file for the view
        kwargs
    )

After you create this module, you must restart Splunk Web (open the http://<localhost:port>/debug/refresh URL in your web browser and click Refresh) before you can use the template tag.

You can read more about tags in Custom template tags and filters on the Django website.

 Write the JavaScript class for the custom view

To specify how to display the data from Splunk, define a custom view by creating a class that inherits from the SimpleSplunkView base class, then save your JavaScript code to the $SPLUNK_HOME/etc/apps/your_app_name/django/static/your_app_name directory.

The SimpleSplunkView base class contains several methods that you override as needed:

  • initialize: Constructor.
  • formatData: Formats results data from Splunk and returns a handle to the data, which is then passed to the updateView method as the second argument. When you don't override this method, data is passed in the output format that is specified by the output_mode property (such as json, json_rows, or json_cols).
  • formatResults: Same as formatData, except that it lets you format the entire results model object (rather than just the data portion).
  • displayMessage: Lets you render messages in a custom way.
  • createView: Configures the custom vizualization and returns a handle to it, which is then passed to the updateView method as the first argument. This method is called once.
  • updateView: Puts Splunk data (returned by the formatData method) into the view (returned by the createView method) and renders it. This method is called automatically whenever Splunk data changes, for example when a search is run again.
  • clearView: Resets rendering.
  • render: Creates the initial view and draws it on the screen. On subsequent calls, runs a full update cycle by calling formatResults, formatData, then updateView.

Here's a typical structure of a custom view:

// Custom view
define(function(require, exports, module) {
    var _ = require("underscore");
    var mvc = require("splunkjs/mvc");
    var SimpleSplunkView = require("splunkjs/mvc/simplesplunkview");
    var ViewName = SimpleSplunkView.extend({
        className: "view_name",

        // Set options for the visualization
        options: {
            data: "preview",  // The data results model from a search
            foo: "bar"
        },

        // Override this method to configure the view
        createView: function() {
            // TODO: Create a visualization
            return viz;
        },

        // Override this method to format the data for the view
        formatData: function(data) {
            // TODO: Format the data
            return data;
        },

        // Override this method to put the formatted Splunk data into the view
        updateView: function(viz, data) {
            // TODO: Display the data in the view
        }
    });
    return ViewName;
});

 Instantiate the custom view

If you created a template tag for your custom view, adding it to your template page is pretty straightforward. First, you'll need to load your template tag definition file using the {% load filename %} template tag. For example, if your template tag definition file is called mytemplatetags.py, include a {% load mytemplatetags %} template tag on your page.

Next, place a template tag to call your view in the content block. The only property that is required for a template tag is id, but you'll typically bind the view to a search using a managerid property.

Here's an example of a very basic page template:

{% extends "splunkdj:base_with_app_bar.html" %}

{% load splunkmvc %}

{% load mytemplatetags %}

{% block content %}
    {% view id="mycustomview" managerid="mysearch" %}
{% endblock content %}

If you aren't using Django, you can instantiate the custom view directly in JavaScript as follows:

    <script>
        var deps = [
            "splunkjs/mvc",
            "your_app_name/view_name"
        ];
        require(deps, function(mvc) {
            var CustomView = require("your_app_name/view_name");

            // Create a custom view
            var customView = new CustomView({
                name: "mycustomview",
                managerid: "mysearch",
                el: $("#mycustomview")
            }).render();
        });
    </script>

For end-to-end examples of creating a custom view, see the Custom view tutorial.