AjaxSearch

From MODx Wiki

Downloads

• Download the Current Release - 1.7.1

Description

The AjaxSearch snippet is an enhanced version of the original FlexSearchForm snippet for MODx. This snippet adds AJAX functionality on top of the robust content searching.

• search in title, description, content and TVs of documents
• search in a subset of documents
• highlighting of searchword in the results returned
• External language files to ease the implementation of multi-language site.

Features

It could works in two modes:

• ajaxSearch mode :
  • Search results displayed in current page through AJAX request
  • Multiple search options including live search and non-AJAX option
  • Available link to view all results in a new page (FSF) when only a subset is retuned
  • Customize the number of results returned
  • Uses the MooTools js library for AJAX and visual effects

• non-ajaxSearch mode (FSF) :
  • Search results displayed in a new page
  • Customize the paginating of results
  • Works without JS enabled as FlexSearchForm
  • Designed to load only the required FSF code

Planned Features

• Improvement of templating (input form and output results)
• A link to open an ajax Window for the selection of advanced search parameter
• Improvement of the extract feature (merging of extracts when they are the same)
• Possibility to index more than one term in the extract
• Direct link from the Ajax output or from the search results page to the term in the page. Not only to the start of the page (indexation)
• Input and output customized filtering
• Addition of a breadcrumb information for the page found
• Improvement of the use of configuration file. Possibility to avoid the overwriting of a parameter when used in the snippet call

AjaxSearch installation

• Extract the contents of the zip file to your computer
• Open the js/ajaxSearch.js file and set the loading & close image path to an image you want to display while the search is working. Otherwise the default ajax image will be used. You could also change the relative url by your absolute url if needed.
• FTP the ajaxSearch folder to your server under assets/snippets and the files and sub-folders will go to correct place
• Close your FTP program and go to the MODx manager
• Go to MODx manager and create a new snippet called AjaxSearch and paste the contents of snippet.ajaxSearch.php to it
• Call the snippet on some document with the parameters you want. Note: If javascript is disabled the snippet functions like the original FlexSearchForm. So you will want to set any of the other options in the snippet call for these users. Test by calling via [!AjaxSearch? &ajaxSearch=0 &otherParamsAsNeeded=`here` !]
• Use the following styles to change how your search looks:

       #ajaxSearch_form {
           color: #444;
           width: auto;
       }
       #ajaxSearch_input {
           width: auto;
           display: inline;
           height: 17px;
           border: 1px solid #ddd;
           border-left-color: #c3c3c3;
           border-top-color: #7c7c7c;
           background: #fff url(images/input-bg.gif) repeat-x top left;
           margin: 0 3px 0 0;
           padding: 3px 0 0;
           vertical-align: top;
       }
       #ajaxSearch_submit {
           display: inline;
           height: 22px;
           line-height: 22px;
       }
       #ajaxSearch_output {
           border: 1px solid #444;
           padding: 10px;
           background: #fff;
           display: block;
           height: auto;
           vertical-align: top;
       }
       .ajaxSearch_paging {
   
       }
       .AS_ajax_result {
           color: #444;
           margin-bottom: 3px;
       }
       .AS_ajax_resultLink {
           text-decoration: underline;
       }
       .AS_ajax_resultDescription{
           color: #555;
       }
       .AS_ajax_more {
           color: #555;
       }

• If you are using the display more results link setup a new page with the snippet call to display your results.

Setup parallel installations

If you want to install new version, but want to try it first and don't want to replace your current AjaxSearch installation, you can do parallel setup.

• Extract the contents of the zip file to your computer
• Rename ajaxSearch folder in the extracted files to something else, for example ajaxSearch-new
• Open the extracted snippet.ajaxSearch.php and change
  define('AS_SPATH', 'assets/snippets/ajaxSearch/');
  to
  define('AS_SPATH', 'assets/snippets/ajaxSearch-new/');
• Open the extracted ajaxSearch.php and change
  define('AS_PATH' , MODX_BASE_PATH . 'assets/snippets/ajaxSearch/');
  to
  define('AS_PATH' , MODX_BASE_PATH . 'assets/snippets/ajaxSearch-new/');
• Open the extracted js/ajaxSearch.js and change
  var _base = 'assets/snippets/ajaxSearch/';
  to
  var _base = 'assets/snippets/ajaxSearch-new/';
• FTP the ajaxSearch-new folder to your server under assets/snippets and the files and sub-folders will go to correct place
• Go to MODx manager and create a new snippet called AjaxSearchNew and paste the contents of snippet.ajaxSearch.php to it
• Use AjaxSearchNew snippet call in some document and view results

