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:

  • after: / before: Näillä attribuuteilla voit asettaa sisältöä tulostumaan ennen/jälkeen tagin oman sisällön. Jos tagi itse ei tuota sisältöä, myöskään näille attribuuteille asetettua sisältöä ei näytetä.

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

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

    Esimerkiksi jos tulostat tuotelistaa tuoteryhmästä, joka ei sisällä tuotteita, näytetään or-attribuutin arvo:

    {CategoryProducts(
  or: 'Ei tuotteita'
)}
  • escape: Asettaa tulostettavassa sisällössä pakomerkin ennen jokaista lainausmerkkiä, jolloin 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 tuplakaarisulkeisiin:
{Products(
  category: 2,
  helper: {{
      <h3>{ProductName}</h3>
      <div>{ProductDescription}</div>
      <div>{ProductPrices}</div>
      {ProductAddToCart}
  }}
)}

Oheisessa esimerkissä tulostetaan {Products}-tagilla kaikki tuotteet tuoteryhmästä, jonka ID on 2.

{Products}-tagin helper-attribuutissa määritellään jokaisen listaelementin sisältö ja merkkaus. Esimerkissä tulostetaan listan jokaisen tuotteen nimi, kuvaus, hinnat ja ostopainike.

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.