Super Search 3.x

Legacy documentation for Super Search 3.x.

POST, GET, or Template?

With many different options for generating search results, you might be wondering what the best way to go is. This page gives you some insight on each of the available methods, and will give you a better understanding of how each works, and what's best for your scenario.

Available Methods

On a page with a Super_Search:Results loop, Super Search looks for search parameters in 3 locations to refine the search parameters. You can supply search parameters via any (or mixes) of:

  • Template parameters
  • POST data
  • GET data

All the parameters listed here are available to all the various methods.

Common Usage

The most common usage of this is to have a Results loop on a results page with some basic setup and limits for the search set, and then use any passed POST or GET data to refine the search data. For example, a common results page may have the markup:

{exp:super_search:results
    channel="news"
    limit="20"
    hightlight_keywords="strong"
}
    <div class="entry">
        <h3>{title}</h3>
        {excerpt}
    </div>
{/exp:super_search:results}

With a search form like:

{exp:super_search:form
    return="supersearch/results"
}
    <label for="keywords">Keywords</label>
    <input type="text" name="keywords" id="keywords" />
    <input type="submit" value="Search!" />
{/exp:super_search:form}

Super Search automatically redirects the POST search query into a query string in the URI. When that search form is submitted, it returns to a URI that would look something like:

/search&keywords=test

The Results loop would run a search using the keywords value from the POST data along with the parameters that are set on the Results tag (ex: limiting to 20 entries within the news channel).

Parameter Method Precedence

It is possible to pass the same parameter multiple times via different methods. For example, a keywords value can be passed on a POST URI as well as being hardcoded within the Results tag. In that case, the parsing follows cascading method to filter the actual parameter that will get used.

  1. Initially template data is parsed and sets some baselines.
  2. Next POST data is parsed.
  3. Finally GET data is parsed.

At each stage, any parameters that have not already been passed via a previous method are either filtered down, added to the search set, or in certain cases ignored.

Why Does It Work That Way?

When Params Are Ignored

Take for instance the channel parameter. If no channel parameter is supplied anywhere, Super Search will search over all the possible channels. In reality you'll probably want to limit it to search over just a few channels, so you might add this to your Results tag:

channel="news|products"

Once the channel parameter is set via a template parameter, it gets special treatment. So if a user went to a URI like:

/search&keywords=secret&channel=secret_channel

Super Search detects that the channel parameter has already been set via a template parameter, and secret_channel isn't a valid option from those set, and ignores it completely from the POST data.

When Params Are Filtered

Similar to the above, assume a channel parameter is set in the template parameters. If the specific data set was similar to the below code, Super Search will limit the search set to the news, products and blog channels:

channel="news|products|blog"

You may wish for a user to have the option to limit their searches to a specific channel, so present them with the option in the search form for channels, and they end up with a URI similar to:

/search&keywords=test&channel=news

Even though the channel parameter has already been parsed, when Super Search looks to parse the POST data and see's that there is a duplicate channel parameter, additional filtering kicks in. As the passed value news exists in the valid set of channels supplied via template parameter, the search set is reduced to only act upon the news channel.

This kind of filtering is limited to senstive parameters such as channel, site, status and a few others. Full parameter options are available in the documentation.

Template Parameters

When building your Results loop, specifying the parameters in the loop gives you the highest precedence. Anything you supply directly in the Results tag takes highest priority.

Some params set via template parameters take control over everything. For example, supplying search parameter via a template param will halt the parsing of any other passed variables via POST or GET.

Some params set via template parameters however, can be overwritten by passed variables via POST and GET. For example, supplying an orderby or limit param via POST or GET will override the orderby or limit template parameters in the Results tag.

POST

Passing search params via POST is the easiest way to get going. As mentioned above, Super Search automatically redirects the POST search query into a query string in the URI. The searches each have a unique URI and users can easily bookmark specific pages and are free to manipulate the search query in the URI even further. A major advantage POST has over GET is the ability to pass a search parameter as an array. These arrays can be very useful when building more advanced searches. Using array's you can allow filtering to specific sets of categories. See GET explanation below for more information.

GET

You can also pass parameters via GET which will result in a unique URI which can easily be tracked with Google Analytics. Users can also bookmark specific pages and are free to manipulate the search query in the URI even further. It's important that you append an additional segment of "search" in your return URL for GET to work (so your results page should be something like http://site.com/template_group/template_name/search?keywords=pie).

GET does have it's limitations. As mentioned above, it is impossible to pass search arrays via GET. For example:

{exp:super_search:form
    return="supersearch/results/search"
    method="get"
}
    <label for="category_one">Category One</label>
        <input type="checkbox" name="category[]" id="category_one" value="1"/>
    <label for="category_two">Category Two</label>
        <input type="checkbox" name="category[]" id="category_two" value="1"/>
    <label for="category_three">Category Three</label>
        <input type="checkbox" name="category[]" id="category_three" value="1"/>
    <input type="submit" value="Search"/>
{/exp:super_search:form}

Will return an "Invalid GET Data - Array" error. This is part of EE's core URI parsing safety mechanisms and there's no way around it. For the case you want to pass array's of data, you have to use a POST.