
                              AjaxSearch - version 1.9.3b

                           Coroico - http://www.evo.wangba.fr

                                20th of november 2012

The release 1.9.3 provide the correction of the following issues:

==== AJAXSEARCH-82 : can't define configuration file name with "@FILE:" prefix
See http://bugs.modx.com/issues/3533


==== AJAXSEARCH-84 : Unquoted field name in orderby clause
See http://bugs.modx.com/issues/3697


==== AJAXSEARCH-85 : Wrong URL construction when using an array of values (checkboxes)
See http://bugs.modx.com/issues/3698


==== AJAXSEARCH-86 : number of characters not checked when a form with filters is submitted


&minChars=2 (less than the default) is now allowed for the search.


=====================================================================================

Previous versions :
 - 1.9.3 delivered the 26th of september 2012
 - 1.9.2 delivered the 5th of December 2010 (provided with MODx 1.0.4)
 - 1.9.1 delivered the 30th of August 2010
 - 1.9.0 delivered the 18th of May 2010 (provided with MODx 1.0.4)
 - 1.8.5 delivered the 20th of March 2010 (provided with MODx 1.0.3)
 - 1.8.4 delivered the 20th of October 2009 (provided with MODx1.0.1)
 - 1.8.3a delivered the 12th of July 2009 (provided with MODx1.0.0)
 - 1.8.3 delivered the 08th June 2009
 - 1.8.2 delivered the 21th April 2009
 - 1.8.1 delivered the 13th October 2008 (provided with MODx0.9.6.3)


======================= CHANGES (since 1.8.5) ==================================


==== Renaming of some parameters

    For a better and a simpler undertstanding some parameters have been renamed

    AS_showForm       =>      showInputForm
    AS_landing        =>      landingPage
    AS_showResults    =>      showResults


==== Renaming of some $_POST and $_GET variables

    AS_search   =>    search


==== Some $_GET variables are now deprecated

    FSF_search is now non interpreted


==== &searchWordList deprecated

    The option is now set un the input template


==== &resultsPage deprecated

    use landingPage rather this deprecated parameter


==== &showMoreResults deprecated

    use moreResultsPage rather this deprecated parameter


==== Firebug mode for the debug is deprecated

      Usage of the firebug mode for the debug is deprecated
      Negatives values : -1, -2, -3 are now unterstood as 1, 2, 3



====================== NEW FEATURES (since 1.8.5) ==============================


==== Accented characters - search html entities too

    The html entity version of the search terms are also searched.
    e.g: "ph&eactute;nom&egrave;ne" and "phénomène" are searched when "phénomène" is searched.


==== advSearch - exactphrase

    The search with the advSearch parameter set to "exactphrase" returns only results which
    exactly match to the searched terms.
    e.g: search "and" doesn't return "band" or "land" just "and" terms.
    As this search option use REGEXP, the search could be longer than for the other options.


==== Use Google Analytics to track AjaxSearch

    AjaxSearch forms could now use $_POST or $_GET
    with $_GET, the query parameter in the URL after you search allow you to track the site
    search with Google Analytics.
    To do this, simply replace method="post" by method="get" in the input template used
    by your ajaxSearch calls.


==== timeLimit - increase the allowed execution time of your script

    &timeLimit = [ int | 60 ]
    Max execution time in seconds for the AjaxSearch script
    0 - If set to zero, no time limit is imposed
    Default: 60 - 1 minute.


==== withTvs Define which Template Variables will be used for the search and display of results.

    &withTvs [ [ + | - ] [ : tvlist] ]  - by default ''

    The parameter withTvs define which Tv will be added as field result for displaying
    and in which tv the search will occur. Only text type TV are enabled

    e.g:

    &withTvs=`tv1,tv2,tv3`      - tv1, tv2, Tv3 are added
    &withTvs=`+:tv1,tv2,tv3`    - tv1, tv2, Tv3 are added
    &withTvs=`+`                - all tvs of the site are added

    &withTvs=`-`                - all tvs of the site are added
    &withTvs=`-:tv1,tv2,tv3`    - all tvs of the site except tv1, tv2, Tv3 are added

    &withTvs=``                 - no tv added

    If &whereSearch contains 'tv' then a tv_value field which contain the concatened
    values of all tv of the document is added

    So the tv added could be used for filtering with the filter parameter (see &filter)

    Like the default site content parameters (pagetitle, longtitle, ...)  the
    Tvs added are available with the following placeholders:

    [+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)


==== Append the content of some Tvs to your search results with the "tvPhx" parameter

    &tvPhx [ [ + | - ] [ : tvlist] ] - by default ''

    The parameter tvPhx define which additional tv will be added as placeholder.

    e.g:

    &tvPhx=`tv1,tv2,tv3`      - tv1, tv2, Tv3 are added as placeholders
    &tvPhx=`+:tv1,tv2,tv3`    - tv1, tv2, Tv3 are added as placeholders
    &tvPhx=`+`                - all tvs of the site are added as placeholders

    &tvPhx=`-`                - all tvs of the site are added as placeholders
    &tvPhx=`-:tv1,tv2,tv3`    - all tvs of the site except tv1, tv2, Tv3 are added as placeholders

    &tvPhx=``                 - no tv defined as placeholders.

    The following placeholders are anabled with the tv:

    [+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)

    The tv value could be used with the filter parameter (see &filter)

    As withTvs includes the TV as a new field in the select clause of the mysql query,
    tvPhx append the content of the selected tv after the search and before filer.


