Textpattern Resources at textpattern.org

Description

This plugin displays a search box similarly to <txp:search_input />. If Javascript is enabled, a results list will fade in and resize in real time below the search box with a nice animation effect as the user types his query.

Optionaly, a clickable image can be displayed at the right of the search box to clear its content. When the search box is empty or contains less than 3 characters, the results list shrinks and fades out.

Also, an image (such as a spinner) can be displayed at the right of the search box when a search is in progress, and disappears when the results are shown.

When the user hits the Enter key he gets redirected to a traditional search results page, so the plugin also degrades nicely in non-Javascript browsers.

Requirements

Since version 0.8, cbs_live_search can use either the jQuery or MooTools javascript framework.
Just pick your favorite one:

jQuery

jQuery 1.2 or more recent is required.

You can use the jquery.js javascript file which is bundled with Textpattern and you need to upload the provided livesearch.jquery.js file to your web server (for example in a folder called “/js/”) and include both of these files in the header of the web pages where you want to use the plugin:

<script type="text/javascript" src="/textpattern/jquery.js"></script>
<script type="text/javascript" src="/js/livesearch.jquery.js"></script>

Remarks:

1. If you are already using jQuery, don’t include it twice!
2. If you also use other javascript frameworks (Prototype, Dojo, YUI, etc.), it is recommended that you include jQuery first. cbs_live_search is also compatible with the jQuery.noConflict() mode.

MooTools

MooTools 1.2 or more recent is required. Because MooTools is modular, you can make your download smaller by only downloading the modules that your scripts are actually using, thanks to the Core Builder. Here are the MooTools Core modules required by cbs_live_search:

• Native: all
• Class: all
• Element: Element.Event, Element.Style
• Fx: Fx.Morph
• Request: Request

The cbs_live_search plugin comes bundled with a file named mootools.js which contains these minimal dependencies only. This ensures the smallest download size for your visitors if you don’t use MooTools or jQuery at all for other features on your public website.

You need to upload the javascript files mootools.js and the provided livesearch.mootools.js to your web server (for example in a folder called “/js/”) and include them in the header of the web pages where you want to use the plugin:

<script type="text/javascript" src="/js/mootools.js"></script>
<script type="text/javascript" src="/js/livesearch.mootools.js"></script>

Remarks:

1. If you are already using MooTools, don’t include it twice!
2. If you use the Prototype framework for other scripts, include it before MooTools.

Syntax

<txp:cbs_live_search />

Attributes

Required

none.

Optional

• section: Name of the section to redirect the user to when he hits the Enter key, in order to display the standard search results page. Default is the default section (home page).
• html_id: HTML id attribute that will be applied to the search form. Default is live_search. You need to set this attribute to different values if you use more than one live search box inside the same web page.
• label: Displays a label above the search box with the specified text. Default is no label.
• size: Size of the search box (number of characters). Default is 15.
• default_value: Invitation text that will de displayed in the box when Javascript is enabled. This text disappears when the box gets the focus or when the user has typed something into it. Default is empty.
• wraptag: HTML tag to wrap the optional label, the search field and the reset and wait images with, inside the form. Default is p (a paragraph).
• safari: When set to true, the classic input box will be replaced by a Mac OS X search widget in Safari if Javascript is enabled. The reset image (see the CSS Styling section) will then never be displayed in these browsers. Other browsers will see the classic input box. Default is false.
• results_break: HTML tag to be used for line breaks in the content inside the live results list, without brackets. Default is br.
• results_wraptag: HTML tag to be used as the wraptag for the content inside the live results list, without brackets. Default is p.
• results_max: Maximum number of results in the live results list. Default is 5.
• results_excerpts: When set to true, displays excerpts of the articles containing the search terms. Search terms will be wrapped in <strong> tags. Default is false.
• results_dates: When set to true, displays the article date at the bottom of each result entry. Default is false.
• no_results: Text that will be displayed in the live results list when no articles are found. Default is “0 articles found” localized in the language of your Textpattern installation.

CSS Styling

The live search consists of a form with the default id attribute value “live_search” (which can be changed using the “html_id” parameter). This form contains two zones. You can style any element by referencing the id attribute of the form and the CSS class of the element (or its tag) in your CSS.

