
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">
?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 thedefault
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 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 |
---|---|
|
"
|
|
'
|
|
<
|
|
>
|
|
&
|
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.
PREVIOUS Use cases for this manual |
NEXT Build a search view using advanced XML |
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18
Feedback submitted, thanks!