A often meet case is to have a incremental search. Each time a search parameter is selected the following parameter is completed.

Let's now take a concrete case: We keep the same database as in the above sample. Imagine we have a select field that is initialised with the towns names. When you choose a city, a select fields containing all the streets of the town appears. When you choose a street the final search is launched.

As mentioned above we have to set the search.ini file

    dsn = SEARCHDSN
    ; Do not forget to add  EncoderClass.myencoding_context = EncoderISO 
    ;(or any other context) 
    ; in your client_conf/client.ini
    
    config.Adresses_init_town.provider.type = table
    config.Adresses_init_town.provider.table = addresses
    config.Adresses_init_town.provider.aliases = adr_town, town
    config.Adresses_init_town.provider.id = adr_town
    config.Adresses_init_town.provider.columns = adr_town
    config.Adresses_init_town.provider.sortColumn = adr_town
    config.Adresses_init_town.provider.sortDirection = asc
    config.Adresses_init_town.formatter.type = smarty
    config.Adresses_init_town.formatter.template = init_adresse_town_select
    
    config.Adresses_init_street.provider.type = table
    config.Adresses_init_street.provider.table = addresses
    config.Adresses_init_street.provider.aliases = adr_street, street, adr_town, town
    config.Adresses_init_street.provider.id = adr_street
    config.Adresses_init_street.provider.columns = adr_street
    config.Adresses_init_street.provider.sortColumn = adr_street
    config.Adresses_init_street.provider.sortDirection = asc
    config.Adresses_init_street.provider.where = "adr_town like '@adr_town_init@'"
    config.Adresses_init_street.formatter.type = smarty
    config.Adresses_init_street.formatter.template = init_adresse_adr_street_select
    
    
    config.Adresses.provider.type = table
    config.Adresses.provider.table = addresses
    config.Adresses.provider.aliases = adr_num, num, adr_street, street, adr_zip, zipcode, adr_town, town
    config.Adresses.provider.id = gid
    config.Adresses.provider.columns = adr_num, adr_street, adr_zip, adr_town
    config.Adresses.provider.sortColumn = adr_num
    config.Adresses.provider.sortDirection = asc
    config.Adresses.provider.sortPriorities = adr_num, adr_street, adr_zip, adr_town
    config.Adresses.formatter.type = smarty
    config.Adresses.formatter.template = search_results
    config.Adresses.provider.where = "adr_street like '@adr_street_init@' and adr_town like '@adr_town_init@'"
                    
                

As you can see, we have have declared 3 search configurations that are pointing on the same database entity. The first two tables are used for initializing the select. They are not of type FullTextTable as we do not want to use the default search comportement. So the provider.label and provider.fulltextColumns are not used. There is also a new configuration parameter that is :

    config.Adresses.provider.where

This parameter allows to specifiy a where clause. The where clause is written in traditional sql but the data corresponding to the value of the form have to be replaced by @the_field_name@.

For the first two tables, the template file have been modified in order not to give back a result table but a select containing all the data required

    config.Adresses_init_street.formatter.type = smarty
    config.Adresses_init_street.formatter.template = init_adresse_adr_street_select 
                

Here is the content of the init_adresse_town_select.tpl file :

                    
    {t}Town:{/t}<br />
    <select name="search_adr_town_init" id="search_adr_town_init"  
      onchange="javascript: initializeStreet()">
        <option value="">&nbsp </option>
            {foreach from=$table->rows item=row}
            <option value="{$row->rowId}">
                {foreach from=$row->cells item=value}
                {$value}
                {/foreach}
            </option>
            {/foreach}
    </select>
                

Here is the content of the init_adresse_adr_street_select.tpl file :

    {t}Street:{/t} <br />
    <select name="search_adr_street_init" 
      id="search_adr_street_init" onchange="search()" >
        <option value="">&nbsp </option>
            {foreach from=$table->rows item=row}
            <option value="{$row->rowId}">
                {foreach from=$row->cells item=value}
                {$value}
                {/foreach}
            </option>
            {/foreach}
    </select>
                    
                

Now we have to setup the search.tpl file.

                    
    <div id="search_div">
    <fieldset><legend>{t}My Title{/t}</legend> <br/>
      here we inser the placeholder for the select(s)
      <br />
      <div id="town_select_div"> Here comes the list containing the towns </div>
      <br />
      <div id ="street_select_div"> Here comes the list containing the streets  </div>
      <br />
      <input type="hidden" id="search_config" name="search_config" value="" />
      <input type="hidden" id="search_sort_column" name="search_sort_column" value=""/>
      <input type="hidden" 
        id="search_sort_direction" name="search_sort_direction" value="asc" />
      <input type="hidden" id="search_number" name="search_number" />
    <div id="search_results_div"></div>
    </fieldset>
    </div>         
                             
                