Search Highlight plugin installation

• Extract the contents of the zip file to your computer
• Create a new plugin named Search_Highlight
• Copy the contents of the file plugin.searchHighlight.tpl into the plugin
• On the System Events tab of the plugin, select OnWebPagePrerender.

AjaxSearch Usage

Creating your first search

In a document:

1. Put the snippet call [!AjaxSearch!] in the document content area and save the document
2. Check Published on the Page Settings tab

In a template:

1. Put the snippet call [!AjaxSearch!] in the template and save it
2. Create a document with your template
3. Check Published on the Page Settings tab of your document

Creating your first search (non-ajax mode)

In a document:

1. Put the snippet call [!AjaxSearch? &ajaxSearch=`0`!] in the document content area and save the document
2. Check Published on the Page Settings tab

To show the results in other page:

1. Put the snippet call [!AjaxSearch? &ajaxSearch=`0` &AS_landing=`x`!] in the document content area and save the document. Here x is the id of your results page.
2. Check Published on the Page Settings tab
3. Create the page #x with the snippet call [!AjaxSearch? &ajaxSearch=`0` &AS_showForm=`0`!]

IMPORTANT NOTE:

• Your database character set is different of utf8:

1. the php_mbstring extension for the multibyte support should be loaded. Check the phpinfo file of your server
2. the $database_connection_charset variable of your /manager/includes/config.inc.php file should be set with the MySql database character set (not the collation) of your database. e.g: latin1, latin2, ...

Searching for words containing characters like "å,ä,ö,Å,Ä,Ö" require to configure your editor to avoid entity encoding. With TinyMCE, for that, change the entity_encoding parameter from "named" to "raw" in the configuration tab and save again your documents.

See below the possible error messages that you can get.

• ajaxSearch and TV:

Search terms are searched in the TVs linked with documents. But, in this case, the extract doesn't show the content of the TV and the search result appears only with the document title and the description. The extract is empty.

• ajaxSearch and private documents:

Search terms are searched in private documents only if you are logged as a user who has the rights of access on the document group of the document

Search Highlight plugin Usage (optional)

1. Somewhere in your template or document add the html: <!--search_terms-->
2. This will display the search terms and a link to remove the highlighting
3. Do a search and click the link to see the search highlighting carried through to the page

IMPORTANT NOTE:

• To improve the performances, the search Highlight plugin uses the <body> tag. If you use a complex body tag like '<body id="type-a">', change the line 53 of the plugin:$body = explode("<body>", $output); // break out the head</code>
  with your own body tag.

• An another possible trick is, in your template, to frame a part of it,(e.g: [*content*]), with an html comment like '<!--highlight-->' change the lines: $body = explode("<body>", $output); to $body = explode("<!--highlight-->", $output); and $output = implode("<body>", $body); by $output = implode("<!--highlight-->", $body);

This will limit the highlighting of search words to this part of your document. Available for only one section to highlight.

AjaxSearch Parameters

General Parameters

Parameter	Possible values	Default value
&config Load a custom configuration. (optional) Configuration files are named in the form: <config_name>.config.php. Inside the config file, parameter values should be added with the syntax: $param = 'value';	Config file name. Other config installed in the configs folder or in any folder within the MODx base path via @FILE	default
&language Sets the ajaxSearch language.(optional) Note: Language files are not fully implemented yet. Feel free to add your language(s). (See english.inc.php for examples.)	chinese english finish francais german italian nederlands portuguese russian spanish svenska	the language set for your MODx manager
&ajaxSearch Use the ajaxSearch mode.(optional) The AjaxSearch mode use an Ajax call to get the results without full page reloading	0 1	1 (true)
&AS_showForm Show the search form with the results.(optional)	0 1	1 (true)
&AS_showResults Show the results with the snippet.(optional) (For non-ajax search)	0 1	1 (true)
&advSearch Set the advanced search options. (optional)	exactphrase : provides the documents which contain the exact phrase allwords : provides the documents which contain all the words nowords : provides the documents which do not contain the words oneword : provides the document which contain at least one word	oneword
&minChars Minimum number of characters to require for a word to be valid for searching. (optional)	Integer	4
&hideMenu Search in hidden documents from menu. (optional)	0 : search only in documents visible from menu 1 : search only in documents hidden from menu 2 : search in hidden or visible documents from menu	2
&extract Show the search words highlighting. (optional)	0 1	1 (true)
&extractLength Length of extract around the search words found. (optional)	50 < Integer < 800	200
&highlightResult Create links so that search terms will be highlighted when linked page clicked. (optional) Require the use of the highligth plugin.	0 1	1 (true)
&parents To define a subset of documents where to search. (optional)	A comma separated list of parent-documents whose descendants you want searched to &depth depth when searching.	all the public documents
&depth Number of levels deep to go. (optional)	Integer > 0	10
&documents To define a subset of documents where to search. (optional)	A comma separated list of documents where to search	all the public documents

