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 in AJAX style under the search box with a nice animation effect as the user types his query in it.

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 enter he gets redirected to a traditional search results page, so the plugin also degrades nicely on non-Javascript browsers.

Requirements

Since version 0.4, cbs_live_search now uses the ultra compact mootools framework for advanced javascript, AJAX and visual effects. Version 0.7 requires mootools 1.2 or more recent. Because mootools is modular, you can make your download smaller by only downloading the modules your scripts are actually using. Here are the core modules required by cbs_live_search:

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

You need to upload the javascript files mootools.js and the provided livesearch.js on 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.js"></script>

Remarks:

1. If you are already using mootools, don’t include it twice!
2. If you use prototype.js for other scripts, include it before mootools.

Syntax

<txp:cbs_live_search />

Attributes

Required

none.

Optional

• label: Displays a label above the search box with the specified text. Default is no label.
• inputsize: Size of the search box (number of characters). Default is 15.
• defaultvalue: 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.
• webkit: When set to true, the classic input box will be replaced by a Mac OS X search widget in Webkit-based browsers such as Safari if Javascript is enabled. The resetimage (see below) will then NEVER be displayed in these browsers. Other browsers will see the classic input box. Default is false.
• section: The name of the section to redirect the user to when he hits enter, to display the standard search results page. Default is the ‘default’ section (home page).
• resetimage: URL of an image to be displayed at the right of the search box. The image will be visible when the search box is not empty. Clicking on this image will clear the search box. Default is no image. Note that even if you specify a reset image, it will never be displayed in Webkit-based browsers when the “webkit” parameter is set to true (see above).
• waitimage: URL of an image to be displayed at the right of the search box. This image will only be shown during a live search operation and disappears as soon as the results are shown. Default is no image.
• break: HTML tag to be used for line breaks in the live results list, without brackets. Default is br.
• wraptag: HTML tag to be used as the wraptag for the live results list, without brackets. Default is empty.
• max: The maximum number of results in the live results list. Default is 5.
• excerpts: When set to true, displays excerpts of the articles containing the search words. Search words will be wrapped in <strong> tags. Default is false.
• dates: When set to true, displays the article date at the bottom of each result entry. Default is false.
• noresults: 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 two zones: A form with the id ‘livesearch_form’ followed by a div block with the id ‘livesearch_results’, containing the results list. You can style these zones by referencing their id in your CSS. For example, #livesearch_form { ... } .

Inside the form, the optional label, the search box and the optional images are wrapped in another div block.

You can choose to make the label invisible by setting its display attribute to “none”, so it will only be displayed in non-CSS browsers that will usually not display the text of the “defaultvalue” parameter (see above).

The search box has the id ‘livesearch_text’. You can style it by referencing its id in the CSS. When the box is inactive (empty with no focus), the “livesearch_inactive” class is applied to it, so you can style it differently while it is in this state, typically by making the font brighter.

If you set the ‘webkit’ parameter to true and the browser is detected as using recent Apple Webkit technology, the seach box will be replaced by a Mac OS X search widget, the reset image will not be shown because the search widget already has one, and the “livesearch_webkit” 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 the reset image will not be shown.

If you use images for a reset button or progress indicator (see above), they will be displayed at the right of the search box, inside the form div block. The “livesearch_resetimage” class is applied to the reset image and the “livesearch_waitimage” class is applied to the wait image, so you can style them individually. Ensure that you have enough space to display them all in the same row (by using correctly sized images and setting elements margins and search box width with correct values for example).

You can choose to style the results list 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 NOT set the height and opacity of this div because they will change dynamically. If you do, your settings will be overridden.
3. You MUST set the width of the div (since 0.4).
4. You MUST set its padding to zero, otherwise the script will not be able to compute the right size for the scale effect. Instead, you can set a margin for the content of the div (see below how to style the content).
5. You MUST NOT set visibility attributes (‘display’ and ‘visibility’). The div will not appear at all if Javascript is disabled.

Finally, you can choose to style this div containing the results list with an absolute or relative position. If you choose absolute, it will fade in above your page like a popup.

The content of the results list is either:

1. At least one result is found: Will display a list according to your ‘wraptag’ and ‘break’ parameters (see above). The title of the articles is wrapped in a link, so you can style the title differently from the excerpt based on the ‘a’ tag (example: #livesearch_results a:link, #livesearch_results a:visited { ... }).
2. No results found: Will display a message (according to the ‘noresults’ parameter described above) wrapped in a paragraph (‘p’ tag).

Changes history

v0.7 (2007-06-11)

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

v0.6 (?)

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