Tässä artikkelissa käydään läpi MyCashflow'n Interface-tagien syntaksi ja erityyppisten attribuuttien käyttäminen.

Interface-tagien tulostama sisältö vaihtelee paljon: osa tageista tulostaa sivun <head>-elementtiin suunnattua sisältöä (esim. {MinifyCSS} ja {MinifyJS}), kun taas osaa on järkevintä käyttää <body>-osion sisällä.

Kaikkien tagien kirjoitusasu alkaa ja päättyy kaarisulkeisiin:

{PageTitle}

Monilla tageilla on attribuutteja, joiden avulla tarkennetaan tai muokataan tagin tulostamaa sisältöä. Attribuutit määritellään pilkuilla erotettuna attribuutti: 'arvo' -listana, joka sijoitetaan sulkuihin tagin sisällä:

{ProductPrice(decimals: 2, includetax: true)}

Selkeyden vuoksi yksittäiset attribuutit on monesti hyödyllistä jakaa useammalle riville:

{ProductPrice(
    decimals: 2,
    includetax: true
)}

Voit halutessasi sulkea attribuuttien arvot lainausmerkkeihin (" tai '), mutta tämä ei ole pakollista. Merkkijonotyyppisten attribuuttien kohdalla lainausmerkkien käyttäminen voi selkeyttää koodia.

{Products(
    before: '<h2>Tuotteet</h2>'
)}

Attribuuttien tyypit

Jokaisella attribuutilla on sallittu tietotyyppi, joka määrittää mitä arvoja attribuutille voidaan antaa. Käytössä olevia tietotyyppejä ovat seuraavat:

  • Totuusarvo (boolean): true tai false.
  • Kokonaisluvut (int): kokonaisluvut (esim. 24).
  • Merkkijono (string): teksti ja/tai HTML- ja Interface-merkkaus.

    Joillakin attribuuteilla on rajallinen määrä sallittuja merkkijonoja. Sallitut vaihtoehdot on aina listattu tagisivujen attribuuttilistoilla.

    Kaikki merkkijonotyyppiset attribuutit eivät hyväksy HTML/Interface-merkkausta. Tagien dokumentaatiosivuilta löydät tarkempaa tietoa attribuuttien sallituista arvoista.

Jos annat attribuutille arvoksi vääräntyyppistä tietoa, tagi tulostaa todennäköisesti virheellistä sisältöä tai ei toimi lainkaan.

Jokaisen tagin attribuuttien sallitut tietotyypit on ilmoitettu aina tagisivun syntaksikaaviossa ja attribuuttilistalla.

Globaalit attribuutit

Seuraavat globaalit attribuutit ovat käytössä lähes kaikilla Interface-tageilla:

  • before: / after: Näillä kahdella attribuutilla voit määrittää sisällön, joka tulostuu ennen tagin tuottamaa sisältöä tai sen jälkeen. Jos tagi ei tuota mitään sisältöä, myöskään before- ja after-attribuuttien sisältö ei tulostu.

    Näin voit esimerkiksi lisätä tuotelistan ympärille container-elementin:

    {CategoryProducts(
  before: '<ul>',
  after: '</ul>'
)}
  • or: Määrittää vaihtoehtoisen sisällön, joka näkyy, jos tagi ei itse tuota mitään sisältöä.

    Esimerkiksi jos tulostat tuotelistaa tuoteryhmästä, joka ei sisällä tuotteita, tagi tulostaa or-attribuutin arvon:

    {CategoryProducts(
  or: 'Ei tuotteita'
)}
  • escape: Asettaa tagin tulostamassa sisällössä pakomerkin ennen jokaista lainausmerkkiä, niin että sisältöä on helpompaa käsitellä JavaScriptin avulla.

Tagien käyttäminen attribuuttien arvoina

Joidenkin attribuuttien arvoina on mahdollista käyttää muiden Interface-tagien tuottamaa sisältöä.

Erilaisilla listoilla on esimerkiksi käytettävissään helper-attribuutti, jonka avulla muotoillaan yksittäisen listaelementin sisältö ja tulostusmuoto.

Attribuutin arvoina käytettäessä Interface-tagit kirjoitetaan samalla syntaksilla kuin yleensäkin. Ainoa ero on, että helper-attribuutin arvo suljetaan tupla-aaltosulkeisiin:
{ProductSet(
  category: 2,
  helper: {{
      <h3>{ProductName}</h3>
      <div>{ProductDescription}</div>
      <div>{ProductPrices}</div>
      {ProductAddToCart}
  }}
)}

Oheisessa esimerkissä {ProductSet}-tagi tulostaa kaikki tuotteet category-attribuutin määrittämästä tuoteryhmästä, jonka ID on 2.

Tagin helper-attribuutti puolestaan määrittää listaelementtien sisällön ja merkkauksen. Tässä esimerkissä tagi tulostaa listan jokaisen tuotteen nimen, kuvauksen, hintatiedot ja ostopainikkeen.

Tiedostoviittaukset attribuuttien arvoina

Joidenkin attribuuttien arvoksi voidaan antaa viittauksia teemakansiossa sijaitseviin HTML-tiedostoihin. Tällainen on esimerkiksi {Helper}-tagin file-attribuutti, jolla luetaan sisään ja tulostetaan sivulle valitun tiedoston sisältö.

Tiedostoviittaukset määritellään aina suhteessa teeman juurikansioon. Viitattavan tiedoston pääte jätetään myös aina pois viittauksesta:

{Helper(
    product: 3,
    file: 'helpers/product-display'
)}

Esimerkissä tulostetaan {Helper}-tagin avulla yhden tuotteen tiedot. Haluttu merkkaus on määritelty teeman helpers/product-display.html-tiedostossa, joka luetaan sisään file-attribuutin arvoksi.