Ajax Parameters - Used by the ajaxSearch mode

Parameter	Possible values	Default value
&ajaxMax The number of results you would like returned from the ajax search. (optional)	Integer	6
&showMoreResults If you want a link to show all of the results from the ajax search. (optional)	0 1	0 (false)
&moreResultsPage Page you want the more results link to point to. (optional) This page should contain another call to this snippet for displaying results.	ID's of a document	0
&ajaxSearchType There are two forms of the ajaxSearch. (optional) 0 - The form button is displayed and searching does not start until the button is pressed by the user. 1 - There is no form button, the search is started automatically as the user types (liveSearch)	0 1	0
&opacity Opacity of the ajaxSearch_output div where are returned the ajax results. (optional) From transparent (0.) to opaque (1.)	0. < Float < 1.	1.
&addJscript If you want the mootools library added to the header of your pages automatically set this to 1. (optional) Set to 0 if you do not want them included automatically.	0 1	1 (True)

Non Ajax Parameters - Used by the non-ajaxSearch mode

Parameter	Possible values	Default value
&AS_landing Document id you would like the search to show on. (optional) This page should contain another call to this snippet for displaying results.	ID's of a document	0
&grabMax The max number of records you would like on each page. (optional) Set to 0 if unlimited.	Integer >= 0	10

Examples

Feel free to add your own examples to the list.

The following examples have been tested with Firefox 2.0, IE 6.0, IE 7.0 It should be work properly with Opera. Not tested with Safari

Thanks for your feedbacks with these browsers

With AjaxSearch mode

[!AjaxSearch!]

• A basic (Ajax) default call that renders a search form with the default images and parameters
• Output search results are displayed through ajax in a window upper the page

[!AjaxSearch? &moreResultsPage=`33` &showMoreResults=`1`!]

