Developing Views and Apps for Splunk Web

About advanced XML

This section provides an introduction to building views using Splunk's advanced XML. It describes basic concepts and provides some example views. The documentation in this chapter is enough to get you started using advanced XML. For additional information:

• Splunk App Framework: Refer to the Splunk App Framework section available from the Splunk Developer Portal.

• UI Examples app: Additional examples and documentation are available from the UI Examples app, available from Splunkbase.

• Advanced XML from the Splunk Wiki Cookbook The Advanced XML section provides some useful examples on getting started.

Simple XML and Splunk's Dashboard Editor

Before building a view using Splunk's advanced XML, you may want to start with Splunk's Dashboard Editor, which uses simple XML. To add features not available with simple XML, convert views from simple XML to advanced XML using the following URI from Splunk Web:

http://localhost:8000/en-US/app/<app_name>/<view_name>?showsource=true

Views

Splunk builds views from XML files stored in an App's view directory. Views are made out of a library of modules. A module is actually a directory of CSS, JavaScript, HTML and, in some cases, Python files.

You can create and edit views according to your needs. Use simple XML for basic views. Use advanced XML for features not available from simple XML. For example, if you want to build a search view, or you want to use modules that aren't available in simple XML.

Modules

Every element in a Splunk view, from the search bar to the results, derives from a Splunk module. Some invisible elements, such as searches running in the background, derive from modules as well. You build and configure views by selecting the appropriate modules and linking them together.

For example, the search bar is one module. Graphs and charts, text entry boxes, links, drop-down menus, and other components are also modules. The Module Reference in this manual lists all available modules, sorted by category. Splunk Web also displays modules sorted alphabetically at the following URL:

http://localhost:8000/modules

Module implementation is available in the following directory of a Splunk installation:

$SPLUNK_HOME/share/splunk/search_mrsparkle/modules/

Module parameters

Modules use parameters to specify module-specific configurations, such as the size of a graph or chart, or the number of events to display per view. Use the <param> tag within a <module> tag to specify parameters, as indicated below. For example:

<module name="Message">
  <param name="filter">*</param>
</module>

The Module Reference lists the parameters available for each module. Some params are required, while others are optional. Some params have default settings.

Module hierarchy

Modules in a view pass information through a tree structure. For example, in a search view, search information passes from a parent module to child modules. Each child module can modify the search in some way. Finally, the search returns events or is transformed into results. For dashboard views, each panel in the dashboard is likely built from a separate search. In this case, you have more modules with smaller trees than a dashboard built from a single search.

The top-level module in a hierarchy uses the layoutPanel attribute to specify its location within the view. Child modules in the tree that do not specify the layoutPanel attribute inherit the attribute from their parent. Multiple panels in a view specify their position on the page using the layoutPanel attribute. For example:

<module name="SearchBar" layoutPanel="mainSearchControls">

Append ?showsource=true to any view's URL to see the hierarchy of modules in the page. For example,

http://localhost:8000/en-US/app/search/charting?showsource=true

Intentions

You can use intentions to pass search language modifications down the module tree hierarchy. Specifically, modules pass searches down the hierarchy, modifying the searches by adding intentions. Once a series of intentions reaches a special type of module -- a dispatching module -- the intentions are composed into a search that is run in Splunk.

Most results modules are dispatching modules -- if a results module doesn't have any results from a search by the time they are invoked in a view, the results module compiles the intentions and runs the resulting search.

Layout templates

There are two types of views: dashboards and search views. A Mako layout template defines each of these types of views. Mako templates are written in Python. Splunk's layout templates define page layout; basically, how each element fits into a page. Splunk stores layout templates in the following location:

$SPLUNK_HOME/share/splunk/search_mrsparkle/templates/view/

Dashboards use a series of rows and columns in their layout. Search views contain a search bar at the top, an events view area, and a few other areas for customization.

Dashboards display results from a variety of different searches, typically using results modules. A search view contains a set of search modules. The search passes through any number of modules, displaying results in one or more results modules. You can add other modules to dashboard views and search views as necessary.

You can use a views CSS to modify the appearance of a view. For example, to float a module next to another module, or move one module below another module. For more information about how to change CSS for a view, see Customize CSS in this manual.

Basic steps for configuring a view

Here's a general outline of the basic steps for configuring views:

1. Decide which modules to include in your view.

2. Configure each module in <view_name>.xml.

3. Put <view_name>.xml in the views directory, inside your app directory. Use either of the following two locations:

$SPLUNK_HOME/etc/apps/<app_name>/local/data/ui/views/
$SPLUNK_HOME/etc/apps/<app_name>/default/data/ui/views/

Note: Be careful about using the default directory.

If you are creating your own app, then use the default directory.

If you are customizing an app shipped with Splunk (for example, the search app), or an app you installed from another source, use the local directory. If you used the default directory in this case, your changes could be overwritten by an update to the app.

4. If you have more than one view for your app, arrange them in the UI by following the instructions in Build navigation.

5. To change the CSS for a view, Customize CSS.

Useful URIs for view building

Here are some URIs that provide useful information about your system when building a view. These are especially useful when building views through the file system, and not using Splunk Manager.

Tools available with info

By far, the most useful toolset for building views for Splunk is the info endpoint available. This page offers a list of all available modules, RelaxNG schemas for view building, and many other utilities.

http://localhost:8000/info

Show source

http://localhost:8000/en-US/app/<app_name>/<view_name>?showsource=true

Use this endpoint to view the implementation of the underlying advanced XML for a view. The advanced XML is available in a tree view and as source code. You use this endpoint to convert simple XML to advanced XML.

Module reference

This endpoint provides a list of all advanced XML modules, sorted alphabetically. Compare with the Module Reference, available in this manual, sorted by functionality.

http://localhost:8000/modules

Display a new view

Use this endpoint to a view newly added to a Splunk instance.

https://localhost:8089/services/apps/local?refresh=true 

Reload a specific view

Use this endpoint to refresh a specific view in Splunk Web.

https://localhost:8089/services/apps/local/<appname>?refresh=true 

Use this endpoint to refresh a specific view in Splunk Web.

Reload all views

Reload all views for the specified app.

http://localhost:8000/app/<appname>/

Reload nav

Reload the navigation menu in Splunk Web.

https://localhost:8089/servicesNS/admin/<appname>/data/ui/nav?refresh=1

About editing XML

Here are a few suggestions about editing XML files for Splunk views.

Special characters in XML files

Some characters have special meaning in an XML file and cannot be used literally. You can wrap the text within CDATA tags as illustrated below. The XML parser does not process text within CDATA tags.

<![CDATA[
 <code>"Text within a CDATA tag"</code>
]]>

Or you can escape these characters using HTML entities:

Character	HTML Entitiy
"	"
'	'
<	&lt;
>	&gt;
&	&amp;

Schemas and editors

Splunk recommends that you use an XML editor that understands XML schemas. Schemas are useful for validating XML and also provide guidelines for building an XML file.

Many XML editors let you load a schema -- DTD, XSD, Relax, RelaxNG are just a few different types of schemas. Splunk contains RelaxNG formatted schemas for views, from dashboards to form searches to advanced XML views.

Read more about how to use Splunk's schemas in the Use XML schemas topic in this manual.

Nesting modules

With advanced XML, you often nest child modules several levels deep. It is a good idea to use consistent indentation and commenting to make sure you properly close parent modules.