ExpressionEngine | How to Use Search Results Module

User Documentation

Search Results

Installation

For 2.1.x

You install the Search Results module with the standard Expression Engine 2.x method.

Download your copy of the module.
Extract the folder and files from the archived (zipped) file.
Open the EE2 directory
Copy the entire "key_search" folder to your third_party folder located at:

/YOUR SYSTEM DIRECTORY/expressionengine/third_party/

For 1.6.x or 1.7.x

You install the Search Results module with the standard Expression Engine 1.6.x/1.7.x method.

Download your copy of the module.
Extract the folder and files from the archived (zipped) file.
Open the EE1 directory
Upload the "key_search" folder to the modules folder inside your system directory.

/YOUR SYSTEM DIRECTORY/modules/

Upload language/english/lang.key_search.php to:

/YOUR SYSTEM DIRECTORY/language/english/

Navigate to CP Home | Modules, find the Key Search module and click Install.

Using the Template Tags

Search Forms in Templates

This module uses the queries that are generated and cached by by the EE default search module (simple and advanced search forms) that ships with ExpressionEngine. You can find the 1.7.x Search Module documentation here. The 2.x documentation is here.

Search Results in Templates

Result sets can be embedded into templates with a simple tag pair:

{exp:key_search:results}
	Your HTML and EE field tags
{/exp:key_search:results}

Parameters

The following parameters are available to use in the primary tag pair to configure the way the records are returned to the template. Here is an example using some basic parameters:

{exp:key_search:results groupby='channel' group_repeat='no'}
	HTML and EE field tags
{/exp:key_search:results}

Parameter	Values	Description	Default
switch	string	Allows you to set two or more values that will alternate between the result set rows. It accepts a string with one or more strings separated by '\|' character.	NULL
groupby	all fields	Allows you to set a result set field to group the row.	NULL
group_repeat	"yes" or "no"	Directs the group field to repeat or not	yes
group_sort	"desc","asc"	Sets the group sort order of the groupby field. Desc sorts the groups in a descending alphanumeric order. Asc sorts the groups in an ascending alphanumeric order. Products	asc
limit	any integer	Limits the rows returned to the number set in this parameter.	all records
orderby	all non-custom fields	Sorts the result set rows (within a group) by a designated field. Do not use this parameter if sorting randomly.	entry_id
sort	"desc","asc","rand"	Sets the sort order to be ascending, descending, or random within a group. Desc sorts the records in a descending alphanumeric order. Asc sorts the records in an ascending alphanumeric order. Rand sorts the records in a random order.	desc
excerpt_size	any integer	The number of words generated by the excerpt tag.	50
page_size	any integer	The number of records to list on a page. Result sets larger than the page_size will be paged.	all records
highlight	"yes" or "no"	Insert span tags around search terms found in the title, excerpt and full entry. The generated span has a class of "terms".	yes
custom	"yes" or "no"	Turns on custom field tags. This will slightly impact the performance of the results page as custom fields are collected from the channel.	no
matrix	"yes" or "no"	Turns on matrix custom field tags. This will slightly impact the performance of the results page as matrix fields are collected from the channel.	no
pt_divebar	"yes" or "no"	Turns on Pixel & Tonic Dive Bar field tags. This will slightly impact the performance of the results page as Dive Bar fields are collected from the channel.	no
category	string	Filters results on the categories listed. It accepts a string with one or more category names separated by '\|' character. A user can add "not" to exclude categories. eg. category = "cat1\|cat2" or category = "not cat1".	Uncategorized
category_empty	any string	Sets a string to use in category field tag where a category for an entry is blank.	Uncategorized
disable	various	Disables certain default features that can slow down search query performance. You are strongly encouraged to disable every feature not needed. Currently supports: categories and pt_divebar	NULL

Variables

All relevant channel entry tags are available to use between the primary tag pair. All custom field tags are available to use if the "custom" parameter is set to "yes". All ExpressionEngine conditional statements work within the primary tag pair.

