Simple form search

Simple form search

Use simple form searches to create a simplified search interface. Form searches let you alias out pieces of your search as tokens, so users only need to type in a search term for each token. For example, here's a form search from the Sample App:

This page tells you how to build a basic form search using simplified XML. For more information on form searches, read the form search intro. If you're working with Splunk's advanced XML syntax, you can build an advanced form search.

Configuration

Simple form searches are built on the same simplified XML as the simple dashboards. You can use the same XML configuration that dashboards use in your form search XML, with a few added elements to take form input.

First, use the searchTemplate attribute to create the search that runs behind the form. Then put dollar signs around the term (or terms) that will get user input:

<searchTemplate>put your search here $term$</searchTemplate>

You can put any kind of search here, as long as you surround the term that you want to replace via the form with $.

Then, to add a form to your page, wrap an input type attribute with a fieldset element:

<fieldset>
        <input type="text" token="username" />
</fieldset>

This will create a form in your page to take user input.

For example, this snippet creates a form that takes in a value of username:

<form>
    <label>My form search</label>
    <searchTemplate>$username$</searchTemplate>

    <fieldset>
        <input type="text" token="username" />
    </fieldset>
    
...

</form>

More form options

There are more options for configuring forms. Set any of these options as additional elements within the input type element.

add a label

Add a label to your form. Use this to add hints or explanation so your users know what kinds of search terms to input. To add a label, use the label attribute.

This example adds Enter a user name before the form:

<input type="text" token="username">
    <label>Enter a user name</label>
</input>

set a default search term

By default, if the user does not fill in the text box when submitting values, the token will be replaced with an empty string. You can change this behavior by setting a default value to fill in the field, or fields, of your form search. To set a default value, use the default attribute.

This example sets Juliet as the default username:

<input type="text" token="username">
    <default>Juliet</default>
</input>

add a prefix or suffix

Your search terms may require additional suffixes or prefixes. Use the prefix and suffix attributes to add additional terms to your search. These will only be added on if a user enters a search into the form.

Set a prefix on your default value:

<input type="text" token="username">
    <prefix>username=</prefix>
</input>

Or quote your default value:

<input type="text" token="username">
    <prefix>username="</prefix>
    <suffix>"</suffix>
</input>

pre-populate form

You may want to pre-populate a form with To pre-populate the form upon loading the page, use the seed attribute.

This example will load a form with the username Jack already in the form:

<input type="text" token="username">
    <seed>Jack</seed>
</input>

Display results

Form searches output results using any of the panels available for simple dashboards.

events

If you just want to display a list of events, add an events node to your form search. For example:

<form>
    <label>Username</label>
    
    <searchTemplate>sourcetype=logins $username$</searchTemplate>
    
    <fieldset>
        <input type="text" token="username" />
    </fieldset>
    
    <row>
        <event>
            <option name="count">100</option>
        </event>
    </row>
</form>

Examples

Here are some more advanced examples using the simplified form search XML.

Multi-search form layout

Form searches can be much more interesting when pairing multiple output panels with a common set of inputs. By relocating the searchTemplate nodes out of the top level hierarchy and into each output panel, a composite form search can be made:

<form>
  <label>Form search example 3 - inverted flow, panel-defined search</label>

  <fieldset>

      <!-- define a common form search input that will be used by all panels
          below that implement a searchTemplate node -->
      <input type="text" token="username">
          <label>Global username</label>
          <default>NON_EXISTENT</default>
          <seed>johnvey*</seed>
      </input>

      <input type="time" />

  </fieldset>

  <row>
      <chart>
          <title>Commits over time</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | timechart count</searchTemplate>
          <option name="charting.chart">area</option>
      </chart>
      <table>
          <title>Top files touched by the user</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | top filePath</searchTemplate>
      </table>
  </row>

  <row>
      <table>
          <title>Users vs changetype</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | ctable user changetype maxcols=4</searchTemplate>
          <option name="count">20</option>
      </table>
      <chart>
          <title>Average lines added by the user</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | timechart avg(added)</searchTemplate>
          <option name="charting.chart">line</option>
          <option name="charting.legend.placement">none</option>
      </chart>
  </row>

</form>

The above form search will dispatch 4 separate searches, though each search will use the user-entered value provided in the fieldset section. Obviously, the token attribute of each distinct search must match with at least one of the input nodes defined within the fieldset.

Single-search, multi-post process

Finally, a special permutation of form searches can take a single search and display different facets of that search through post-processing. For example, the previous example of 4 searches can be combined into 1 search by:

<form>
  <label>Form search example 4 - inverted flow, panel-defined post-process</label>

  <!-- define a search that returns, in one result set,  all of the data that is 
    needed by the subsequent panels -->
  <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | head 10000</searchTemplate>

  <fieldset>

      <input type="text" token="username">
          <label>Global username</label>
          <default>NON_EXISTENT</default>
          <seed>johnvey*</seed>
      </input>

      <input type="time" />

  </fieldset>

  <row>
      <chart>
          <title>Commits over time</title>
          <searchPostProcess>timechart count</searchPostProcess>
          <option name="charting.chart">area</option>
      </chart>
      <table>
          <title>Top files touched by the user</title>
          <searchPostProcess>top filePath</searchPostProcess>
      </table>
  </row>

  <row>
      <table>
          <title>Users vs changetype</title>
          <searchPostProcess>ctable user changetype maxcols=4</searchPostProcess>
          <option name="count">20</option>
      </table>
      <chart>
          <title>Average lines added by the user</title>
          <searchPostProcess>timechart avg(added)</searchPostProcess>
          <option name="charting.chart">line</option>
          <option name="charting.legend.placement">none</option>
      </chart>
  </row>

</form>

The searchPostProcess node inside each panel instructs the form search to take the final search results and rerun them through a separate search pipeline. The basic model is to have a non-transforming search seeded in the searchTemplate node, and then apply transforming searches in the searchPostProcess nodes.

• Was this topic useful?
• Post a comment