• Template udvikling
  • For Udviklere

    • Template udvikling

    I denne artikel:

    

    Inden du påbegynder udviklingen af et template, er det vigtigt, at du har en forståelse for de grundlæggende emner som omhandler templates og systemets opbygning:

     

    System filer

    1. meta.json

    Den vigtigste fil for templatet er meta.json. Uden meta.json indlæses templatet ikke. Derfor er meta.json også den eneste fil, der altid vil ligge lokalt i templaten og ikke på serveren. Filen meta.json indeholder de vigtigste informationer om din template, så som navn, beskrivelse og udvikler information. Men meta.json fortæller også systemet om templaten er en parent eller en child template. Det sker gennem PARENT parameteren. Forneden ses PARENT parameteren for template002, der er et child template til template001 (Rooty):

    
"PARENT": "template001"

     

    Template001 er selv et parent template og har derfor ingen PARENT defineret.

    2. source/settings/settings.json

    Filen settings.json er den fil der bestemmer, hvilke input muligheder der skal være i Ret design. Det vil sige, at du med denne fil kan bestemme hvilke muligheder brugeren har i Design manageren. Filen er en JSON fil og skal derfor overhold det format. Vores bedste råd er, at tage udgangspunkt i de eksisterende filer og arbejde derfra.

    Filen har følgende opbygning:

    • SETTINGS navnet er den parameter setting som den er tilgængelig under i systemet:
      • I Smarty under $template.settings.SETTINGS_NAVN.
      • I SCSS (hvis TO_SCSS er sat til TRUE) med _ skrevet om til -
    • Der findes 4 typer SETTINGS:
      • DROPDOWN: Dropdown med muligheder i OPTIONS
      • COLOR_PICKER: En farvevælger
      • TEXT: Et almindeligt text input felt
      • IMAGE_PICKER: En billedvælger ( fil vælger )


    Eksempel på design indstilling i settings.json: 

    
"FONT_COLOR_HEADLINE":{
    "TYPE" : "COLOR_PICKER",
    "TITLE" : {
        "DK" : "Overskrift tekst farve",
        "UK" : "Headline text color",
        "SE" : "Textfärg, överskrift",
        "NO" : "Skriftfarge, overskrift"
    },
    "TO_SCSS" : "TRUE"
}

    Tilgang til setting via SCSS i source/scss/template.theme.scss:

    
