Super Search 2.x

Legacy documentation for Super Search 2.x.

This function allows you to display a list or "cloud" of all terms searched upon over time. It will show all popular search terms and if desired, let you show a weighted cloud, where more popular search terms appear larger than less popular search terms.

If you wish to use the weighted cloud method: the number of times the most popular search term is used establishes the top of the scale, with 0 as the bottom. You can specify the number of groups into which your search terms will be sorted. Each of your search terms will be evaluated as to which group they belong in. They will be given a numerical ranking based on this. CSS styling is then used to convert that number value into a font size.

For example, imagine you have 3 terms that were searched upon on your site: apple, orange and pie. You specify that you want to show a cloud with 3 groups. If apple was searched 12 times, orange 7 times, and pie 1 time, the top of your scale will be 12. apple will get the highest rank and the largest font size. pie will get the smallest ranking and font size. orange will get the middle font because it falls into the middle grouping. The range for falling into the lowest group would be 0-4. For the middle, 5-8. And for the top, 9-12.

{exp:super_search:cloud} content {/exp:super_search:cloud} 

Parameters

The following parameters are available for use:

groups=

groups="5" 

This parameter tells the search cloud how many groups to divide your search terms into. For example, if you specify 5, it will create 5 groups and place the search terms into the appropriate group based on their popularity. This will determine the font size for each tag. Defaults to 5.

start=

start="10" 

This parameter controls which integer of font size to start counting. This affects the size variable which sets the font size of each search term in your cloud. Defaults to 10.

step=

step="2" 

This parameter controls the amount to increment the size variable. This allows you to create greater differences in font sizes between search term popularity groups. Defaults to 2.

day_limit=

day_limit="5" 

Using this parameter, you can filter your list of search terms by those which have been searched upon within the last number of days. Defaults to none.

start_on=

start_on="2011-12-20 14:00" 

Using this parameter, you can filter your list of search terms by those which have been searched upon within the specified date range. The date/time must use this format: YYYY-MM-DD HH:MM. Used in conjunction with the stop_on parameter. Defaults to none.

stop_on=

stop_on="2012-01-20 14:00" 

Using this parameter, you can filter your list of search terms by those which have been searched upon within the specified date range. The date/time must use this format: YYYY-MM-DD HH:MM. Used in conjunction with the start_on parameter. Defaults to none.

site_id=

site_id="3" 

The parameter allows you to filter the list of search terms and their popularity by MSM sites the terms were searched upon. Separate multiples with the pipe character (|), or specify all to look across all sites. Defaults to current site.

fixed_order=

fixed_order="81|17|26|43" 

This parameter allows you to optionally override the results and set them into a fixed order by specifying term ID's. Separate multiples with the pipe character (|).

term=

term="cheese|pie|corn" 

This parameter allows you to filter down your list of search terms results by specifying search terms. Separate multiples with the pipe character (|).

term_id=

term_id="12|82|48" 

This parameter allows you to filter down your list of search terms results by specifying ID's of search terms. Separate multiples with the pipe character (|).

exclude_term=

exclude_term="burger|hammy|pimpkins" 

This parameter allows you to exclude specific search terms from your results, using the search term. Separate multiples with the pipe character (|).

exclude_term_id=

exclude_term_id="34|234|89" 

This parameter allows you to exclude specific search terms from your results, using the search term ID. Separate multiples with the pipe character (|).

limit=

limit="20" 

This parameter is available to limit the amount of results in the cloud. Defaults to 20.

most_popular=

most_popular="no" 

By default, the results in the cloud/list are filtered to contain the most popular search terms, when used in conjunction with the limit parameter. So for example, if you have 50 search terms, and you have a limit set to 20, the top 20 most popular search terms will be displayed, and then ordered by the value in the orderby parameter. This is more beneficial when ordering your results by anything other than count. To disable this behaviour, call this parameter and specify a value of no. Defaults to yes.

paginate=

paginate="both" 

Pagination works just like it does in the Channel:Entries tag. When specified, and used in conjunction with the super_search_paginate variable pair, pagination will display. Refer to Channel:Entries tag documentation for more information.

orderby=

orderby="term" 

This parameter allows you to order your search terms by the method you wish. Default method is count. Available methods are:

  • term - alphabetical
  • count - number of times the term has been searched for
  • first_seen - the date which the term was first searched upon
  • last_seen - the date which the term was most recently searched upon
  • entry_count - the number of times the term appears in the site(s) data
  • random - randomly selects one of the above methods

