Amit a scriptaculousról tudni érdemes 5

Ami igazi életet pumpált és “én is azonnal akarom”-má tette az ajaxot az kétségtelenül az autocompletion, azaz az automatikus kiegészítés. Ez a bizgentyű bebizonyította, hogy igenis lehet újfajta, a usereknek hasznos elemeket építeni html alapokon. Ha szeretnénk a scriptaculous ezen eszközét használni akkor az alap JavaScript meghívásunknak tartalmaznia kell a controls modult, azaz minimálisan az alábinak kell lennie.

<script type="text/javascript" src="eleresi/ut/prototype.js">
</script>
<script type="text/javascript" src="eleresi/ut/scriptaculous.js?load=effects,controls">
</script>

Akár egy JavaScript fileban lévő stringekből álló tömbből akarjuk az automata kiegészítést használni az Autocompleter.Local objektummal, akár a szerverünktől várjuk a lehetséges találatokat az Ajax.Autocompleter objektummal a következőket biztosan meg kell adnunk.

• a szöveg mezőt (input) amelyben szeretnénk az auto-kiegészítést használni
• azt az elemet (többnyire div) amelyben meg kívánjuk jeleníteni a lehetséges kiegészítéseket
• azt, hogy honnan várjuk a lehetséges találatokat (tömbből a kliens oldalon vagy a szervertől)
• végül pedig az auto-kiegészítés opcióit

Autocompleter.Local

Ha a lehetséges találatokhoz nincs szükségünk a szerverrel való kommunikációra, mivel azok a kliens oldalon a rendelkezésre állnak – mert mondjuk az első oldalbetöltéskor úgy is letöltjük őket, vagy az első auto-kiegészítéskor letöltjük a teljes listát), akkor az Autocompleter.Local objektumot fogjuk addig csavarni amíg levet nem enged.

A JavaScriptünk szokás szerint rövid és édes.

var magyarMegyek = [
  'Bács-Kiskun',
  'Baranya',
  'Békés',
  'Borsod-Abaúj-Zemplén',
  'Csongrád',
  'Fejér',
  'Győr-Moson-Sopron',
  'Hajdú-Bihar',
  'Heves',
  'Jász-Nagykun-Szolnok',
  'Komárom-Esztergom',
  'Nógrád',
  'Pest',
  'Somogy',
  'Szabolcs-Szatmár-Bereg',
  'Tolna',
  'Vas',
  'Veszprém',
  'Zala'
  ];

document.observe('dom:loaded', function(){
  new Autocompleter.Local('megye', 'tippek', magyarMegyek)
  });

A html sem követhetetlenebb.

<form>
  Megye: <input type="text" id="megye" name="megye" size="35" />
  <div id="tippek"></div>
</form>

És még szükségünk lesz egy pici css-re, hogy a felkínált tippek ki is nézzenek valahogy.

#tippek{
  position:absolute;
  width:200px;
  border:thin solid #888;
  margin:0;
  padding:0.5em;
  background-color:#fff;
  }
#tippek ul{
  list-style-type:none;
  margin:0;
  padding:0;
  background-color:#fff;
  }
#tippek li{
  cursor:pointer;
  }
#tippek li.selected{
  background-color:#ff9;
  }

A tippek div-et a scriptaculous Autocompleter.Base objektuma kezeli, ami magától a megfelelő input mező alá fogja helyezni, találatok esetén megjeleníti, beállítja a szélességét, ha pedig már nincs szükség rá, akkor eltünteti. Nem szabad megfeledkeznünk arról, hogy a kiválasztott elemnél a selected css osztályt kell használnunk, mert csak.
Egérrel és billentyűzettel is választhatunk a felkínált elemek közül.

Finomhangolás

choices

maximum ennyi lehetséges találatot jelenít meg. 10 a default.

partialSearch

Alapértelmezett értéke true, melynek hatására minden forrásadat minden szavának elején keres egyezést, vagyis a “vi” begépelésénél a találatok között ott lesz a “Vidám Svábbogár” és a “Dinka Viktor” is. Ha false-ra állítjuk akkor a fentiekből csak a “Vidám Svábbogár” fog megjelenni, mert csak a szövegek elején keres egyezést.

partialChars

2 a default, ennyi karakter után indítja a keresést (nem feltétlen azonos a minChars-szal)

fullSearch

Alapértelmezett értéke false, melynek eredményeként csak a szavak elején keres egyezést. Ha a szóban bárhol megfelel számunkra az egyezés akkor true-t használjunk.

ignoreCase

Alapértelmezett értéke true, így nem veszi figyelembe a kis és nagybetűk közötti különbségeket.

Ajax.Autocompleter

Ha a szervertől várjuk a lehetséges találatokat, akkor ezt az objektumot fogjuk használni. Szintaxisában megyezik az Autocompleter.Local-lal, csupán itt adatforrásként egy tömb helyett egy url-t adunk meg. A szerver oldal az auto-kiegészülő input elemünk name paraméterét (nem az id-t!) kapja meg változóként, értéke pedig a begépelt karakterek lesznek. Válaszul a szervernek a találatokat egy xhtml kódolású ul li listában kell visszaadnia.