.header h1 {
    color: $font-color-headline;
    font: 2em/1 sans-serif;
}


    Tilgang til setting via Smarty i tpl filerne:

    {$page.headline}

    3. source/settings/settings_values.json

    Filen settings_values.json hører sammen med settings.json og er værdierne fra Ret design. settings_values.json genereres af systemet og bruges til at gemme indstillingerne til Ret design.

    4. source/scss/template.theme.scss

    Filen template.theme.scss er en af de mange Sass filer, som Hostedshops templates består af. Det er dog den eneste som ikke compiles lokalt og uploades. Filen template.theme.scss bliver nemlig compilet på serveren af systemet, hver gang brugeren trykker gem i Ret design. Hvis du ikke kender Sass er det en precompiler til CSS som du kan læse meget mere om på deres website sass-lang.com.

    Filen template.theme.scss er sammen med settings_values.json de filer, som systemet tager udgangspunkt i, når den skal compile assets/css/theme.css. Til at compilere filen bruger Hostedshop PHP biblioteket scssphp, en simpel PHP version af Sass. Filen består primært af Sass partials, som ligger i source/scss/theme/, men indeholder også nogle få globale mixins. Filens indeholder primært farve værdier, for at gøre kompileringen så simpel som muligt.

    Note til udviklere, der allerede kender Sass: det er ikke muligt at bruge Compass i template.theme.scss, da scssphp IKKE kan compile Compass. Skal du bruge Compass, foreslår vi at du gør det i Sass filer som du compilet lokalt. I vores tilfælde er det source/scss/template.structure.scss.

    Når du vil udvikle en template, kan du bruge source/scss/template.theme.scss til at tilgå farverne fra Ret design. Som nævnt i forbindelse med settings.json vil de settings der er opsat her, være tilgængelig i template.theme.scss, hvis TO_SCSS er sat til TRUE.

    5. assets/css/theme.css

    Filen theme.css er det compilede resultatet af source/scss/template.theme.scss. Filen compileres hver gang der trykkes gem i Ret design og filen bliver slettet og overskrevet med en ny fil.

    Filen theme.css er en almindelig CSS fil, der kan ses i Rediger filer. Hvis du vælger, at redigere filen, skal du være opmærksom på at alle ændringer vil gå tabt, så snart der trykkes gem i Ret design.

    6. source/settings/language/*.json (dk.json etc.)
    Her placeres filer indeholdende egne sprogvariable. Det er nødvendigt at navngive filerne efter de sproglag der findes på løsningen. F.eks. dk.json.
    Indholdet i filen ser ud som følger:  

    
{
    "MY_OWN_TRANSLATION": {
        "value": "Se tilbud her!"
    },
    "MY_OTHER_TRANSLATION": {
        "value": "Se flere tilbud her!"
    }
}

     

    Rediger template

    Ønsker du at ændre i et eksisterende template, foreslår vi som udgangspunkt, at du laver en ny fil. I Hostedshop har vi 3 typer filer i vores templates; CSS, Javascript og Smarty template filerne. Alle filerne kan tilgåes på to måder, enten via Design manageren eller via FTP. Se evt. hvordan du opretter FTP adgang under FTP adgang til udviklere. Som en ny ting, kan du via den nye Design manager, også fjerne (og naturligvis tilføje) referencer til CSS eller Javascript filer fra en template, så du helt selv bestemmer hvilke assets du vil loade eller ikke vil loade. Vil du f.eks. gerne lave en ny variant visning, eller overskrive en variant visning, har du nu mulighed for det, ved at fjerne referencerne til filerne.

    Du har altid mulighed for, at overskrive en fil i Design manageren. Systemet er opbygget sådan, at når den leder efter assets, så kigger den altid lokalt først, i template mappen, inden den kigger efter filen på system serveren. Det vil sige filer tilføjet med addScript eller addLink først kigges efter lokalt i template mappen. Herefter i system mappen. Filer der ligger lokalt er anvist med (c) i Rediger filer.

     

    Opret CSS fil

    Skal du redigere eller lave nogle ændringer til CSS’en på en template, foreslår vi, at du opretter en ny CSS fil i mappen assets/css og tilføjer dine CSS rettelser her. Lige nu er den nemmeste måde at gøre det på via FTP.

    Når du har tilføjet CSS filen i mappen, skal du indsætte en reference til den. Det gøres via Smarty funktion vi har stillet til rådighed, som hedder addLink. addLink gør det muligt at tilføje CSS filer til <head> fra alle tpl filer, men vi foreslår dog at du som udgangspunkt gør det i index.tpl, da det på den måde er meget nemmere at holde styr på alle dine referencer. Se forneden hvordan det kan gøres:

    

{*** Eksempel på template CSS fil ***}
{addLink href='assets/css/custom.css'}

{*** Eksempel på global CSS fil ***}
{addLink href='//eksempel.com/style.css' relative='true'}

    Opret tpl fil

    En Smarty template (*.tpl) fil, fungerer på mange måder som CSS og Javascript filerne, hvor du kan redigere filerne gennem Rediger filer eller via FTP. Modsat CSS og Javascript filerne foreslår vi dog, at i stedet for altid at oprette nye filer, så bør du kun oprette filer, hvis det drejer sig om en ny funktion. Det kan være en ny partial, som en sekudær header, en sidebar eller noget helt tredje.

    For at få adgang til at redigere en Smarty template fil gennem FTP, kan det være nødvendigt at gemme den i Rediger filer, så filen har en (c) efter sig, der viser at filen er en lokal template fil.

    Hvis du gerne vil oprette en Smarty template fil, skal du lige nu gøre det via FTP. Hvor du opretter filen afhænger af, hvilken kontekst du gerne vil bruge den. Hvis du vil lave en ny partial til et modul, foreslår vi at du opretter den i mappen til det modul. Vil du f.eks. skal oprette en ny partial til Produkter, så er vores forslag du ligger den i modules/products/partials. Vil du oprette en generel partial til templaten. F.eks. en udvidelse til headeren. Foreslår vi du ligger den i partials mappen i templatens rod.

    Når du skal inkludere en template foregår det med Smarty’s include funktion, hvor du også har mulighed for at medsende ekstra parametre. Parameterne vil være tilgængelig i mappen som variabel: $parameter. Se eksemplerne forneden hvordan det kan gøres:

    
{*** Eksempel på include af fil i sammen mappe ***}
{include file='eksempel.tpl'}

{*** Eksempel på include af fil i anden mappe ***}
{include file='mappe/eksempel.tpl'}

{*** Eksempel på include af fil og medsendelse af parametre ***}
{include file='mappe/eksempel.tpl' parameter1='1' parameter2='2'}

    Byg/compile template filer lokalt

    Med den nye Design manager, har vi valgt at ligge alle filer tilgængelig for dig som udvikler. Det har vi gjort for, at gøre det mulig for dig at bygge lige præcis det template du gerne vil. Ud over filerne der udgør templaten, har vi også valgt at ligge alle source (kilde-) filerne til Javascript og Sass ud. Så det er muligt for dig, at ændre dele af filerne i stedet for at skulle fjerne eller overskrive funktionalitet, med andre filer. Når vi compiler og bygger CSS og Javascript filer fra source filerne bruger vi Sass til at lave CSS og Grunt til at minify og concatinate mange Javascript filer sammen til en minificeret fil.

    For at gøre det muligt for dig, at gøre det sammen, har vi til alle templates vedlagt 2 projekt filer. I vores tilfælde er det:

    • package.js
    • Gruntfile.js -

    Med disse projekt filer og de rigtige udviklingsværktøjer kan du bygge alle template filer lokalt fra source filerne og uploade dem til dit template via FTP. Nedenfor kan du læse mere om hvad filerne skal bruges til.
    Bemærk:
    Alle filer i modules/*/assets/js bliver compiled ind i app.js.
    Alle filer i modules/*/includes bliver brugt lokalt af modulet, f.eks. bliver checkout.js inkluderet af checkout-order.tpl, fordi vi på den måde lettere kan opdatere denne fil separat fra de andre filer.

    Package.js

    Er en projekt fil til Node.js. Node.js, hvis du ikke kender det, er Javascript på serversiden, lige som du sikkert kender PHP er det nu muligt at køre Javascript på serveren. For at kunne compile og bygge udviklings filerne er det nødvendigt at have Grunt og Grunt er bygget på Node.js, så det skal være installeret for, at du kan bygge lokalt. Node.js kan hentes og installeres fra deres website nodejs.org. Efter du har installeret Node.js, kan du i mappen hvor du har udviklings- og source filerne liggende i terminalen eller consolen skrive nedenstående og alle Node.js dependencies til projektet vil blive installeret:

    
$ npm install

    Gruntfile.js

    Gruntfilen er selve projekt filen der står for at gøre alt det hårde arbejde. Filen er en task / opgave fil til Grunt, der er et build tool til Node.js. Grunt skal installeres ved siden af alle de andre Node.js dependencies, fordi det er et program som skal ligge globalt og som skal køres fra terminalen eller consolen. Grunt installeres med npm efter du har installeret Node.js, ved at skrive nedenstående: 

    
$ npm install -g grunt-cli

    Efter du har installeret Grunt, kan du nu bruge Gruntfilen. Det gør du ved i terminalen eller consolen at navigere hen til mappen med udviklings- og source filerne. Med vores Gruntfil har vi lavet to tasks som du kan kalde: 

    
$ grunt watch

    Grunt watch overvåger alle source filerne (både Javascript og CSS) og kigger efter ændringer, når der sker en ændring bygger den filerne sammen eller compilere dem. Filerne bliver bygget til assets/js og assets/css. Filerne vil ikke være minificerede og vil indholde alle kommentare. Watch tasken er ideel at bruge mens du udvikler og stadigvæk skal debugge og fejlfinde, da filerne ikke er minificeret. Tasken bliver ved med at køre indtil du lukker terminalen eller consolen eller indtil du trykker CTRL+C for at afbrude den.

    
$ grunt build

    Grunt build køre de samme underopgaver som Grunt watch, men køre dem kun èn gang og alle filerne bliver minificeret og alle overflødige kommentare bliver fjernet. For Javascript filerne gælder det også at alle console.log kald bliver fjernet, så de ikke skaber problemer for browsere som ikke understøtter console.log. Tasken er til at bygge alle filerne til færdige produktions filer. Så når du er helt færdig med dit projekt, har testet det hele, skal du køre Grunt build og alle dine færdig filer vil ende i assets/ mappen som minificerede og optimerede filer.

    Er du interesseret i, at vide mere om Grunt, kan du læse en kom godt igang guide på deres website.