Yhden sivun kassan osien päivittäminen AJAX-pyynnöillä

Yhden sivun kassalla kaikki kassan osat sijaitsevat samalla sivulla. Kassan osiin syötetty sisältö vaikuttaa muihin kassan osiin, joten osien sisältö on syytä päivittää aina kun muihin osiin tehdään muutoksia. Esimerkiksi toimitusosoite vaikuttaa käytettävissä oleviin toimitustapoihin, joten toimitustavat on syytä päivittää aina kun tilauksen postinumeroa tai kohdemaata muutetaan.

Koko sivua ei kannata päivittää uudestaan aina kun asiakas tekee muutoksia, vaan lähettää tiedot JavaScriptillä AJAX-pyyntönä palvelimelle, ja hakea kaikki lähetetyistä tiedoista riippuvaiset osat erillisellä AJAX-pyynnöllä.

Yhden sivun kassan jQuery-plugin

Yhden sivun kassan osien päivittämistä helpottamaan olemme kehittäneet jQuery-pluginin, joka tarkkailee lomakkeen muutoksia ja päivittää kassojen osia lennosta riippuen siitä, mitä kassan osaa on muutettu.

Pluginin käyttämisen vaatimukset ovat, että jQuery on ladattuna ja että kassasivulta löytyvät kaikki yhden sivun kassan vaatimat osat HTML-elementtien sisältä, joiden id on sama kuin tagin nimi, esimerkiksi:

<fieldset class=”TagWrapper” id=”CheckoutShippingAddress”>
    {CheckoutShippingAddress(
        mode: ’form’,
        ajax: ’true’
    )}
</fieldset>

Plugin alustetaan seuraavalla tavalla, jos ei haluta muokata mitään pluginin asetuksia:

$(’.TagWrapper’).mcfOnepageCheckout();

Esimerkissä kaikilla kassan lomaketageilla pitäisi olla ympärillään esimerkiksi <div>- tai <fieldset>-elementti, jolla on luokkanimi 'TagWrapper', jolloin kassan plugin tutkii elementin sisällä tapahtuvia muutoksia ja lähettää elementin sisällä olevan lomakkeen osan tarvittaessa palvelimelle.

Plugin lähettää tietoja palvelimille seuraavissa tilanteissa:

1. Kun käyttäjä on muuttanut jotain lomakkeella ja fokus siirtyy pois lomakkeen osasta (esimerkiksi asiakastietoja on muokattu ja käyttäjä siirtyy muokkaamaan toimitusosoitetta tai klikkaa muuten lomakkeen ulkopuolelle)
2. Kun käyttäjä ei ole muokannut lomaketta vähään aikaan
3. Kun toimitusmaata muutetaan asiakastiedoissa tai toimitusosoitteessa
4. Kun toimitus- tai maksutapaa muutetaan

Kun tiedot on lähetetty, plugin hakee automaattisesti kaikki lähetetyistä tiedoista riippuvat osat ja kirjoittaa ne elementteihin, joiden id on tiedoista riippuvaisen tagin nimi.

Esimerkiksi kun asiakas päivittää toimitusosoitteen, plugin etsii elementin, jonka id on 'CheckoutShippingMethods', ja kirjoittaa toimitustapojen valinnan uudelleen tuon elementin sisään.

Pluginin asetukset

Kassapluginilla on muutamia hyödyllisiä tapahtumia ja asetuksia joiden avulla voidaan lisätä teemaan esimerkiksi latausanimaatio jota näytetään silloin kun kassan osia päivitetään.

Alla yksinkertaistettu esimerkki kuinka latausanimaatio on lisätty vanhan oletusteeman pluginin avulla:

$(’.TagWrapper’).mcfOnepageCheckout({
    // Ajetaan, kun riippuvuuden hakeminen alkaa
    get_start: function(el) {
        // Lisätään latausanimaatiota varten elementti
        el.append(’<div class=”CheckoutLoader”></div>’);
    },

    // Ajetaan, kun tietojen lähetys palvelimelle alkaa
    post_start: function(el) {
        // Lisätään latausanimaatiota varten elementti
        el.append(’<div class=”CheckoutLoader”></div>’);
    },

    // Ajetaan, kun yksittäinen tietojen lähetys on valmistunut
    post_success: function(el) {
        // Poistetaan latausanimaatio
        $(’.CheckoutLoader’, el).remove();
    },

    // Ajetaan, kun yksittäinen riippuvuus on ladattu
    get_success: function(el, response) {
        // Poistetaan latausanimaatio
        $(’.CheckoutLoader’, el).remove();
    },

    // Ajetaan, kun kaikki ajax-pyynnöt ovat valmistuneet
    complete: function(el) {}
});

Esimerkin eri tapahtumien kohdalla on helppo myös liittää esimerkiksi muut jQuery-pluginit uudestaan kassan osiin, mikäli kaupan lomakkeilla on niitä käytetty.

Katso myös pluginin asetusten tarkempi esittely.

Kassan ilmoitukset

Kassalla tarvitsee lisäksi tulostaa ilmoituksia esimerkiksi silloin kun asiakastiedot ovat puutteelliset. Ilmoitukset saadaan tulostettua yhden sivun kassalla kahdella tavalla:

<fieldset class=”TagWrapper” id=”CheckoutBillingAddress”>
    <div class=”Notification Error”>
        <p>Ole hyvä ja täytä kaikki kentät. Tarvitsemme osoitetietojasi tilauksen toimittamista ja siihen liittyviä yhteydenottoja varten.</p>
    </div>
    ...
</fieldset>

$.ajax({
    type: ’POST’,
    url: ’/checkout/’,
    data: {
        response_type: ’json’
    },
    cache: false,
    success: function(response) {}
});

Esimerkki toimii sekä lähetettäessä (POST) että hakiessa (GET) kassan tietoja. Tällöin palvelin palauttaa seuraavanlaisen JSON-objektin:

{
    ”content”:
        ”<input type=\”hidden\” name=\”response_tag\” value=\”CheckoutBillingAddress(mode:’form’,ajax:’true’,action:’customer_information’)\” />”,
    ”notifications”:
        ”<div class=\”Notification Error\”><p>Ole hyvä ja täytä kaikki kentät. Tarvitsemme osoitetietojasi tilauksen toimittamista ja siihen liittyviä yhteydenottoja varten.</p></div>”
}

Objektin "content"-osassa on merkkaus, joka normaalisti palautuu suoraan vastauksena, mutta sillä muutoksella että täällä ei tule merkkauksen mukana ilmoituksia. Objektin toinen osa on ”notifications”, jonka sisällä tulee ilmoituksen merkkaus, joka on helppo poimia erilleen ja tulostaa haluamassaan paikassa.