sort=

sort="asc" 

This parameter allows you to sort search terms by ascending (asc) or descending (desc) order. Default is desc.

backspace=

backspace="2" 

In the event you wish to trim the last few characters from the results, you would specify this parameter. For example, if you have a comma-seperated list of search terms, you would have ,[space] formatting within the template tag. If you specify 2 in the backspace parameter, it will trim off the last ,[space] when the template parses.

searched_only=

searched_only="no" 

This parameter lets you choose whether you want words that have NOT been searched upon yet show up in the results. By default, the Cloud tag will not show words not searched on. To display these words, specify this parameter with a value of no.

Variables

The following variables are available for use:

super_search_term

{super_search_term} 

This variable returns the search term.

super_search_term_id

{super_search_term_id} 

This variable returns the ID of the search term.

super_search_total_searches

{super_search_total_searches} 

This variable will return the total number of times the given term has been searched upon.

super_search_first_seen

{super_search_first_seen format="%F %j, %Y"} 

This variable returns the date of when the given term was first searched by someone. Use standard date variable formatting for this variable.

super_search_last_seen

{super_search_last_seen format="%F %j, %Y"} 

This variable returns the date of when the given term was most recently searched by someone. Use standard date variable formatting for this variable.

super_search_site_id

{super_search_site_id} 

This variable will display the MSM site(s) that had this term searched upon.

super_search_size

{super_search_size} 

This variable will return the group number the search term is part on, based on the popularity of the search term (determined by the groups parameter).

super_search_step

{super_search_step} 

This variable relates to the step parameter. It helps you represent the breakpoints between groups of search terms by their popularity. The usual usage for this is to set different font sizes of the search terms to create the "cloud" effect.

super_search_count

{super_search_count} 

This variable will return the relative position number of the search term within the list of results.

super_search_absolute_count

{super_search_absolute_count} 

This variable will return the absolute position number of the search term across all pages of results.

super_search_total_results

{super_search_total_results} 

This variable will return the total amount of search term results being displayed in the results of the cloud on the current page. You would typically use this in a conditional statement.

super_search_absolute_results

{super_search_absolute_results} 

This variable will return the total amount of search term results across all pages in the results of the cloud on the current page.

super_search_switch

{super_search_switch="style_1|style_2"} 

This variable will alternately output each of the multiple values you provide. You would typically use this with CSS.

Variable Pairs

The following variable pairs are available for use:

super_search_paginate

{super_search_paginate}
    Page {super_search_current_page}
    of {super_search_total_pages} pages
      {super_search_pagination_links}
{/super_search_paginate}

Pagination is available for this tag and works just like regular EE pagination, but each variable/variable pair is prepended with super_search_ (except for any variables/variable pairs inside of the super_search_pagination_links variable pair). Used in conjunction with the paginate parameter.

Conditionals

Most of the variables above are available for use as conditionals. Additionally, the following conditional is available for use:

super_search_no_results

{if super_search_no_results}
    Sorry, no results were found.
{/if}

This conditional displays it's contents when there are no results found.

Examples

The following are a few different examples of how you can use this tag:

Popular Search Terms Cloud

Below is a simple typical usage of the search cloud in "cloud" format:

<div id="cloud">
    {exp:super_search:cloud
        start="15"
        groups="10"
        step="3"
        limit="25"
        orderby="term"
        sort="asc"
    }
        <a  href="{path='search/results/search&keywords={super_search_term}'}"
            style="font-size:{super_search_step}px;">
            {super_search_term}
        </a>
    {/exp:super_search:cloud}
</div>

Popular Search Terms List

You could also display your search term results in list form if you wish. You can also keep font size weighting in place, but is removed from the example below:

<ul>
    {exp:super_search:cloud
        limit="25"
        paginate="both"
    }
        <li>
            <a href="{path='search/results/search&keywords={super_search_term}'}">
                {super_search_term}
            </a>
            ({super_search_total_searches})
        </li>
        {if super_search_no_results}
            <li>Sorry, no results were found.</li>
        {/if}
        {super_search_paginate}
            <li>
                Page {super_search_current_page} of
                {super_search_total_pages} pages &nbsp;
                {super_search_pagination_links}
            </li>
        {/super_search_paginate}
    {/exp:super_search:cloud}
</ul>