MyCashflow-verkkokauppateemojen asetuksia ja tuettuja ominaisuuksia voidaan määrittää asetustiedostossa theme.xml. Tässä artikkelissa käydään läpi asetustiedoston sisältö ja käyttäminen teemassa.

Mikäli asetustiedosto puuttuu kaupan teemasta, teemaa ei voi ottaa käyttöön verkkokaupassa.

Asetustiedosto on XML-tiedosto, josta esimerkiksi tietyt Interface-tagit lukevat tarvitsemiaan tietoja. Myös joidenkin verkkokaupan ominaisuuksien käyttö teemassa pitää mahdollistaa asetustiedostossa (esim. lahjakorttien ja tuotesuodattimien) .

Sijoita asetustiedosto teeman juurikansioon (esimerkiksi themes/shop/TEEMA/theme.xml).

Asetustiedoston rakenne

Asetustiedosto sisältää 4 päätason elementtiä:

  • <Version/>: teeman versionumero
  • <Settings/>: teemaa koskevia yleisiä asetuksia
  • <Features/>: teemassa tuetut ominaisuudet
  • <ImageSizes/>: eri yhteyksissä käytettäviä kuvakokoja (esim. tuotesivujen ja -listojen kuvat)
  • <ThemeSettings/>: vapaavalintaiset, teemakohtaiset asetukset

Alla näet esimerkin asetustiedoston perusrakenteesta:

<?xml version="1.0"?>
<Theme>
  <Version>1</Version>
  <Settings>
    ...
  </Settings>
  <ImageSizes>
    ...
  </ImageSizes>
  <Features>
    ...
  </Features>
  <ThemeSettings>
    ...
  </ThemeSettings>
</Theme>

Seuraavissa kappaleissa käydään läpi tarkemmin elementtien sisältöä.

Versiointi

<Version/>-elementissä voit pitää tietoa teeman kehityksestä. Voit päivittää versionumeron aina tehtyäsi muutoksia ja luoda teemaan myös erillisen readme.md-tiedoston, jossa kerrot versioittain tekemistäsi muutoksista.

Version perusteella lisätään myös {MinifyJS}- ja {MinifyCSS}-tageille versioparametri v=x. Kun parameteri on läsnä, muutokset teeman CSS/JavaScript-tiedostoihin eivät tallennu välimuistiin, mikä helpottaa teemamuutosten tekemistä.

<?xml version="1.0"?>
<Theme>
  ...
  <Version>1</Version>
  ...
</Theme>

Metatiedot

Asetusten <Doctype standard="HTML5/XHTML"/>-kentässä määritetään teeman jokaisen sivun HTML-dokumenttityyppi. Kentän arvo voi olla HTML5 tai XHTML (oletus).

Dokumenttityyppimääritys sisällytetään teemaan käyttäen {Doctype}-tagia, joka tulostaa valmiin dokumenttityyppimäärityksen (esim. <!doctype html>).

<?xml version="1.0"?>
<Theme>
  ...
  <Settings>
    <Doctype standard="HTML5"/>
  </Settings>
  ...
</Theme>

Kuvat

Asetusten <NoImage file="i/noImage.jpg"/>-kentässä määritetään oletusarvoinen tuotekuva kaikille tuotteille, joilla ei ole omia tuotekuvia. Tuotekuvatagit, kuten {ProductImages}, tulostavat kentän file-attribuutissa määritetyn kuvan.

Kuvan sijainti pitää määrittää suhteessa verkkokaupan tiedostohakemiston /files-kansioon. Alla olevassa esimerkissä kuva noImage.jpg sijaitsee i-nimisessä alikansiossa files-kansion sisällä.

<?xml version="1.0"?>
<Theme>
  ...
  <Settings>
    <Images>
      <NoImage file="i/noImage.jpg" />
    </Images>
  </Settings>
  ...
</Theme>

Lisäksi <ImageSizes/>-elementissä voidaan määrittää eri yhteyksissä käytettäviä kuvakokoja:

  • <Mini/>: käytössä esimerkiksi ostoskorin pikkukuvissa
  • <List/>: käytössä tuotelistojen tuotteilla
  • <Normal/>: käytössä tuotesivun tuotekuvalla
  • <Big/>: käytössä tuotekuvan suurennoksilla
  • <OpenGraph/>: käytössä OpenGraph-metatietoihin tulostettavalla kuvalla (hyvä olla iso)
  • <BrandList/>: käytössä tuotemerkin logoa tulostettaessa navigaatioissa ja listoissa
  • <BrandNormal/>: käytössä tuotesivun {ProductBrand}-tagilla
  • <CampaignImage/>: käytössä kampanjoiden sekä tuoteryhmien ja -merkkien kampanjakuvilla
  • <CheckoutLogo/>: käytössä kassan toimitus- ja maksutapalogoilla