• Basic call witch adds a link "More results" at the end of the results list, to go to a full search results page (#33)
• The page #33 should contain a non-ajaxSearch snippet call like:

[!AjaxSearch? &ajaxSearch=`0` &AS_showForm=`0`!]

• Display the results without the search form again

[!AjaxSearch? &ajaxMax=`10` &extract=`0`!]

• Basic call witch overrides the number of maximum results returned in the ajax output results window
• Removes the display of extracts. Only the title and description are displayed

[!AjaxSearch? &documents=`2,3,8,16`!]

• Basic call which renders a search form with the default images and parameters
• Search terms are searched among the documents `2,3,8,16`

[!AjaxSearch? &parents=`5,7` &depth=`4`!]

• Renders a search form with the default images and parameters
• Search terms are searched on 4 levels among the document children of documents 5, 7

[!AjaxSearch? &parents=`9,12` &hideMenu=`0` &advSearch=`allwords`!]

• Renders a search form with the default images and parameters
• Search terms are searched among the document children of documents 9, 12
• Documents should contains all the search terms and not hidden from the menu

Without AjaxSearch mode

[!AjaxSearch? &ajaxSearch=`0` &AS_landing=`33`!]

• Basic call which renders a search form with the default images and non-Ajax parameters
• Results are outputed to the page #33
• The document #33 should contain a non-ajaxSearch snippet call like :

[!AjaxSearch? &ajaxSearch=`0` &AS_showForm=`0`!]

• Display the results without the search form again

[!AjaxSearch? &ajaxSearch=`0` &AS_landing= `33`!]

• Search results will be displayed on document #33
• The document #33 should contain a non-ajaxSearch snippet call like :

[!AjaxSearch? &ajaxSearch=`0` &AS_landing= `33` &AS_showForm=`0` &grabMax=`10` &highlightResult=`0`!]

• Same as above. To display the results without the search form again
• Overrides the number of maximum results returned per page and removes search term highlighting

[!AjaxSearch? &ajaxSearch=`0` &AS_landing=`33`!]

• Basic call which renders a search form with the default images and non-Ajax parameters
• Results are outputed to the page #33
• The document #33 should contain a non-ajaxSearch snippet call like :

[!AjaxSearch? &ajaxSearch=`0` &AS_showForm=`0` &parents=`10` hideMenu=`1` &advSearch=`nowords`!]

• Display the results without the search form again
• Search terms are searched among the document children of documents 10
• Documents should not contain any of the search terms and should not be visible from the menu

Demo site

• More examples on the demo site : http://www.modx.wangba.fr/

• AjaxSearch versions comparison
• Sql explanations
• Bugs and features tracker

Some tricks (before the next release)

• to display in the output search results, the longtitle instead the pagetitle, change the line 27 of includes/templates.inc.php from:
  

<a class="[+as.resultLinkClass+]" href="[+as.resultLink+]" title="[+as.longtitle+]">[+as.pagetitle+]</a>

to

<a class="[+as.resultLinkClass+]" href="[+as.resultLink+]" title="[+as.longtitle+]">[+as.longtitle+]</a>

But keep in mind if your document hasn't longtitle, you get a blank line !

• to remove the introduction message displayed in the non-ajax mode, simply change the line 72 of includes/templates.inc.php:
  

<p class="ajaxSearch_intro" id="ajaxSearch_intro">[+as.introMessage+]</p>',

to

<p class="ajaxSearch_intro" id="ajaxSearch_intro"></p>',

Configuration file

The default configuration file is configs/default.config.php

Except if &config is set with a different configuration file name, this file is always loaded and read.
Inside the file, configuration parameter values should be added with the syntax: $param = 'value';

example:

$language ='spanish-utf8';
$ajaxSearch = 0;
$grabMax = 12;

In this example, &language, &ajaxSearch, &grabMax values, if set in the ajaxSearch call, will be overwritted by the values of the configuration file.

You can change the messages, e.g. the "Search here..." or the "Go!" text by editing the appropriate language config file located in /assets/snippets/AjaxSearch/lang/.

Error messages

AjaxSearch version is not defined. Please check the snippet code in MODx manager.

• means that the snippet code in the manager is not properly installed or has changed and doesn't fit with the snippet source folder (includes/snippet.ajaxSearch.inc.php)

AjaxSearch version is obsolete. Please check the snippet code in MODx manager.

• means that you the version of the snippet code in the manager doesn't fit with the version of the snippet source folder (includes/snippet.ajaxSearch.inc.php)

AjaxSearch setup path is not defined. Please check the snippet code in MODx manager.

• means that the path, to the snippet source folder (includes/snippet.ajaxSearch.inc.php), in the snippet code, in the manager is not defined

AjaxSearch version obsolete. Check the version of AjaxSearch.js file

• means that the version of the snippet source folder (includes/snippet.ajaxSearch.inc.php) doesn't fit with the js/ajaxSearch.js file

AjaxSearch: database_connection_charset not set. Check your config file

• means that your $database_connection_charset variable of your /manager/includes/config.inc.php file should be set

AjaxSearch: database_connection_charset is null. Check your config file

• means that your $database_connection_charset variable of your /manager/includes/config.inc.php file is an empty value

AjaxSearch: unknown database_connection_charset = something. Add the appropriate Html charset mapping in the ajaxSearch.php file

• is not an error but need that you add in the ajaxSearch.php file the mapping between the mysql database character set (not the collation) and the html charset.
• e.g: 'latin1' => 'ISO-8859-1',

Browser tests

Tested on Windows XP SP2 with:

• Firefox 2.0
• IE6.0, IE7.0
• Opera 9.26
• Safari 3.1

Bug tracker and feature requests

You can follow bugs and feature requests on the dedicated tracker: http://www.flyspray.modx.wangba.fr/index.php?project=1

Support

http://modxcms.com/forums/index.php/topic,5357.0.html

For all new posts, thanks the first time to give the following informations:

• ajaxSearch snippet version
• ajaxSearch snippet call of the page where is the search form
• ajaxsearch snippet call of your landing or moreResults page
• value of your search terms.
• where the searched term is. In a title/description/content of a public/private document or in a TV
• charset of your html page
• charset of your database
• value of your $database_connection_charset variable in your /manager/includes/config.inc.php file
• type of entity_encoding (Raw / Named) of your editor (TinyMCE, ...)
• browser type and version (IE, FireFox, Opera, Safari, ...)

and if needed:

• Client side operating system (Windows / Linux) and browser type
• Php version
• MySql version

Thanks for your feedbacks.

AjaxSearch Glossary

AjaxSearch mode

Search results displayed in current page through AJAX request

Non ajaxSearch mode

Search results displayed in a new page

Search term

The entry term in the search form, searched

Extract

Part of a document extracted and added in the results page

Search result

Title, as a link to the document, description and extract

Search results page

All the search results with optionaly a more results link to a showMoreResult page.

or all the search results paginated with the grabMax parameter

highlighted term

In the search results page, the search terms found could be (or not) highlighted.

In the linked document, the highlighting of the terms needs the plugin searchHighlight