About advanced XML
Important notice: The Advanced XML dashboard framework is officially deprecated. For more information, see Advanced XML Deprecation. |
This section provides an introduction to building views using advanced XML. It describes basic concepts and provides some example views.
Simple XML and the Splunk Dashboard Editor
Before building a view using advanced XML, you may want to start with the 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=advanced
- Caution: Not all features available in simple XML are available in advanced XML.
Views
Splunk software builds views from XML files stored in an App's view directory. Views are made out of a library of ModuleSystem. 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 are not available in simple XML.
Modules
Every element in a Splunk view, from the search bar to the results, derives from a 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. Splunk Web 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. For example:
<module name="Message"> <param name="filter">*</param> </module>
Some module 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 the URL of any view 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 .
Most results modules are dispatching modules. If a results module does not 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 Enterprise layout templates define page layout, or how each element fits into a page. You can find the 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 CSS to modify the appearance of a view. For example, you can modify the CSS 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 to configure a view
The basic steps to configure a view are:
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, use the
default
directory.
- If you are customizing an app shipped with Splunk Enterprise (for example, the search app), or an app you installed from another source, use the
local
directory. If you use thedefault
directory in this case, your changes can be overwritten by an update to the app.
4. If you have more than one view for your app, arrange the views in the UI.
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 Web.
Tools available with info
The most useful toolset for building views is the info endpoint. This page offers a list of all available modules, RelaxNG schemas for building views, 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.
http://localhost:8000/modules
Display a new view
Use this endpoint to access a view that is newly added to a Splunk Enterprise 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 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
It it best to 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 Enterprise contains RelaxNG formatted schemas for views, from dashboards to form searches to advanced XML views.
Read more about how to use the Splunk Enterprise 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 ensure that you properly close parent modules.
Developer resources | Build a search view using advanced XML |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9
Feedback submitted, thanks!