<?xml version="1.0"?>
<Theme>
  ...
  <ImageSizes>
    <Mini width="32" height="32"/>
    <List width="162" height="162"/>
    <Normal width="258" height="258"/>
    <Big width="900" height="600"/>

    <OpenGraph width="1500" height="1500"/>
    
    <BrandList width="32" height="32"/>
    <BrandNormal width="162" height="162"/>
    
    <CampaignImage width="383"/>
    <CheckoutLogo width="270" height="90"/>
  </ImageSizes>
  ...
</Theme>

Kassa

Teeman ominaisuuksien <Checkout/>-osiossa määritetään teemassa tuetut kassan tyypit.

Asetukset <SinglePage supported="true/false" /> ja <MultiPage supported="true/false"/> määrittävät teemassa käytettävissä olevat kassat. Jos asetustiedostossa on määritetty esim. <SinglePage supported="false"/>, teemassa ei ole mahdollista käyttää yksisivuista kassaa, vaikka se olisi version asetuksissa valittuna, vaan teemassa on aina käytössä vain monisivuinen kassa. Jos teema ei sisällä valitun kassan sivupohjia, kauppa käyttää automaattisesti järjestelmän sisäistä, vastaavaa kassaa.

Jos molemmat kassat ovat käytettävissä, version asetuksissa voidaan valita kassan tyyppi. Kun version asetuksissa ei vielä ole tehty mitään valintaa, käytössä oleva kassa määritetään default="default"-attribuutin avulla.

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <Checkout>
      <SinglePage supported="true" />
      <MultiPage supported="true" default="default" />
    </Checkout>
  </Features>
  ...
</Theme>

Verottomat hinnat

Voit lisätä teemaan tuen versiokohtaiselle Näytä hinnat ilman arvonlisäveroa -asetukselle, jolloin voit luoda verkkokauppaan B2B-kauppaversion ilman että sinun tarvitsee luoda versiota varten omaa teemaa.

Toteuta verottomien hintojen asetukselle teematuki lisäämällä teeman asetuksiin <Settings>-kohtaan <VatFree supported="true"/>-asetus. Varmista myös, että yhdelläkään teeman hintoja esittävistä tageista ei ole käytössä includetax-attribuuttia.

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <VatFree supported="true"/>
  </Features>
  ...
</Theme>

Verottomien hintojen asetus ei toimi tulosteteemoissa. Jos haluat näyttää niissä hinnat verottomina, sinun on lisättävä kaikille niissä käytetyille hintatageille includetax: false -attribuutti.

Lue myös:

Tuotelistat

Teeman asetusten <ProductList/>-osiossa määritetään tuotelistojen sivutusvalikossa valittavissa olevat sivukoot.

Asetus vaikuttaa vain tuotesuodattimia käyttävien tuotelistojen sivutustyökaluihin.

Sivutusvalikko tulostetaan tuotelistojen yhteyteen {PaginationLimit}-tagilla.

Esimerkiksi alla olevalla asetuksella asiakas voi valita tuotelistan yksittäisen sivun pituudeksi 25, 50 tai 100 tuotetta.

<?xml version="1.0"?>
<Theme>
  ...
  <Settings>
    <ProductList>
      <PageSizes>
        <PageSize>25</PageSize>
        <PageSize>50</PageSize>
        <PageSize>100</PageSize>
      </PageSizes>
    </ProductList>
  </Settings>
  ...
</Theme>

Tuotelistojen maksimipituus on 100 tuotetta.

Lahjakortit

<GiftCards supported="true/false"/>-asetuksen avulla verkkokaupassa mahdollistetaan lahjakorttien laajennettu tuki.

Kun <GiftCards/>-asetuksella on arvo true

  • {CartTotal}-tagi tulostaa ostoskorin välisumman mukaanlukien alennukset
  • {CartOpenTotal}-tagi tulostaa avoimen summan
  • kassalla ei tarvitse valita maksutapaa, jos lahjakortin käytön jälkeen tilauksen loppusumma on 0 €.

Arvolla false

  • {CartTotal}-tagi tulostaa avoimen summan (lahjakortin jälkeen maksettavaa)
  • {CartOpenTotal}-tagi ei tee mitään, koska tagi ei ole käytössä ilman uudistettuja lahjakortteja
  • kassalla pitää valita maksutapa, vaikka tilaukselle ei jäisi maksettavaa.

Lue lisää asetuksen vaikutuksista

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <GiftCards supported="true" />
  </Features>
  ...
</Theme>

Tuotepaketit

Teeman ominaisuuksien <ProductBundles supported="true/false"/>-asetus määrittää tuotepakettien toteutustavan.

Arvon ollessa false (tai sen puuttuessa) {ProductShortDesc}-tagi tulostaa tuotepaketit lyhyeen tuotekuvaukseen. Jos arvo on true, tuotepaketit eivät sisälly lyhyeen tuotekuvaukseen, vaan teemaan on lisättävä haluttuun kohtaan {ProductBundles}-tagi, joka tulostaa tuotepakettilistauksen.

