Have you ever wondered how you can programatically create an autocomplete form element in Drupal? This tutorial will show you how to develop a form that contains a text field autocomplete widget that uses the Drupal Ajax Framework to dynamically retrieve content from your database.

To illustrate this in an example, I have created a table in my database that holds some colors (green, blue, red, etc). In your case this will probably be something more advanced, but you’ll get the point. Moreover, I created a custom page that displays a form with an autocomplete widget that queries the database as you start typing in it:

OK, so this simple example requires three functions: one to register some URL paths with Drupal, one to create the form that houses our autocomplete widget and one that retrieves the data from the database. This is actually the order I am going to write them in, explaining after each what the purpose of the code is.

function demo_menu() {
  $items['demo-autocomplete-test'] = array(
    'title' => 'Test autocomplete',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('demo_form'),
    'access arguments' => array('access content'),
    'type' => MENU_NORMAL_ITEM,
  );

  $items['demo-autocomplete-engine'] = array(
    'page callback' => 'demo_autocomplete',
    'access arguments' => array('access content'),
    'type' => MENU_CALLBACK,
  );
  return $items;
}

This first function implements the Drupal hook_menu(), one of the most useful ones out there. We use it to register with Drupal two URL paths: one for accessing our form that holds the autocomplete widget (demo-autcomplete-test) and one for the AJAX to use as a source for the autocompletion (demo-autocomplete-engine).

Without going too much into how to use this hook, I will make a couple of observations. The first menu item that is declared is given some attributes. We basically say that when a user navigates to www.example.com/demo-autocomplete-test, the respective page should have the title you see, and if the user has the appropriate access permissions, s/he should see the form called demo_form (that we will next create). The second menu item is not used for navigation but to provide the AJAX with a path to use for the autocompletion. You’ll see in a minute what I mean.

Let's see the second function:

function demo_form($form, &$form_state) {
  $form = array();

  $form['colors'] = array(
    '#title' => t('Colors'),
    '#type' => 'textfield',
    '#maxlength' => 60,
    '#autocomplete_path' => 'demo-autocomplete-engine',
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => 'Submit',
  );

  return $form;
}

This function creates our testing form that contains an autocomplete widget. Two form items are declared: a textfield for the colors and a submit button. In order to turn a regular Drupal Form API textfield into an autocomplete widget, we need to give it a special attribute: #autocomplete_path -> the source for the autocompletion data to be run by the AJAX script. This is the path we registered in the previous function and gave it a callback function: demo_autocomplete.

So basically when the user starts typing into this textfield, an AJAX call will be made to that path, triggering this callback function that we now need to declare:

function demo_autocomplete($text) {
  $results = array();

  $query = db_select('colors', 'c');
  $query
      ->condition('c.color', '%' . db_like($text) . '%', 'LIKE')
      ->fields('c', array('color'))
      ->orderBy('color', 'ASC');
  $colors = $query->execute();

  foreach ($colors as $row) {
    $results[$row->color] = check_plain($row->color);
  }

  drupal_json_output($results);
}

I mentioned in the beginning that for this example I created a table to store color names in. Well this function does a simple thing: searches through that table using a wildcard and returns the results in a JSON format for the AJAX call. A parameter is passed to the function ($text) which represents the text string to be searched in the database. So to better understand what’s happening here, imagine the following:

As soon as the user types a letter into the texfield, an AJAX call is made and the search is performed in the table for all the colors that contain that letter. As the user types more letters, more searches are performed and the results displayed like in the image I showed you in the beginning. The cool thing is that this is being done dynamically without page refresh using AJAX.

Hope this was clear and helped you understand how you can use this technique in your development. If you have any questions, feel free to drop a line in the comments.