Mivel a szervertől várhatóan lassabban fogunk választ kapni mint a helyi keresés esetén (még localhoston is) ezért valahogyan a user tudtára kell hozni, hogy a háttérben kemény munka folyik. Erre általában egy kis kijelző képet hazsnálunk, amit az ajaxload.info lapról beszerezhetünk. Ha az auto-kiegészítő épp adatokat vár a szervertől, akkor megjelenítjük, egyébként elrejtjük. erre szolgál az indicator opció, ami egy dom elemet vagy id-t vár.

A html és a css ugyanaz mint a fenti példában, a JS-t kell némileg módosítani.

new Ajax.Autocompleter('nev', 'tippek', '/nevek.php');

Persze ehhez biztosan fog tartozni a szerver oldalon is valami kód, ami lehet bármi szerver oldali nyelven megírt kereső. Itt egy php-s példa.

<?php
header('Content-Encoding: utf-8');

Először is nem árt ha gondoskodunk arról, hogy a megfelelő karakterkódolással jöjjenek vissza az adatok. Ezen a ponton lehetnek némi problémáink, röviden arra kell törekedni, hogy minden szóbajöhető karakterkódolás (fileok, mysql, http) azonos legyen.

 
mysql_connect("localhost", "mysql_júzer", "aTitkosJelszó") or
    die("Kapcsolódás sikertelen: " . mysql_error());
mysql_select_db("azÉnKisAdatbázisom");
mysql_query('SET NAMES utf8');

Kapcsolódtunk az adatbázishoz, kiválasztottuk itt is a megfelelő karakterkódolást.

 
$parancs = "SELECT month, day, nameday
    FROM 108_nameday
    WHERE nameday LIKE '%" . htmlspecialchars($_POST['nev']) . "%'";

A parancsunk egy sima SQL parancs, itt a szavakon belüli egyezést is keresünk.

 
  $eredmeny = mysql_query($parancs)

print '<ul>';
while ($sor = mysql_fetch_array($eredmeny)){
  print '<li id="' . $sor['month'] . '-' . $sor['day'] . '">'. $sor['nameday'] .'</li>';
}
print '</ul>';
?>

Végül pedig legeneráljuk az xhtml kódot a listának.

Ha valaki botor módon nem telepítette még fel magának a Firebugot, akkor azt most haladéktalanul tegye meg, hogy szemmel tarthassa a kliens és szerver közötti kommunikációt a Console fülön.

Finomhangolás

method

Alapból 'post', de állíthatjuk éppen 'get'-re is. Az adatkommunikáció mikéntjét dönti el.

paramName

Alapból az input mezőnk name attribútuma kerül a szervernek változónévként elküldésre, de ezzel megváltoztatható

callback

az itt definiált függvény az input mezőt és az eddig begépelt karaktereket kapja meg, ezzel a függvénnyel hozzáadhatunk egy timestampet pl a paramétereinkhez

parameters

statikus paraméterek hozzáfűzése a lekérdezéshez query stringként.

A fentiek egy alkalmazása mondjuk így nézhet ki.

new Ajax.Autocompleter(
  'inputmezo',
  'eredmenydiv',
  'kereso.php',
  {
    method : 'get',
    paramName : 'aKeresettSzo',
    parameters : 'hivas=jsbol',
    callback : function(azInput, aKarakterek){
      var kIdo = aKarakterek + '&ido=' + new Date().getTime();
      return(kIdo);
      }
  }
  );

Ennek hatására a szerver felé a következő GET lekérés indul el:

kereso.php?aKeresettSzo=amitbegepelt&ido=117632378452&hivas=jsbol

select

annak a css osztálynak a neve ami a találatokra ráillik, ha a li elemen belül többminden is van nem csak szöveg.
Például ha a találati listánk így néz ki, akkor az opciók között ott kell lennie a {select : ‘anev’}-nek.

<li>
  <img src="ff.png" />
  <span class="anev">Szomorkáns Hörcsög</span>
  <span>Romantikus Horrorfilm</span>
</li>

tokens

Sokszor az is előfordul, hhogy azt szeretnénk, hogy a user egynél több dolgot is beírhasson az auto-kiegészülő inputba. Ebben az esetben a tokens opcióval adhatjuk meg azt az elválasztó karaktert stringként, vagy azokat az elválasztó karaktereket tömbként amelyek elválasztják az egyes szavakat egymástól. Ha ezt használjuk, akkor beírunk egy név töredéket, kiválasztjuk, nyomunk egy vesszőt, és elkezdhetjük az új név gépelését.

Nevek vesszővel elválasztva:

onShow

ez a tulajdonság gondoskodik a találati box elhelyezéséről és megjelenítéséről. Alapértelmezés szerint 0,15 mp alatt az Effect.Appear effektet használja.

afterUpdateElement

akkor hívódik meg amikor a találatok közül kiválasztunk valamit. Két paramétert kap, az inputot és a kiválasztott li-t. a magam részéről ide egy submitot (vagy azt helyettesítő függvényt) szoktam általában tenni.

onHide

a találati box elrejtése. Alapból 0,15 mp alatt az Effect.FadeOut fut le.

Remélem ezután már senkit semmi nem tart vissza attól, hogy a felhasználói kezébe adja ezt a népszerű kényelmi és használhatóságot növelő funkciót. A sorozat következő részében DOM-ot fogunk építeni a scriptaculous aranyos kis kőműveskanalával.