What is an intention?

Right now that description could use some improvement. I'll send an email and over the short term this question, answer and that page will likely evolve a bit.

Intentions are an abstraction layer that allows the UI to make a common subset of search-language modifications to any given search string, without having to have any language-parsing code on the client.

Modules can contribute to the user's eventual search in a number of ways:

1. modules can change out the underlying 'base search' string (SearchBar, HiddenSearch, HiddenSavedSearch do this),
2. they can add or modify or clear the intentions that live on top of that 'base search' (SearchSelectLister, basically all 'form search' modules do this),
3. they can add or modify time ranges (TimeRangePicker as well as HiddenSearch, HiddenSavedSearch),

that's about it as far as altering the search that eventually gets run.

To give some specific examples of intentions:

a) an 'addterm' intention can be used to safely add either "foo" or foo="bar" to the search, and it can also specify whether the term should be added to the first search clause, or added at the end after any renames/rex clauses etc..

b) a 'toggleterm' intention is rarely useful to third party developers but very central to the splunk UI - it is much like addterm except that if it finds the corresponding search language piece is already there it will remove it instead of adding it.

c) the 'plot' intention can do common permutations of top/rare/timechart and is what power's report builder's 'basic' mode.

d) the 'stringreplace' intention allows you to turn a selected element from the UI into a specific string in a specific place in the underlying search string. This intention breaks the normal intention model in that 1) it requires special matching syntax to be present in the underlying search string (ie $foo$), 2) its thus impossible to run the operation in reverse, ie to 'decompose' a search string into a smaller base search plus some 'stringreplace' intentions. In short although the concept behind stringreplace is a lot more familiar and simpler, the configuration for it is quite complicated and its best to use it as an advanced tool when 'addterm' cant be used. Examples of this would be when you need to replace tokens in a subsearch, or replace tokens in another command like transaction.