Autocomplete

The autocomplete fields are text inputs that, as soon as the user starts typing into them, will give suggestions based on what has been typed so far.

Contents 1 How to build an autocomplete field 1.1 Database 1.2 Controller 1.3 View 2 The Tool complement 2.1 Database 2.2 Controller 2.3 View 3 Example 4 Troubleshoot

How to build an autocomplete field

Database

First, you must define your field in structure_fields and specify "autocomplete" as type. Then, you need to define the url parameter. This is the url of the view that will generate the autocomplete suggestions. This url must be defined in the setting field.

url=/path/to/my/view/

Controller

Your controller will receive the typed string into $_GET['term']. What you usually want to do with it is a search for matching strings into the database. Here is an example with storage labels.

//query the database
$storage_masters = $this->StorageMaster->find('all', array(
	'conditions' => array(
	'StorageMaster.Selection_label LIKE' => $_GET['term'].'%'
	),
	'fields' => array('StorageMaster.selection_label'),
	'limit' => 10
));

//build the textual result array
$result = "";
foreach($storage_masters as $storage_master){
	$result .= '"'.$storage_master['StorageMaster']['selection_label'].'", ';
}
if(sizeof($result) > 0){
	$result = substr($result, 0, -2);
}
//set the result variable to hand it to the view
$this->set('result', "[".$result."]");

//set the layout as ajax so that no frame is being printed
$this->layout = 'ajax';
//set debug 0 to make sure the autocomplete works every time (otherwise the debug info breaks the javascript textual array)
Configure::write('debug', 0); 

In this example we are searching for matching labels. The results needs to be returned as a textual javascript array. Those have the form

[ "foo", "bar", "grid" ]

Once the array is built, we set the result variable to hand it over to the view. Then, we set the layout as being ajax so that no frame is printed around our content. We also set debug to 0 to make sure no debug queries are outputted. Should they be outputted, the javascript array would be followed by debugging info and the receiver would be unable to handle the data.

View

The view will not be displayed; it is only a mean to return data to the querying script. All we have to do is to print the javascript array.

<?php echo($result); ?>

The Tool complement

Autocomplete fields can have a tool associated to them. The so said tool is a pop-up that helps the user to select a proper value for the field. When an autocomplete field has a tool associated to it, a "Tool" link will appear at the right of the input.

Database

To enable the autocomplete tool, you must define a tool parameter in the setting field of the structure_fields entry of your field. The tool parameter is an url pointing to your tool view. You usually want to pass the field id associated to your tool to allow the javascript script to put the value in the right place. Of course, your controller needs to handle that field_id.

tool=/path/to/your/tool/field_id

Note: Settings are separated by commas.

Controller

One thing is important in the controller. You probably don't want to have any headers, hence you need to specify

$this->layout = 'none';

Furthermore, you probably want your view to receive the field id.

this->set( 'field_id', $field_id );

View

Two things might be helpful in the view.

1. You might want to update the view based on some select fields. To do so, you can refresh your tool pop-up with a javascript call to Ajax.Updater. One of the possible ways is to pass the pop-up div id as the first parameter (lightwindow_contents) and the url of your tool + the parameters as a second parameter. At this point, you most likely want your controller to take more parameters, like the selected options, to use them as a filter.
2. You might want to create a button that will copy some value to the autocomplete form and close the tool pop-up at the same time. This is where the autocomplete field id becomes handy. To close the pop-up, you have to make a javascript call to myLightWindow.deactivate();

Example

To see in production example, refer to the codingicd10 plugin.

Troubleshoot

Problem	Possible cause	Solution
When I start typing in the field I have no suggestions.	You do not have permission to access the tool.	Have an administrator grant you the permission.
When I click on the tool link, the pop-up content is the page itself.	You do not have permission to access the tool.	Have an administrator grant you the permission.
When I click on the tool link, rather than having a pop-up I'm redirected to a page with the pop-up content.	The pop-up script is not properly loaded.	Verify that you have no javascript error and that the script file exists.