Build a search view using advanced XML

Important notice: The Advanced XML dashboard framework is officially deprecated. For more information, see Advanced XML Deprecation.

Search views are similar to the view in Splunk's default Search app. A search view presents a search bar to users, and displays events or search results. Search views also have a specific layout. This topic provides a step-by-step procedure showing how to use advanced XML to build a search view and introduces the search view layout.

For more information, see the Module System Reference.

Configure the search view

1. Decide which modules you want to include in your view.

2. Create a view XML file <view_name>.xml, either through Splunk Manager, or in the views directory, inside your app directory:

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

Note: Use the app's local directory to avoid overwriting your changes when an app is updated. When creating your own app, you might want to use the app's default directory.

3. Configure each module in your view's XML file. Set parameters for each module and layoutPanels for parent modules.

4. If you have more than one view for your app, arrange them in the UI.

Open the view.xml file for editing

If you are creating a new view XML file, <view_name>.xml, add the following tags:

<view>
</view>

Name your view

Use the label tag to give the view a descriptive name.

<view>
  <label>Basic Search View</label>

Add chrome

Typically, you add the top navigation modules AccountBar and AppBar.

<view>
  <label>Basic Search View</label>

  <!-- top nav chrome -->
  <module name="AccountBar" layoutPanel="appHeader"/>
  <module name="AppBar" layoutPanel="navigationHeader"/>

</view>

Set params

Modify module parameters to customize your view. For example, you can remove the app drop-down by setting a param for the AccountBar. The following XML creates a view that doesn't have the link to Manager or the app drop-down menu in the upper right-hand corner:

<view>

  <!-- top nav chrome -->
  <module name="AccountBar" layoutPanel="appHeader">
    <param name="mode">lite</param>
  </module>
  <module name="AppBar" layoutPanel="navigationHeader"/>

</view>

Each module recognizes a specific set of parameters, as listed in the Module Reference.

Specify layout panels

The layoutPanel attribute to <module> defines where to display a module in a view. There are different layout panels for each part of the view, and different layout panels for different types of views. It's a good idea to familiarize yourself with the different layout panels to understand how to best display modules in a view.

Chrome layout panels

Here are the layout panels for chrome:

Module	Description
messaging	Use this layoutPanel for messaging modules.
appHeader	Contains all the overall links for the AccountBar.
navigationHeader	Use this layoutPanel for the AppBar module, which contains navigation for the app.
viewHeader	viewHeader is a header panel for a view. You can put a view TitleBar in this panel.

Add the search bar

A basic search view shows the search bar:

To build this view, use the SearchField module -- this module creates the search bar. You can prepopulate this module with search terms, but leave it blank for now:

<view>
  <label>Basic Search View</label>

  <!-- top nav chrome -->
  <module name="AccountBar" layoutPanel="appHeader"/>
  <module name="AppBar" layoutPanel="navigationHeader"/>

  <!-- This module renders the search box -->
  <module name="SearchBar" layoutPanel="mainSearchControls">
  </module><!-- close SearchBar module -->

</view>

Search module layout panels

The following layout panels are useful for search modules:

Module	Description
splSearchControls-inline	Aligns search modules next to each other in columns. The first module expands to occupy space not occupied by the other modules.
mainSearchControls	Aligns search controls one after another, typically using a vertical alignment.

There are additional search modules.

Add the results display area

Add the EventsViewer module to display search results. A user can drill down from the events displayed.

<view>
  <label>Basic Search View</label>

  <!-- top nav chrome -->
  <module name="AccountBar" layoutPanel="appHeader"/>
  <module name="AppBar" layoutPanel="navigationHeader"/>

  <!-- Renders the search box -->
  <module name="SearchBar" layoutPanel="mainSearchControls">

    <!-- Renders the resulting events from your search -->
    <module name="EventsViewer"/>

  </module><!-- close SearchBar module -->

</view>

The SearchBar module contains the EventsViewer module, which means EventsViewer is a child of SearchBar – EventsViewer can access the search from the search bar. Child modules inherit the layoutPanel settings, as well.

Tip: Using 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.

Results layout panels

There are a number of results modules.

Results modules look best when placed in the following layout panels.

Module	Description
fullWidthControls	Use this layout panel for results that take up the whole width of the view, such as serverSideInclude or other web resources.
graphArea	Use this panel for the FlashTimeline module.
sidebar	Use this panel to display the FieldPicker and SuggestedFieldView modules.
resultsHeaderPanel	Add a header to your results with the ResultsHeader module.
pageControls	Put Paginator and page control modules here.
resultsAreaLeft	Display your results here with the EventsViewer module.
resultsAreaRight	Add a secondary area to display results to the right of resultsAreaLeft.
resultsOptions	This is a pop-up layer and shows up as a link to Options from within pageControls.

Add pagination

Add a Paginator module to allow users to page through results spread over two or more pages.

<module name="Paginator">
    <param name="entityName">events</param>

The entityName parameter is required for the Paginator module. This module also accept several optional parameters.

The Paginator module completes the example. Here is a listing of the complete search view.

<view>
  <label>Basic Search View</label>

  <!-- Top nav chrome -->
  <module name="AccountBar" layoutPanel="appHeader"/>
  <module name="AppBar" layoutPanel="navigationHeader"/>

  <!-- Begin SearchBar: renders the search box -->
  <module name="SearchBar" layoutPanel="mainSearchControls">

    <!-- Begin Paginator: provides for paging through the results of the search -->
    <module name="Paginator">
      <param name="entityName">events</param>

        <!-- EventsViewer: Display search results -->
  	<module name="EventsViewer"/>
    </module> <!-- End Paginator module-->
  </module> <!-- End SearchBar module -->
</view>