If you define a label, you can choose to make it invisible by setting its display property to “none” in the CSS, so it will only be displayed in non-CSS browsers that will usually not be able to display the text of the “default_value” parameter (see above).

Example:

#live_search label {
	display: none;
}

The search zone

The first zone is a block with the applied class “ls_search” which contains: the optional label (followed by a line break if defined), the text input box and the reset and wait images. The tag of this block is defined by the “wraptag” parameter (de fault is p).

The search box is an input tag. If you want, you can style it using a CSS rule like this one:

#live_search input {
	font-size: 10px;
	color: #000;
}

When the search box is inactive (empty with no focus), the “ls_inactive” class is applied to it, so you can style it differently while it is in this state, typically by making the font brighter.

Example:

#live_search input.ls_inactive {
	color: #666;
}

If you set the “safari” parameter to true and the browser is detected as Safari, the seach box will be replaced by a Mac OS X search widget and the reset image will not be shown because this special search widget already has one, and the “ls_safari” class will be applied to the form. This allows you to style the form and its subelements differently when displaying the Mac widget, for example by making the search widget larger because you know that the reset image will not be shown.

Immediately to the right of the search box, still inside the block, you have the reset image and then the wait image. These images are facultative and must be defined using CSS if you want to use them. If you don’t declare any CSS rule for one of these images, it will never appear.

The reset image is a <span> tag with the class “ls_reset_image” which is visible when the search box is not empty. Clicking on this image will clear the search box like a reset button. Note that even if you define a CSS rule for a reset image, it will never be displayed in Safari browsers when the “safari” parameter is set to true (see above).

The wait image is a <span> tag with the class “ls_wait_image” which is visible only during a search operation and disappears as soon as the results are shown. Typically, this image is a spinner or a hourglass.

When you define the CSS rules for these images, you must:

• Set the display property to “inline-block”,
• Set the width and height properties to the width and height of the image (in pixels),
• Set the background property to the image file URL,
• For the reset image only, set the cursor property to “pointer” so that the mouse cursor indicates to the user that it works like a button.

Also, it is a good idea to define a margin for some of these elements in order to add some space between the input box and the images.

Example:

#live_search .ls_reset_image
{
	display: inline-block;
	width: 14px;
	height: 14px;
	background: transparent url(../img/reset.gif) no-repeat center;
	cursor: pointer;
	margin-left: 10px;
}

#live_search .ls_wait_image
{
	display: inline-block;
	width: 16px;
	height: 16px;
	background: transparent url(../img/spinner.gif) no-repeat center;
	margin-left: 10px;
}

Remark: Browsers using previous versions of the Gecko engine like Firefox 1 or 2 normally do not support the “inline-block” value but cbs_live_search includes a javascript fix to make it work in these browsers, so you don’t need to worry about it.

Ensure that you have enough space to display all elements of this block in the same row (by using correctly sized images and setting elements margins and the search box width with correct values for example).

The results zone

The results zone is a <div> block with the class “ls_results”, containing the results list.

You can choose to style this <div> block as you want, but they are a few constraints:

1. You must set a non-transparent background for it (a color and optionnaly an image), otherwise if you keep the default transparent background, the div will display wrong in Internet Explorer.
2. You must set the “overflow” property to “hidden”, otherwise the effect will not work as expected.
3. You must set the “width” OR “height” of the <div> block (not both). If you set the width, ensure that it can expand vertically. If you set the height, ensure that it can expand horizontally.
4. You must not set its padding (leave it to zero, as it is by default), otherwise the script will not be able to compute the right size for the scale effect. Instead, you may set a margin for the content of the <div> block (see below how to style the content).
5. You must not set “display” and “visibility” properties. The block will simply not appear at all when Javascript is disabled.

You may set any border to any side. Enventually, you can choose to style this <div> block with an absolute position or not. If you choose absolute (specify position: absolute;), it will fade in above your page like a popup.

Example 1 (normal positioning):

#live_search .ls_results
{
	background-color: #ebebeb;
	overflow: hidden;
	width: 200px;
}

Example 2 (absolute positioning):

#live_search .ls_results
{
	position: absolute;
	left: 0;
	top: 0;
	background-color: #000;
	overflow: hidden;
	width: 500px;
	border: 1px solid #fff;
}

