MyCashflow blogi

Miska kirjoitti 22.2.2011 kategoriaan Interface-merkkaus avainsanoilla Interface tagit Interface-merkkaus: 0

Kuinka toteuttaa livehaku omassa teemassa

Tässä ulkoasun suunnittelijoille tarkoitetussa ohjeessa käymme läpi kuinka on mahdollista toteuttaa livehaku omaan MyCashflow teemaan. Uusimmassa ladattavassa oletusulkoasussa tulee kyseinen ominaisuus mukana ja käytämmekin oletusulkoasun skriptejä esimerkissä ja puramme ne osiin.

Livehaku on äärimmilleen yksinkertaistettuna Interface-tagille lähetetty Ajax-kutsu muutamalla parametrillä. Jos tagi palauttaa onnistuneesti jotain, niin tämä palautus sitten tulostetaan listaan ja näytetään. Tietystihän todellisuus on aina hieman monimutkaisempi, mutta käydään oletusteeman koodi pala palalta läpi, niin huomaatte, ettei se kovin hankalaa ole.

Esimerkkikoodi vaatii toimiakseen jQueryn lisäksi myös typeWatch nimisen pluginin, joka on näppärä pikku skripti, jolla pidämme huolen ettei hakua aloiteta turhaan, vaan vasta sitten kun käyttäjä on lopettanut kirjoittamisen.

Esimerkkikoodi

var mcfLiveSearchResultsWidth = $("#SearchForm").css("width");
$("#SearchForm").append($('<ul id="LiveSearchResults" style="width: '+ mcfLiveSearchResultsWidth +'"></ul>').hide());

Alussa kaappaamme hakulomakkeen lomakkeen leveyden muuttujaan, sekä luomme hakukentän perään tyhjän listan, joka samalla piilotetaan ja jonka leveydeksi asetetaan hakulomakkeen lomakkeen leveys, jotta hakutulokset asettuvat kyseisen elementin kanssa nätisti linjaan.

$("#SearchInput").typeWatch({
  highlight:true,
  wait: 500,
  callback: function(txt) {

Seuraavaksi asetamme typeWatch pluginin tarkkailemaan muutoksia hakukentässä siten, että kun 500ms on kulunut viimeisimmästä näppäimen painalluksesta, suoritetaan asettamamme callback-funktio ja käyttäjän hakukenttään kirjoittama teksti asetetaan muuttujaan txt.

    $("#AjaxMsg").text("Haetaan");

Tulostamme ilmoitukseen tiedon kävijälle siitä, että jotain tapahtuu. Oletusulkoasussa on käytetty jQueryn globaalia ajaxStart tapahtumaa siten, että AjaxMsg elementti näytetään aina Ajax-pyynnön käynnistyessä ja teksti vaihtuu tapahtuman mukaan.

    $.ajax({
      url: "/interface/SearchProducts",
      data: {
        query: txt,
        limit: 5,
        helper: "helpers/livesearchresults"
      },

Tässä ovat Ajax-pyyntömme parametrit, joista pakollisia ovat vain url, joka on osoite jonne Ajax-pyyntö lähetetään ja data objektin query parametri, jonne haemme hakukenttään kirjoitetun tekstin. Livehaku pyytää hakutuloksia osoitteesta, jota voidaan käyttää myös Interface-tagien käyttämiseen MyCashflow’n ulkopuolella ja tästä löytyykin lisätietoa ohjeestamme.

Lisäksi asetamme tässä parametrin limit, joka rajaa tulostettavien tuotteiden määrän viiteen (vastaa Interface tagien limit attribuuttia), sekä helper parametrillä kerromme kutsulle, että haluamme käyttää tuotteiden tulostukseen helpers/livesearchresults.html tiedostoa (vastaa helper attribuuttia).

      beforeSend: function() {
        $(".SearchIndicator","#SearchForm").fadeIn(500);
      },

BeforeSend on funktio joka suoritetaan juuri ennen kuin Ajax-pyyntö lähetetään. Tässä tapauksessa funktio näyttää hakulomakkeen sisälle tulostetun hakuindikaattori elementin, jolle on CSS-tiedostossa asetettu taustakuvaksi latausanimaatio.

      success: function(results) {
        $('#AjaxMsg').slideUp(250);
        $("#LiveSearchResults").html(results).fadeTo(500,0.9);
        $(".SearchIndicator","#SearchForm").addClass("CloseSearchResults").click(function() {
          $("#SearchInput").val("").blur();
          $("#LiveSearchResults").html("");
          $(this).hide().removeClass("CloseSearchResults");
        });
      }

Success on funktio, joka suoritetaan, kun ajax-kutsu on mennyt onnistuneesti läpi. Funktion ensimmäinen argumentti sisältää palvelimen palauttaman tulostuksen ja tässä asetamme argumentin muuttujaan nimeltä results.

Ensimmäiseksi funktion sisällä liu’utamme AjaxMsg ilmoituksen pois näkyvistä, koska emme lataa enää tuotteita. Seuraavaksi tulostamme luomamme LiveSearchResults listan sisälle results muuttujan sisällön, eli itse hakutulokset sekä häivytämme hakutuloslistan näkyviin.

Lopuksi lisäämme hakuindikaattorille luokkanimen CloseSearchResults, joka vaihtaa elementin taustakuvan latausanimaatiosta ruksiksi, sekä liitämme elementin klikkaus tapahtumaan funktion, jolla voidaan piilottaa hakutulokset, tyhjentää hakukenttään kirjoitetut hakusanat ja piilottaa hakuindikaattori eli käytännössä perua haku.

    })
  }
}).attr("autocomplete","off").after('<span class="SearchIndicator"></span>').keyup(function() {
  if ($(this).val()==="") {
    $("#LiveSearchResults").html("");
    $(".SearchIndicator","#SearchForm").hide().removeClass("CloseSearchResults");
  };
});

jQueryn kätevän ketjutuksen avulla lisäämme vielä lopuksi aivan ketjun alussa valitulle SearchInput hakukenttäelementille attribuutin, joka estää selainten omat automaattiset täydennystoiminnot, sekä tulostamme tässä kohtaa hakuindikaattorielementin, jota aiemmin koodissa jo käytettiin.

Lisäksi lopussa tarkistamme jokaisen näppäimen vapautuksen yhteydessä onko hakukenttä kokonaan tyhjä ja mikäli on, niin piilotamme hakuindikaattorin, sekä poistamme siltä mahdollisen CloseSearchResults luokkanimen, joka määräsi onko hakuindikaattorin taustakuva latausanimaatio vai ruksi, jolla hakukentän voi piilottaa. Tämä sitä varten, että kun käyttäjä hakee heti uudestaan, ja luokkanimeä ei olisi poistettu, niin latausanimaation tilalla näkyisi ruksi.

Tässäpä se livehaku sitten olisi levällään kuin Jokisen eväät. Toivottavasti tästä julkisesta levittelystä joku oppikin jotain ja mikäli joku kohta tuntuu sekavalta, niin se johtuu todennäköisesemmin kirjoittajan sekavasta ulosannista, kuin lukijan käsityskyvyn rajallisuudesta. Tässä tapauksessa kannattaa laittaa kysymystä rohkeasti kommentteihin, niin pyrin auttamaan mahdollisten ongelmien kanssa.