==== filter - to exclude unwanted documents of the search

     filtering by tv name is now possible

     e.g: &filter=`articleTags,volcano,7`  display only documents related to volcanoes.
     Documents are filtered by the TV 'articleTags'.

     IMPORTANT : here the tv should be allowed as result with the withTvs or tvPhx
                 parameters


==== Show introduction message under the input form

    &showIntro [ 0 | 1 ]

    To show or hide the introduction message displayed with the input form
    Default: 1 (show)


==== 2 new paging type added

     &pagingType [ 0 | 1 | 2 | 3 ] : type of pagination

     Default: 1

     0: Results Pages 1 | 2 | 3
     1: Previous - X-Y /Z - Next
     2: X-Y /Z - Show more 10 results

     Type 0 for non-ajax mode only
     Type 1 for non-ajax and ajax mode
     Type 2 for ajax mode (Jquery only)

    &tplPaging0 - Chunk to style the paging links - type 0

    &tplPaging1 - Chunk to style the paging links - type 1

    &tplPaging2 - Chunk to style the paging links - type 2

    IMPORTANT:
    arrow button images are provided with the images folder.
    use asprev.png, asnext.png or your own images to define your previous and next buttons.

    e.g:
    .paging1Prev{ width:16px; margin:0 3px 0 0;display:block; float:left; text-indent:-3000px; background:url(images/asprev.png)  0 center no-repeat; }
    .paging1Next{ width:16px;display:inline-block;text-indent:-3000px; background:url(images/asnext.png) 0 center no-repeat; }

    .paging2More{ margin:10px 10px; padding:8px;background:url(images/asnext.png) 0 center no-repeat;}


==== Custom output

    &output [ 0 | 1 ]

    0 - by default the results are listed below the input form
    1 - custom layout:

    To place the different AjaxSearch elements where you want, use the following placeholders

    [+as.inputForm+] : the input form with the intro message
    [+as.results+] : the search results

    The parameter &tplLayout is now deprecated

    The parameter &tplInput is now used to style the ajaxSearch input form


==== New modifiers for the ajaxSearch Phx parser

    to include images in your templates, uses the possible following phx modifiers:

    imgwidth  : image width       -   e.g: <img src="[+as.imageArticle+]" width="[+as.imageArticle:imgwidth+]" />
        provide the image width

    imgheigth : image heigth      -   e.g: <img src="[+as.imageArticle+]" heigth="[+as.imageArticle:imgheigth+]" />
        provide the image height

    imgattr   : image attributs   -   e.g: <img src="[+as.imageArticle+]" [+as.imageArticle:imgattr+] />
        provide the image attributes as height="xxx" width="yyy"

    imgmaxwidth=`length`  : image max width  -   e.g: <img src="[+as.articleImage+]" width="[+as.articleImage:imgmaxwidth=`60`+]" />
        limit the width of the image to a maximum. Under this limit, keep the true width

    imgmaxheight=`length` : image max height -   e.g: <img src="[+as.articleImage+]" height="[+as.articleImage:imgmaxheight=`100`+]" />
        limit the height of the image to a maximum. Under this limit, keep the true height

    These modifiers are particularly usefull with the ajax mode to help html to determine the height of the AjaxSearch pop-up window


==== Unique id for AjaxSearch instance

    &asId [ string | '']
    Any combination of characters a-z, underscores, and numbers 0-9
    This is case sensitive. Default = empty string

    This parameter allow distinguish several Ajaxsearch instances on the same page
    The id is used to link the snippet calls between them
    Choose a short name. eg: "as2"


==== Define categories

    &category [ tv_name | '']
    Any combination of characters a-z, underscores, and numbers 0-9
    This is case sensitive. Default = empty string
    Name of a TV. The category of a MODx document is provided by this TV content

    e.g: &category=`category`
    And the "category" tv value of a document could contain for instance Music, Arts, ...
    Then the categConfig function should be defined like that:

    /*
     *  categConfig :   To define the display of categories (output)
     *  Add a category as a switch item. 'uncategorized' item describe the results outside of any category
     *  Add a switch for a new site. The default site is named 'defsite'.
     *  Allowed config parameters : grpLabel, tplResult, tplAjaxResult, display, extract, rank ...
     */
    if(!function_exists('categConfig')) {
        function categConfig($site='defsite',$category){
            $config = array();
            $site = strtolower($site);
            $category = strtolower($category);
            switch($site) {
                case 'defsite':
                switch($category){
                    case 'arts':
                        $config['grpLabel'] = 'Arts';
                        $config['tplAjaxResult'] = 'imgResult';      // allow the display of an image
                        break;
                    case 'music':
                        $config['grpLabel'] = 'Music';
                        $config['tplAjaxResult'] = 'imgAjaxResult';      // allow the display of an image
                        break;
                    case 'geography':
                        $config['grpLabel'] = 'Geography';
                        $config['tplAjaxResult'] = 'imgAjaxResult';
                        break;
                    case '':
                        $config['grpLabel'] = 'Site wide';
                        break;
                }
            }
            return $config;
        }
    }


