Low Search

Parameters in Low Search

Low Search uses both native and its own parameters to generate search results. All these parameters can be applied in two ways: as input fields in a Form, or as hard-coded parameters in the Results or URL tag. The values of these parameters can always be shown inside a Low Search tag by using the parameter name as a variable, prefixed with low_search_.

So, any parameter:

param_name="param_value"

Is equal to:

<input name="param_name" value="param_value">

And the param_value can be shown with:

{low_search_param_name}

For example, take a look at these parameters, input fields and variables:

channel="news" search:featured="yes"

<input type="hidden" name="channel" value="news">
<input type="checkbox" name="search:featured" value="yes" checked>

{low_search_channel}
{low_search_search:featured}

Note: Use input fields if you want the value of the parameter to be user defined or logged to the Search Log. Use hard-coded parameters if you want the value to be fixed.

Multiple values

In ExpressionEngine, multiple values of a parameter are usually separated by a vertical bar |. This can also be translated into input fields, as long as the parameter name has square brackets ([]) appended to it. Then the same principle applies:

category="2|4|6" search:number="one|three"

<select name="category[]" multiple>
  <option value="1">Category One<option>
  <option value="2" selected>Category Two<option>
  <option value="3">Category Three<option>
  <option value="4" selected>Category Four<option>
  <option value="5">Category Five<option>
  <option value="6" selected>Category Six<option>
</select>

<input type="checkbox" name="search:number[]" value="one" checked> One
<input type="checkbox" name="search:number[]" value="two"> Two
<input type="checkbox" name="search:number[]" value="three" checked> Three

{low_search_category}
{low_search_search:number}

Note: do not include the square brackets in the variable names.

Inclusive values

The example above will filter results by any of the values given. However, ExpressionEngine also allows you to filter by all of the values, by separating them with an ampersand (&) rather than a vertical bar. Low Search also caters for this, using the require_all parameter, which takes any amount of parameter names as its value. For example:

category="2&4&6" search:number="one&&three"

This is equal to:

category="2|4|6" search:number="one|three" require_all="category|search:number"

<select name="category[]" multiple>
  <option value="1">Category One<option>
  <option value="2" selected>Category Two<option>
  <option value="3">Category Three<option>
  <option value="4" selected>Category Four<option>
  <option value="5">Category Five<option>
  <option value="6" selected>Category Six<option>
</select>

<input type="checkbox" name="search:number[]" value="one" checked> One
<input type="checkbox" name="search:number[]" value="two"> Two
<input type="checkbox" name="search:number[]" value="three" checked> Three

<input type="hidden" name="require_all" value="category|search:number">

{low_search_category}
{low_search_search:number}
{low_search_require_all}

Exclude values

ExpressionEngine also allows you to exclude values, by prepending not  to the parameter value, which negates the value. Low Search also caters for this, using the exclude parameter, which takes any amount of parameter names as its value. For example:

category="not 2|4|6" search:number="not one|three"

This is equal to:

category="2|4|6" search:number="one|three" exclude="category|search:number"

<select name="category[]" multiple>
  <option value="1">Category One<option>
  <option value="2" selected>Category Two<option>
  <option value="3">Category Three<option>
  <option value="4" selected>Category Four<option>
  <option value="5">Category Five<option>
  <option value="6" selected>Category Six<option>
</select>

<input type="checkbox" name="search:number[]" value="one" checked> One
<input type="checkbox" name="search:number[]" value="two"> Two
<input type="checkbox" name="search:number[]" value="three" checked> Three

<input type="hidden" name="exclude" value="category|search:number">

{low_search_category}
{low_search_search:number}
{low_search_exclude}

SQL parameters

As per version 3.4.0, Low Search supports SQL parameters. This means you can use a SQL query in any pararameter. SQL queries are limited to SELECTs only and should always end with a semi-colon (;). Low Search will take the first item in the SELECT statement and creates a pipe-separated list from it. If the SQL query produces no results, it sets the parameter value to what comes after the semi-colon. You can optionally prefix the SQL query for better matching. Schematically, such a query looks like this:

param="prefix SELECT field FROM table WHERE lorem = 'ipsum';no results"

Valid prefixes are: =, not, =not, >, <, >=, and <=.

Note: SQL queries are only allowed in hard-coded parameters.

Examples

Display products with a price higher than the overall average price:

{exp:low_search:results
  channel="products"
  search:price="> SELECT AVG(field_id_5) FROM exp_channel_data WHERE channel_id = 3;"
  orderby="price"
}

Display articles where the selected author (based on a relationship field) is not Closed. Don’t display anything if all authors are Closed:

{exp:low_search:results
  channel="articles"
  child:author="SELECT entry_id FROM exp_channel_titles WHERE channel_id = 4 AND status != 'closed';-1"
}

IN conditionals (EE 2.8.1 and down)

In EE 2.8.1 and below, Low Search supports special IN conditionals to help you deal with multi-valued variables. An IN conditional looks something like this:

{if variable IN (1|2|3)} ... {/if}

This is particularly useful if you’re using nested tags for additional parameters, like categories. For example, to generate the category options used in the examples above, use this:

<select name="category[]" multiple>
  {exp:channel:categories channel="news" style="linear"}
    <option value="{category_id}"{if category_id IN ({low_search_category})} selected{/if}>
      {category_name}
    <option>
  {/exp:channel:categories}
</select>

Note: this syntax will throw errors in EE 2.9.0+. You can use Regular Expression conditionals instead.

Regular Expression conditionals (EE 2.9.0 and up)

In EE 2.9.0 and higher, the same as the IN conditionals can be achieved with native conditionals using the Matches Operator. The best way to approach this, would be like this:

{if pipe_separated_items ~ '/(^|\|)'.single_item.'($|\|)/'} ... {/if}

The pipe_separated_items and single_item variables should be written without curly braces. The latter is part of the regular expression using the string concatenation operator. Using regular expression conditionals, the above example would be written like this:

<select name="category[]" multiple>
  {exp:channel:categories channel="news" style="linear"}
    <option value="{category_id}"{if low_search_category ~ '/(^|\|)'.category_id.'($|\|)/'} selected{/if}>
      {category_name}
    <option>
  {/exp:channel:categories}
</select>