AjaxSearch

From MODx Wiki

Downloads

• Download the Current Release - 1.8.3

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, alias, intro and Template Variable (TV) values of documents
• Search in title and description of MaxiGallery images. Display the images found as search results with a link to the image in the gallery
• Search in content of jot and display the document with the comment
• Search in your own tables (it is required to describe them)

Features

It could works in two modes:

• ajaxSearch mode :
  • search results are displayed in a popup window over the current page through an AJAX request
  • available link to view all results in a new page when only a subset is retuned (Show more results link)
  • allow a live search (Each new letter which is entering in the search box provide new search results)
  • tune the opacity parameter of the popup window
  • Uses the MooTools or jQuery js library for AJAX and visual effects
  • with JS disabled swap to the non-ajaxSearch mode

• non-ajaxSearch mode :
  • search results displayed in a new page
  • customize the paginating of results
  • works without JS enabled as FlexSearchForm
  • designed to load only the required non-ajaxSearch code

for the two modes :

• provide several templates to customize search input form and search results
• use extended place holder and template parameters to fit your needs
• redifined the templates and provide them as file or chunck
• advanced seach allow to search among the search words provided between: one word, all words, the exact phrase or no words
• a template is available to let the user choose the advanced search parameter
• rather to use a search input field, use a template with a drop down list with predefined search terms
• define search in subset of documents and adds radio-buttoms to let the user choose where applied the search
• specify the subset by using a list of id or by providing a list of hierachies of documents
• specify the search into the hidden documents and into the documents of reference type (links))
• 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
• user could define his own strip functions to applied on input search term or on search results
• define in which tables the search will occur. content, tv, maxigallery, jot available
• do a search in your own tables. Define the main table and the joined table. Do a search with them.
• specify precisely in which fields you want use for search
• restrict the search to a list of TVs
• filter unwanted documents of the search. Use the metacharacter # as search terms
• define the content (which fields from which tables) of extract
• define the maximum number of extracts to be shown
• define your own extract ellipsis and add the extract separator you want
• all the searchable text fields of results are available as extended placeholders
• highlighting of searchword in the extracts returned
• display the path of documents found by adding a breadcrumb
• order the results
• define the ranking value and sort the results with it
• choose the clear default mode to don't lose the initial phrase in the input form
• use a configuration file to define permanent parameters. Decide if snippet call parameters overwrite or not the configuration definition.
• 2 debug modes. Output the trace in a file or directly in the firebug console. 3 levels of log.
• external language files to ease the implementation of multi-language site
• log the search requests (successfull and unsucessfull)
• allow your end user to comment the search results

Planned Features

• For the last proposals see JIRIA MODX ADDON / AJAXSEARCH
• and Let me know what is missing ...

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.txt 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:
• styles for the layout template

       #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;
       }
       .AS_ajax_result {
           color: #444;
           margin-bottom: 3px;
       }
       .AS_ajax_resultLink {
           text-decoration: underline;
       }
       .AS_ajax_resultDescription{
           color: #555;
       }
       .AS_ajax_more {
           color: #555;
       }

• styles for the paging template

       .ajaxSearch_paging {
   
       }