The content of the results block will be either:

1. At least one result is found: A list with wrap and break tags according to your “wraptag” and “break” parameters (see above). The title of the articles will be wrapped in a link, so you can style the title differently from the (optional) excerpt based on the <a> tag (example: #live_search .ls_results a:link, #live_search .ls_results a:visited { ... }). The search expression will be wrapped in a <strong> tag inside the excerpts.
2. No results found: A message (according to the “noresults” parameter described above) wrapped in a paragraph (<p> tag).

You can style the results content as you want with no limitations. It is recommended to set a margin because its container (the <div> block with the class “ls_results”) must not have any padding.

Example:

#live_search .ls_results p
{
	margin: 10px;
}

Changes history

v0.8b (2013-05-08)

• Updated the provided jQuery javascript code to be compatible with jQuery 1.9 and 2.0.

v0.8 (2008-12-15)

• Added a jQuery 1.2 javascript in addition to the MooTools javascript.
• Optimized both javascripts for reduced file size (< 2 KB instead of 3 KB).
• Added horizontal resizing of the results list (instead of vertical only). The results list can now grow following either a fixed width or a fixed height.
• Hitting the “Esc” key when the search box has the focus will now clear it.
• Adding spaces to the left or right of the search terms will not result in a new identical query being performed.
• Added “html_id” and “wraptag” options.
• The results list is now inside the form, below the search box block and not outside the form.
• You can now use multiple live search boxes inside the same page by specifying different values for the “html_id” attribute and even style them differently.
• Removed the “waitimage” and “resetimage” options. Now these images must be styled in the CSS instead. If no CSS rules are defined for them, they will simply not appear.
• Renamed other options to better comply with the TextPattern model and better reflect their usage. “webkit” is now named “safari” because it actually only works with Safari.
• Fixed potential SQL injection vulnerabilities.
• The results now also include “sticky” articles.
• Improved search speed and results matching compared to a standard search. Live search queries can now contain characters like .'()<> and will return correct results (a standard search containing these characters will still return wrong results until the Textpattern developers fix this problem).
• Outputs cleaner XHTML (javascript declaration is inside a CDATA block).
• Upgraded the provided minimal MooTools build to v1.2.1 and new dependencies.
• Enhanced documentation.

v0.7 (2008-06-11)

• Code updated for MooTools v1.2.
• MooTools is now included in the distribution file.

v0.6 (2007-06)

• Code updated for MooTools v1.1.

v0.5 (2007-04-06)

• Code updated for MooTools v1.0.

v0.4 (2006-09-20)

• Now uses the MooTools framework instead of Prototype and moo.fx, for a smaller download size. The code was mostly rewritten to take full advantage of this new framework.
• Now connection failures and server errors will be detected and the results list will disappear automatically, instead of infinite wait.
• Less HTML is now written in the page.
• Bugfix: The results list was wrongly sized in Internet Explorer during the very first display when the width was not fixed. Now you always need to set the width for the results list using CSS.
• Bugfix: The live search field was always styled as “inactive”, even when it had the focus.

v0.3 (2006-07-27)

• The server-side search script now use the ‘ps()’ function instead of ‘gps()’ to fetch parameters which is a bit faster.
• Bugfix: The “no results” response from the server was not interpreted correctly, which caused Javascript warnings and the “no results” message not to appear in Safari.
• Small bugfix: using br instead of <br /> as a default value for “break”.

v0.2 (2006-07-23)

• Added the “defaultvalue” parameter to display an invitation text in the search box.
• Added the “webkit” parameter for an improved search box in Apple Webkit-based browsers.
• Added the “noresults” parameter, allowing to specify the text to display in the results list when no results are found.
• The search box can now be styled differently when inactive.
• The reset image is now only visible when the search box is not empty.
• Images are now shown and hidden in a more efficient way by toggling their visibility attribute.
• Images can now be styled individually, thanks to a different CSS class applied to each one.
• Changed the way the label is displayed so it can be hidden through CSS.
• Fixed the results box scaling to wrong dimensions when it has a CSS border.
• The server now returns an empty response when no results are found.
• Improved documentation. Please read it carefully again if you are upgrading.

v0.1 (2006-07-13)

Initial release.