Lue lisää tuotepakettien toteuttamisesta teemassa

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <ProductBundles supported="true" />
  </Features>
  ...
</Theme>

Vapaavalintaiset teema-asetukset

Teema-asetuksiin on mahdollista lisätä vapaavalintaisia asetuksia, jotka näkyvät teemaeditorin valikossa käyttäjän hallittavina WYSIWYG-työkaluina.

Lue myös:

MyCashflow'n oletusteema nojaa vahvasti vapaavalintaisiin, graafisen käyttöliittymän avulla hallittaviin asetuksiin. Voit ottaa teeman käyttöön ja muokata sitä tarpeen mukaan tai käyttää sitä mallina uuden teeman asetuksia määrittäessäsi.

Vapaavalintaiset asetukset määritetään asetustiedoston <ThemeSettings/>-osiossa, jonka rakenne on kuvattu alla:

<?xml version="1.0"?>
<Theme>
    ...
    <ThemeSettings>
        <SettingGroup label="custom_setting_group_1" description="custom_setting_1_group_description">
            ...
            <Setting type="boolean|select|color|integer" default="foo" name="foo" label="setting_1" description="setting_1_description"/>
        </SettingGroup>
    </ThemeSettings>
    ...
</Theme>

Vapaavalintaisia asetuksia käytetään teemassa {Setting}-tagin avulla. Tagi tulostaa eri asetuksiin tallennettuja arvoja asetusten name-attribuutin perusteella.

Asetukset on mahdollista ryhmitellä käyttäen <SettingGroup/>-elementtiä. Ryhmien avulla voit koota toisiinsa liittyviä asetuksia yhteen auttaaksesi teeman käyttäjää navigoimaan valikossa.

Asetuksille ja asetusryhmille voi määrittää monikieliset nimet ja kuvaukset, jotka toteutetaan yhdessä theme.xml-tiedoston ja teeman käännöstiedostojen kanssa.

Alla käydään läpi vapaavalintaisten asetusten määrittämiseen käytetyt elementit ja niiden mahdolliset attribuutit.

  • <SettingGroup/>
    • label (pakollinen): Asetusryhmän nimi, joka näkyy asetusvalikossa.
    • description: Asetusryhmän kuvaus, joka näkyy asetusvalikossa.
  • <Setting/>
    • type (pakollinen): Asetuksen tyyppi, joka määrittää asetusvalikossa näkyvän hallintaelementin ja ohjaa sen käyttöä teemassa. Mahdolliset arvot:
      • boolean
      • select

        Jos arvo on select, <Setting/>-elementin sisään on lisättävä <Option value="foo" label="Bar"/>-elementtejä, jotka määrittävät listalla valittavissa olevat vaihtoehdot (lue lisää valintalistan toteuttamisesta).

      • integer: numerotyyppisillä asetuksilla ovat käytettävissä myös seuraavat valinnaiset attribuutit:
        • min: minimiarvo
        • max: maksimiarvo
        • step: määrä, joka lisätään tai poistetaan yhdellä numerokentän hallintanuolen painalluksella.
        • unit: yksikkö (esim. px)
      • color
    • default (pakollinen): Oletusarvo, jonka mahdollinen sisältö riippuu type-attribuutista. Se määrittää, kuinka asetus toimii teemassa silloin, kun teeman käyttäjä ei ole syöttänyt sille mitään arvoa.
    • name (pakollinen): Asetuksen nimi, jota käytetään {Setting}-tagissa tunnistamaan asetus käytettäessä sitä.
    • label (pakollinen): Asetuksen nimi, joka näkyy asetusvalikossa.
    • description: Asetuksen kuvaus, joka näkyy asetusvalikossa.

Esimerkki asetustiedostosta

Jos olet kehittämässä omaa teemaasi, voit kopioida alta löytyvän asetustiedoston suoraan teemasi juurihakemistoon nimellä theme.xml ja tehdä siihen tarvitsemiasi muutoksia.

<?xml version="1.0"?>
<Theme>
  <ImageSizes>
    <Mini width="80" height="80" />
    <List width="180" height="180" />
    <Normal width="600" height="600" />
    <Big width="1200" height="1200" />
  </ImageSizes>
  <Features>
    <Checkout>
      <SinglePage supported="true" default="default" />
      <MultiPage supported="false" />
    </Checkout>
    <GiftCards supported="true" />
    <ProductBundles supported="true" />
    <ProductListFilters supported="true" />
  </Features>
  <Settings>
    <Doctype standard="HTML5" />
    <ProductList>
      <PageSizes>
        <PageSize>25</PageSize>
        <PageSize>50</PageSize>
        <PageSize>100</PageSize>
      </PageSizes>
    </ProductList>
  </Settings>
</Theme>