• styles for ajax results and results. See the detailed section below.

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 ajaxSearchPopup.php and change
  define('AS_SPATH', 'assets/snippets/ajaxSearch/');
  to
  define('AS_SPATH', '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 SearchHighlight
• Copy the contents of the file plugin.searchHighlight.tpl into the plugin
• On the System Events tab of the plugin, select OnWebPagePrerender
• To improve the performances, the searchHighlight 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.

advSearch Highlight plugin installation

advSearch is a variation of the SearchHighlight plugin. Use which fit your needs the better.

• Extract the contents of the zip file to your computer
• Create a new plugin named AdvSearchHighlight
• Copy the contents of the file plugin.advSearchHighlight.tpl into the plugin
• On the System Events tab of the plugin, select OnWebPagePrerender.
• In your templates or documents define which section could be highlighted.
• For that frame the search content sections you want by "" and
• This will limit the highlighting of search words to this part of your document.

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 and Searchable 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 and Searchable 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 and Searchable 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 and Searchable 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 error messages section that you can get.

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

AjaxSearch Parameters

General Parameters

 .ajaxSearch_hiddenField {
    position:absolute;
    text-decoration:underline;
    background-color:#CC0000;
    left:0px;
    top:-500px;
    width:1px;
    height:1px;
    overflow:hidden;
 }

Ajax Parameters - Used by the ajaxSearch mode

Non Ajax Parameters - Used by the non-ajaxSearch mode

Placeholders

To use an another template, define the template name and location with @FILE:assets/snippets/ajaxSearch/templates/folderName/templateName.tpl.htm or create a chunck parameter by copy/paste and change of an existing template.

• &tplLayout : chunk to style the ajaxSearch input form and layout

Global ajaxSearch layout (input form, intro message, results) by default : /templates/layout.tpl.html

Non ajax mode & more results page :

• &tplResults : chunk to style the output results outer

Results outer layout (number of results, list of results, paging) by default : /templates/results.tpl.html

• &tplResult : chunk to style each output result

Result template (title link, description, extract, breadcrumbs link) by default : /templates/result.tpl.html

• &tplPaging : chunk to style the paging links

Paging link template (pages, current page) by default : /templates/paging.tpl.html

• &tplComment

chunk to style comment form by default: @FILE:".AS_SPATH.'templates/comment.tpl.html'

Ajax mode :

• &tplAjaxResults : chunk to style the ajax output results outer

Results outer layout (number of results, list of results, more results link) by default : /templates/ajaxResults.tpl.html

• &tplAjaxResult : chunk to style each ajax output result

Result template (title link, description, extract, breadcrumbs link) by default : /templates/ajaxResult.tpl.html

searchString available as placeholder Use [+as.searchString+] to get the search string used for the search. For instance use "Search results for [+as.searchString+]" as pagetitle for your landing page.

All the fields of the main table and of the joined table defined as "displayed" in the table definition could be used with the tplResult and tplAjaxResult templates:

For each field named "xxxx" we having: [+as.xxxx+] the content of the field named xxxx [+as.xxxxShow+] a boolean value which is equal to 0 when xxxx=, 1 otherwise [+as.xxxxClass+] a class name equal to: - ajaxSearch_resultXxxx for the non ajax results (&tplResult) - AS_ajax_resultXxxx for the ajax window (&tplAjaxResult)

For instance, with &whereSearch="content,tv", the following informations are available

• "content" as main table - id field : [+as.id+]
• "content" as main table - date field : [+as.publishon+]
• "content" as main table - displayed fields :

• [+as.pagetitle+], [+as.pagetitleShow+], [+as.pagetitleClass+]
• [+as.longtitle+], [+as.longtitleShow+], [+as.longtitleClass+]
• [+as.description+], [+as.descriptionShow+], [+as.descriptionClass+]
• [+as.alias+], [+as.aliasShow+], [+as.aliasClass+]
• [+as.introtext+], [+as.introtextShow+], [+as.introtextClass+]
• [+as.menutitle+], [+as.menutitleShow+], [+as.menutitleClass+]
• [+as.content+], [+as.contentShow+], [+as.contentClass+]

• "content" as main table - breadcrumbs link:
• [+as.breadcrumbs+],[+as.breadcrumbsShow+],[+as.breadcrumbsClass+]

• "tv" as joined table - 'concat_alias' field : [+as.tv_value], [+as.tv_valueShow+], [+as.tv_valueClass+]

and in any case the extract result built with &extract parameter:

• [+as.extract+], [+as.extractShow+], [+as.extractClass+]

with AS_ajax_resultExtract (ajax) or ajaxSearch_resultExtract (non-ajax) as class names

With &whereSearch="content,tv,maxigallery,jot" we add :

• [+as.jot_content], [+as.jot_contentShow], [+as.jot_contentClass]
• [+as.gal_title], [+as.gal_titleShow], [+as.gal_titleClass]
• [+as.gal_descr], [+as.gal_descrShow], [+as.gal_descrClass]

&tvPhx : Set placeHolders for TV (template variables)

• 0 : disallow the feature
• 'tv:displayTV' : set up placeholders for each TV (named tvName) linked to the documents found (default)

Placeholders for TVs are:

• [+as.tvName+], [+as.tvNameShow+], [+as.tvNameClass+]

Where tvName is the MODx name of a TV

• [+as.tvName+] is the HTML output of your TV
• [+as.tvNameShow+] = 1 if the TV is not NULL
• [+as.tvNameClass+] :

- ajaxSearch_resultTvName for the non ajax results (&tplResult) - AS_ajax_resultTvName for the ajax window (&tplAjaxResult)

e.g: AS_ajax_resultAsTag1, a tv named "asTag1" (take care, the first letter of tvName should be here an upper case)

displayTV is a provided ajaxSearch function which render the Modx TV output. Don't change the name!

But tvPhx could also be a user function and runs with your custom tables.

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 And some of them with Safari and Opera

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

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 config file, parameter values should be added with the syntax: $param = 'value' or $__param = 'value' $__param is always overwritted by the parameter of the snippet call, if it exists. On the contrary, $param is always applied, whatever the parameter in the snippet call.

Inside the config file, should be defined, if used :

• stripInput function
• stripOutput function
• searchWordList
• subSearch

The signature of StripInput function is:

 
 // StripInput user function. 
 // Uncomment and complete the core function and choose your own function name
 // string functionName(string searchstring, string advsearch)
 // functionName : name of stripInput function passed as &stripInput parameter
 // searchstring : string php variable name as searchString input value
 // advSearch : string advSearch variable as advSearch parameter and return value
 // return the filtered searchString value

 function myStripInput($searchString, &$advSearch){
   $advSearch = ...  ;
   return $searchString;
 }
 

The signature of StripOutput function is:

 
 // StripOutput user function
 // Uncomment and complete the core function and choose your own function name
 // string functionName(string results)
 // functionName : name of stripOutput function passed as &stripOutput parameter
 // results : string php variable name as results
 // return the filtered results

 function myStripOutput($results){ 
   $results = ....  
   return $results;
 }
 

The AjaxSearch functions: stripHtml(), stripHtmlExceptImage(), stripJscripts() and stripLineBreaking() are available to set up your own stripOutput function.

e.g: &stripOutput=`saveImage`

 
 function saveImage($results){ 
 // replace line Breaking by space
 $results = stripLineBreaking($results);
 // strip other html tags
 $results = stripHtmlExceptImage($results);
 // strip javascript tags
 $results = stripJscripts($results);
 
 return $results;
 }
 

The signature of a searchWordList is:

 
 // searchWordList user function
 // Uncomment and complete the core function and choose your own function name
 // string functionName(params)
 // functionName : name of searchWordList function passed as &searchWordList parameter
 // params : array of parameters
 // return a comma separated list of words

e.g: &searchWordList=`mySearchWordList,[*id*]`

 function searchWordList($params){ 
 switch($params[0]){ 
   case '61':
     $list = "primary,school,education,children,teacher,africa,litteracy,bicycle";
     break;         
   case '62':
     $list = "primaire,école,éducation,enfants,professeur,afrique,littérature,bicyclette";
     break; 
 }
 return $list;

}

The signature of subsearch definition is:

 // subSearch user function
 // Uncomment and complete the core function and choose your own function name
 // string functionName()
 // functionName : name of token linked with the sub-domain as defined in the layout template
 // return an array with a list of configuration parameters

eg: for instance with

 <li><input type="radio" id="subSearch1" name="subSearch" value="travel,1" [+as.subSearch1Checked+] /><label for="subSearch1">Travel pictures gallery</label></li>
 
 
   function travel(){
   
     $config = array();
     
     // travel search definition
     
     $config['documents'] = '104';  
     $config['whereSearch'] = 'content:alias|jot|maxigallery';
     $config['extract'] = '0';
     $config['breadcrumbs'] = 'Breadcrumbs,showHomeCrumb:0,showCrumbsAtHome:1';
         
     return $config;
   }
 
   

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 error: php_mbstring extension required

• means that the Php mbstring extension should be set

AjaxSearch error: search function not defined in the configuration file

• means that the subSearch domain is not defined in the configuration file. Check your layout template and your configuration file.

AjaxSearch error: table not defined in the configuration file

• means that you use an unknown table with the whereSearch parameter. Check the whereSearch parameter and your configuration file.

AjaxSearch error: the function is not defined in the configuration file

• means that you use an unknown function with the tvPhx parameter. Check the tvPhx parameter and your configuration file.

AjaxSearch error: the function is not defined in the configuration file

• means that you use an unknown function with the tvPhx parameter. Check the tvPhx parameter and your configuration file.

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

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, ...)
• activate the debug mode and catch the log

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

Rank

Value of ranking depending of number of search results and where the results have been found

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