ExpressionEngine How to Use Search Results Module

User Documentation

Search Results

Installation

For 2.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

You install the Search Results module with the standard Expression Engine 1.6.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 Input

This version of the module uses the result sets produced by the default search module (simple and advanced search forms) that ships with ExpressionEngine. You can find the 1.6.x Search Module documentation here . The 2.x documentation is here.

Embedding search results in templates

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

{exp:key_search:results parameters=”values”}
	HTML and EE field tags
{/exp:key_search:results}

NOTE: In the current version you will need to include at least one parameter or the tag pair will throw an error.

Parameters

The following parameters are available to use in the primary tag pair to configure the way the records are returned to the template.

Parameter	Data Type	Description	Default Value
switch	any string	Allows you to set two or more values that will alternate between the result set rows	NULL
groupby	field name	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	integer	Limits the rows returned to the number set in this parameter.	no limit
orderby	field name	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	integer	The number of words generated by the excerpt tag.	50
page_size	integer	The number of records to list on a page. Result sets larger than the page_size will be paged.	no page size
highlight	string	Insert span tags around search terms found in the title, excerpt and full entry. Available values are “yes” and “no”. The span class = “terms”.	yes
custom	boolean	Turns on custom field tags. This will slightly impact the performance of the results page as customer fields are collected from the channel. Available values are “yes” and “no”.	no

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". 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"})

This 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/Weblos 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) and “XHTML”. This tag 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 is an empty string.
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”)

All ExpressionEngine conditional statements work within the primary tag pair.

A single variable tag is 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.

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.”

Example Use Case

{exp:key_search:results groupby="channel" group_sort="asc" group_repeat="no" excerpt_size="60"}
	<h4>{group}</h4>
	<div class="result">
		<a href="{auto_path}">{title}</a>
		{excerpt end=">>" type="XHTML"}
		{author}
		{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