==== Display the results

     &display [ 'mixed' | 'unmixed' ]

      When results comes from differents subsites (categories), you could choose to display the results mixed or unmixed.
      Default: unmixed
      Unmixed mode display the results grouped by site or subsite. Each group of results could be paginated.
      Mixed mode mixes all the results coming from the differents sites or subsites.
      With unmixed mode, results are ordered by the field provided by the first field of the order parameter
      e.g: if the subsite "products" has been defined with "product_name, supplier" as order parameter and
      the site "employees" has been defined with "job" as order parameter, then the results will be ordered by
      "using product_name" value for products and "job" value for "employees".


==== GrpResult & AjaxGrpResult templates

      &tplGrpResult - Chunk to style the non-ajax output group result outer
      &tplAjaxGrpResult - Chunk to style each output group result outer


==== Label for a group of results

      in the configuration file a label could be defined to be be linked with the group of results.
      This isn't a snippet parameter. Only a variable of configuration file.
	  This variable shouldn't contain a comma (",")

      $config['grpLabel'] = 'Arts (Painting)';


==== parents ( in / not in)

     &parents [ [ in | not in ] : comma separated list of Ids | '' ]

     e.g:
     &parents=`in:24,25` 	- do the search in the children documents of documents 24 and 25

     &parents=`not in:24,10` - do the search in all documents except in the children documents of documents 24 and 10 documents

     &parents=`24,25`  means &parents=`in:24,25` (compatible with the 1.8.4 release)
     &depth [ 0 < int ] Number of levels deep to retrieve documents


==== documents ( in / not in)

     &documents [ [ in | not in ] : comma separated list of Ids | '' ]

     e.g:
     &documents=`in:28,29,30,31` 	- do the search in the documents 28,29,30,31

     &documents=`not in:28,29,30,31` - do the search in all documents except in documents 28,29,30,31

     &documents=`28,29,30,31`  means &documents=`in:28,29,30,31` (compatible with the 1.8.4 release)


==== extracts

     Optimization of the extract algorithm.


==== Introduction of the document

    The first characters of the document are displayed when the search occurs with the "nowords" advSearch parameters
    or when a filter is applied without any search term.

    The length of the indroduction is provided by extractLength parameter (200 characters by default).
    The text displayed is the text defined by the extract parameter (content,description,introtext,tv_value by default)
    Obviously without any search term highligthed.


==== JQuery & mootools libraries updated with the last versions

     Jquery 1.4.2 & mootools 1.2.4 released with ajaxSearch 1.9.0


==== Javscript disabled

    define the css class "init" to mask the ajaxSearch_output div when javascript is disabled

    e.g:

    #ajaxSearch_output.init {
        border: none;
        background-color: #FFF;
    }

    #ajaxSearch_output  {
        font-size:90%;
        background-color:#EFEFEF;
        border:1px solid #6F9303;
        color:black;
        width:550px;
        z-index:1;
        padding:5px;
        margin:10px 0 15px 0;
    }


==== pcre_backtrack limit

     The backtrack_limit setting sets the maximum number of bytes preg is allowed
     to search over before it gives up. This limit is automatically set to 1600000
     at the beginning of the script and then restored to the initial value at the
     end of the script.


==== Language files updated

    Six labels have been added for english & french language files.
    Thanks to post the missing labels on the ajaxSearch forum board

    Used to display the number of results found:
    $_lang['as_resultsTextSingle'] = '%d result found.';
    $_lang['as_resultsTextMultiple'] = '%d results found.';

    Used to display the total number of results displayed:
    $_lang['as_resultsDisplayed'] = 'Displayed: %d';

    Used to display the number of results displayed by group:
    $_lang['as_grpResultsDisplayedText'] = '(Displaying %d - %d of %d)';

    Used by pagingType 1:
    $_lang['as_paging1Text'] = '%d - %d / %d';

    Used by pagingType 2:
    $_lang['as_paging2Text'] = 'Show more %d results';


==== AjaxSearch Logs manager - Follow up the searches of your users !

    A simple module is provided to display in the manager the last searches run by your
    users. This requires to use the asLog parameter.
    Use the file module.ajaxSearchLogManager.txt to set a new module.


==== Documentation folder

    in the documentation folder, the cheatSheet ajaxSearch192.pdf give a quick
    overview of AjaxSearch parameters. Thanks to Goldsky for this contribution.

    The someCssExamples folder give the search.css file used on the demo site to
    style ajaxSearch.

    The someConfigsExamples folder provide the configs folder used on the demo
    site.

    The someTemplatesExamples folder provide some templates used on the demo site.