Finally we have to set up the java script file. Open or create the plugins/search/htdocs/js/Search.ajax.js file and write:

    AjaxPlugins.Search = {

      handleResponse: function(pluginOutput) {
        //we inject the select input in the HTML
        if (pluginOutput.htmlCode.Adresses_init_town) { 
          //should be the same value as the input search_config
          $('town_select_div').innerHTML = pluginOutput.htmlCode.Adresses_init_town;        
        }  

        if (pluginOutput.htmlCode.Adresses_init_street) { 
          //should be the same value as the input search_config
          $('street_select_div').innerHTML = pluginOutput.htmlCode.Adresses_init_street;        
        }  

        if (pluginOutput.htmlCode.Adresses) { 
          //should be the same value as the input search_config
          $('search_results_div').innerHTML = pluginOutput.htmlCode.Adresses;        
        }
      }
    };


    /*
    * Search plugin's Actions
    */

    AjaxPlugins.Search.Actions = {};

    AjaxPlugins.Search.Actions.DoIt = {

      buildPostRequest: function(argObject) {
        return AjaxHandler.buildPostRequest();
      }
    };

    function order(column) {

      if (column != $('search_sort_column').value) {
        $('search_sort_column').value = column;
        $('search_sort_direction').value = 'asc';
      } else {
        if ($('search_sort_direction').value == 'asc') {
          $('search_sort_direction').value = 'desc';
        } else {
          $('search_sort_direction').value = 'asc';
        }
      }

      CartoWeb.trigger('Search.DoIt')
    }

    //we empty the old selects and reinsert the new ones instead
    //Please do not forget to modify the search_config input value
    function initializeTown() {
    $('town_select_div').innerHTML = '';
         var myinput = $('search_config');
         myinput.value = 'Adresses_init_town';
         CartoWeb.trigger('Search.DoIt');
    }

    function initializeStreet() {
        $('street_select_div').innerHTML = '';
        var myinput = $('search_config');
        myinput.value = 'Adresses_init_street';
        CartoWeb.trigger('Search.DoIt');
    }

    function search() {
        var myinput = $('search_config');
        myinput.value = 'Adresses';
        CartoWeb.trigger('Search.DoIt');
    }

    function recenter(id){
        if ($('search_config').value == 'Adresses') {
            //id to recenter, be sure there is a hidden input 
            //with that name and id in your template! if not, add it
            $('id_recenter_ids').value = id;

            /* if the search database table name is the same 
            as the related layer to recenter on, you can set it as below
               be sure there is a hidden input with that name and id in your template! if not, add it */
            $('id_recenter_layer').value = $('search_config').value;

            /* do not use the recenter_scale parameter 
            if you recenter on ids, only use it with recenter on x,y.
               you can set the recenter scale in location.ini on server side */
            
            /* do not use the recenter_doit parameter 
            if you recenter on ids, only use it with recenter on x,y. */

            CartoWeb.trigger('Location.Recenter');
        }
    }
    Event.observe(window, 'load', initializeTown, true);
                

For each initialisation, we have to set the correct value inside the search_config input and add a "onload" event in order to initialize the town select when the page is loaded.

Event.observe(window, 'load', initializeTown, true);

Sometimes, you may want to have a search that is done on multiple tables. It can be done easily. You have just to use the mechanisms presented in the basic sample and create in the search.ini a table that looks like this:

    config.parcels.provider.type = table
    config.parcels.provider.table = parcelles, addresses
    config.parcels.provider.aliases = adr_num, num, adr_street, street, adr_zip, zipcode, adr_town, town
    ;//be sure not to have twice the same id column name in different tables (or use aliases)
    config.parcels.provider.id = parcel_id 
    config.parcels.provider.columns = parcel_ref, adr_street
    config.parcels.provider.fulltextColumns = parcel_ref, adr_num, adr_street, adr_zip, adr_town,
    config.parcels.provider.sortColumn = parcel_ref, adr_street
    config.parcels.provider.sortDirection = asc
    config.parcels.formatter.type = smarty
    config.parcels.formatter.template = search_results
    config.parcels.provider.labels = parcel_ref, street
    config.parcels.provider.where = "adr_street like '%@adr_street@%' AND addresses.parcel_ref = parcels.parcel_ref"
                               
            

In this sample we have a search that is done on a table adresses and a table parcels where a parcel contains many adresses. The search return all the streets where the name matches the name given in the form and their corresponding parcel reference.

A provider is an interface implementation that allows you to acess a type of data that is not supported by PEAR DB.

You have to modify the Search.php. In this file there is an abstract class that is named :

    abstract class ResultProvider 

You have to extend this class :

    class MyResultProvider extends ResultProvider {
        public function getResult(SearchRequest $request) {
            $table = New Table();
            $table->tableId = 'search';
            $table->columnIds = array('col1');
            $table->noRowId = false;
            $table->rows = array('hello world');
            $table->numRows = $dbResult->numRows();
            // Generates pages information
            $table->rowsPage = 1;
            $table->totalPages = 1;
            $table->page = 1; //curent page number
            $result = new SearchResult();
            $result->table = $table;
            return $result;
        }
    }
                

You have to implements the getResult fonction. It should return a Table() instance.

A formatter allows you to format the result of the query. Actually it returns code generated by Smarty. But if you want to use an other template engine or a more specifique formatter (JSON for example or in our case a smarty with differents delimiters), you have to modify the ClientSearch.php

In this file there is an abstract calss :

abstract class ResponseFormatter 

you have to extend this class

 
    /**
    * Formats a response using a Smarty template with different separators
    * @see ResponseFormatter
    */
    class MYSmartyResponseFormatter extends ResponseFormatter {
   
        /**
        * @see ResponseFormatter::getResponse()
        */
        public function getResponse(SearchResult $result) {
    
        $smarty = new Smarty_Plugin($this->plugin->getCartoclient(),
        $this->plugin);
        $smarty->right_delimiter = '[EOF';
        $smarty->left_delimiter  = 'EOF]';
        $smarty->assign('table', $result->table);
        return $smarty->fetch($this->template . '.tpl');
        }
    }
                

You have to implements the getResponse function. It should return a string.The $result variable correspond to the value return by the provider.