Drupal autocomplete

Één van de mogelijkheden van Drupal die wat minder goed belicht wordt op het internet is de ingebouwde autocomplete mogelijkheid. Een autocomplete formulierveld geeft suggesties voor de invoer als je nog aan het typen bent. Handig als je lange dingen moet invoeren of als je niet precies weet wat je nou moet typen. Als je bijvoorbeeld iemand wil zoeken, maar alleen een stukje van de achternaam weet. Dit voer je dan in en je krijgt automatisch een lijstje te zien met alle namen waar dat stukje in voor komt.

Voor deze tutorial is het belangrijk dat je basiskennis van PHP en MySQL hebt. Ook moet je weten hoe je in Drupal modules en dynamisch formulieren maakt. Informatie over formulieren staat in Forms API Quickstart Guide.

Een autocomplete `<input>` maken

Als eerste maken we het invoerveld voor de autocomplete:

<?php
$form['translation_options']['original_author'] = array(
  '#type' => 'textfield',
  '#autocomplete_path' => 'modulenaam/autocomplete', 
);
?>

Slechts twee eigenschappen voor het invoerveld zijn noodzakelijk: #type en #autocomplete_path. Autocomplete velden namelijk alleen text inputs kunnen zijn. #autocomplete_path is het adres waar de autocomplete input zijn data vandaan haalt. Gebruik een adres dat uniek is voor jouw module. De handigste manier is zorgen dat de naam van de module in het adres voor komt.

Het adres aanmaken

We laten het invoerveld verwijzen naar een adres, maar dat moet wel bestaan. Hiervoor hebben we hook_menu() nodig. Wat we uiteindelijk moeten doen is een pad aanmaken dat een functie aanroept die op zijn beurt weer de data teruggeeft. Paden worden in Drupal aangemaakt via het menu, dus we moeten ook nog aangeven dat er geen pagina achter het adres hangt met MENU_CALLBACK:

<?php
$items[] = array(
  'path' => 'modulenaam/autocomplete',
  'access' => TRUE,
  'callback' => 'modulenaam_autocomplete',
  'type' => MENU_CALLBACK,
);
?>

path geeft logischerwijze aan welk pad er geregistreerd wordt. access moet TRUE zijn, anders heeft de bezoeker geen toegang tot dit adres. Aangezien we willen dat iedereen het autocomplete veld kan gebruiken, vullen we TRUE hardcoded in. Bij callback moet je invullen welke functie aangeroepen moet worden als dat adres opgevraagd wordt. Onze functie is modulenaam_autocomplete(), dus dat vullen we in.
Opmerking: De haken die achter de functie staat moeten niet ingevuld worden.
Als laatste melden we Drupal nog even dat dit adres een zogenaamde MENU_CALLBACK is. Dit houdt in dat er geen pagina opgevraagd wordt, maar dat alleen een functie wordt aangeroepen.

De dataverwerking

Okee, we hebben nu een invoerveld, we hebben gezorgd dat dat invoerveld contact kan zoeken met de functie die voor de data zorgt, maar die functie zelf hebben we nog niet. De opzet is heel simpel:

<?php
$matches = array();
$result = db_query("SELECT achternaam FROM {personen} WHERE LOWER(achternaam) LIKE LOWER('%%%s%%')", $_GET['needle']);
while ($match=db_fetch_object($result)) {
  $matches[] = check_plain($match->achternaam);
}
echo drupal_to_js($matches);
?>

$_GET['needle'] is de tekst die jij in het invoerveld invult. Hierop zoeken we in de database en de resultaten slaan we op in de array $matches. Met drupal_to_js() maken we van deze PHP array een JSON object dat we echoën.

Slot

Sowieso is AJAX al niet zo moeilijk, maar doordat Drupal veel functies al ingebouwd heeft (bijv. dynamisch formulierelementen voor autocomplete aanmaken) wordt het een eitje.
Opmerking: Zorg dat /misc/autocomplete.js ingevoegd wordt in de pagina. Zonder dit bij Drupal meegeleverde script werkt de autocomplete niet