You can also use the following variable tags:

Tag	Description
group	This variable returns the contents of the grouped field. This tag accepts the optional variable “format” as defined at: http://expressionengine.com/public_beta/docs/templates/date_variable_formatting.html
group_block, /group_block	This tag pair wraps a group tag to allow strings, tags, scripts to be generated along with the group string. Everything within tag pair is subject to same repetition logic as indicated by the group_repeat parameter. Example: {group_block} Subject: {group}s {/group_block} NOTE: Only available for EE 2.x
switch	This variable is replaced by alternating values specified in the switch= parameter. A good way to use this tag is to alternate class names of HTML tags to style alternating rows to be more clear in the user interface.
auto_path	This parameter is replaced with the URL to the entry with the URL Title appended to the end. The path will automatically be determined by the Search Results URL setting for the channel/weblog in Channel/Weblog Management.
excerpt	An excerpt from the returned entry truncated to the number of words specified in the "excerpt_size" parameter. The field specified for the excerpt is selected in the Channel/Weblog Management settings for the channels/weblogs This tag accepts the optional variable “type”. By using “type” you select the format to use for the excerpt. This allows the user to include all XHTML tags or return a simple string with no XHTML tags. Options are “none”(default), “XHTML”, and "context". The "context" setting returns sentences that contain the search term separated by … up to the size of the excerpt. This tag also accepts the optional variable “end”. By using “end” you determine the HTML character code for the character the follows an excerpt string. Default is … (horizontal ellipse). An empty string can be used for no character. The string can be a link to a graphic file. If the excerpt does not have to truncate the field, the ending character does not appear in the rendered page. The tag also accepts the optional parameter "default" NOTE: Only available for EE 2.x. By using "default" you can set the string that is used if the excerpt field is empty. The default value for an empty string is an empty string.
category, /category	This tag pair wraps the category tags to loop through all categories for an entry. You can control the string with backspace and limit attributes. E.g. {categories backspace="2" limit="3"}<a href="{auto_path_category}">{category_id}-{category_name}</a>, {/categories}
read_more	This variable is replaced with a hyperlink automatically determined by the Search Results URL setting for the channel/weblog in Channel/Weblog Management. This tag accepts the optional variable “text”. You can use "text" to override the default string of "Read more". (example usage text=”see more”)
absolute_count	This returns the number of the entry regardless of what page it is on.

A couple of variable tags are available to be used anywhere on a results page:

{exp:key_search:referring_page}

This tag returns a URI string of the page that initiated the search. This can be used in a link tag HREF parameter.

{absolute_results}

This returns the total number of results. You must use this outside of the primary tag pair.

Other Features

Search term highlighting

If the parameter "highlight" = yes then search terms are surrounded with <span class="terms"> and </span> tags. You can easily style the search terms by using the "terms" class in your stylesheets.

Error Handling

Undefined properties are trapped and sent to the normal ExpressionEngine error handling library with the error message of “You are attempting to use one or more undefined properties in your Search Results tags. Please check your template.”

Custom field size

Custom fields can be truncated to a specific number of words. Simply use a size parameter inside of the custom field tag. (for example: {my_field size="50"})

Example Use Case

{exp:key_search:results groupby="channel" group_sort="asc" group_repeat="no" excerpt_size="60"}
    {group_block}
    <h4>{group}</h4>
    {/group_block}
    <div class="result">
        <a href="{auto_path}">{title}</a>
        <span class="cats">{categories backspace="2" limit="3"}<a href="{auto_path_category}">{category_id}-{category_name}</a>, {/categories}</span>
        {excerpt end=" >>" type="XHTML"} {read_more}
    </div>
{/exp:key_search:results}

How to get help

We want to you get the most out of this plugin so please contact us if you need help. Please send us your question at support@planet-ee.com

Planet/EE