Bakgrund
I version 7 av Commerce så försvinner möjligheten att direkt ändra i sina mallar (och andra anpassningar) via SFTP, som funnits i tidigare versioner.
Det ersätts helt av versionshantering i Git, där resultatet skickas ut i produktion i form av ett paket med anpassningarna. Dessa paket kallas för en "shuttle" och flera "shuttles" kan kombineras ihop enligt en "flightplan". Resultatet av en sådan kombination blir en "flight" som är det som slutligen körs.
Det här dokumentet beskriver ett sätt att jobba med sina mallar som är grundläggande.
För omfattande utveckling och mera avancerade anpassningar finns möjligheter till en licensierad utvecklarmiljö där du kan testa hela plattformen inklusive anpassningar på din egen dator. Kontakta Kodmyran om du har ett sådant behov.
Förutsättningar:
Det här behöver du fixa själv:
- Ett Git repo, antingen i egen regi, eller via någon molntjänst. Exempel på vanliga Git repo/leverantörer är Gitlab, Github och BitBucket. Den här guiden täcker enbart Gitlab som exempel, väljer du någon annan kan du troligen få det att fungera bra även med dem men CI/CD script och vissa handgrepp kan skiljas mellan olika leverantörer och måste justeras.
- Installera ett Git verktyg på din dator
Det här får du från Kodmyran efter kontakt med supporten:
- API Nyckel - En textsträng med en massa slumpvis tecken som fungerar som ett lösenord för maskin-till-maskin kommunikation.
- Cloud URL - en webbadress där dina "shuttles" lagras
- Källkoden till din mall om du inte vill börja från noll.
Hur gör man?
Den här guiden utgår ifrån att du använder Gitlab i molnet som verktyg, om du använder något annat kan du behöva göra vissa anpassningar.
Gitlab har ett personligt/gratis paket/nivå som kan användas för många, och större paket för de med mera behov. Ingen av funktionerna som används här kräver något mer än gratis versionen. Däremot kan det finnas gränser kring antal anställda till exempel som kräver ett större paket.
Använder du en Gitlab du installerat på egen server fungerar det nästan likadant men du måste göra vissa egna inställningar i övrigt för att bland annat få i gång en "gitrunner".
- Det första är att sätta upp kontot hos Gitlab, gå till gitlab.com och starta ett konto.
- Väl där så får du skapa ett nytt projekt, namnge det som du önskar. Undvik åäö och mellanslag om du kan i namnet, det underlättar.
- Installera en Git klient på din dator. Det finns många, men vi brukar använda TortoiseGit på Windows. På Mac finns Git att ladda ner via bland annat Apples utvecklarverktyg (XCode).
- Inne i Gitlab så finns nu på projektets förstasida en ikon för "Clone", klicka på den och kopiera adressen, du kan välja båda varianterna, men den för https är enklare och du använder sedan samma anv. namn och lösenord som du använt i övrigt för Gitlab. Väljer du SSH varianten måste du skapa ett nyckelpar mm vilket är lite mer avancerat, men smidigare om du skall arbeta mycket med dina mallar.
- Skapa en katalog på din dator för att hantera din mall, undvik åäö, mellanslag och andra specialtecken i katalogen.
- Ställ dig i katalogen och använd kommandot "git clone" för att skapa en lokal kopia av det som ligger lagrat i Git. Med TortoiseGit kan du bara markera katalogen i Windows filhanterare och klicka med höger musknapp så får du en meny med alla Git alternativ. Använd länken du kopierade ovan för att tala om för Git vart källkoden finns.
- Packa upp källkoden du fått ifrån Kodmyran i samma katalog, du skall få ett antal filer och kataloger. En av dem är katalogen "src" som innehåller all källkod och filen .gitlab-ci.yml i toppen. Flytta inte runt filerna, då kommer inte CI/CD script mm att fungera. För ett paket som är en mall får man då normalt en struktur som ser ut som exemplet nedan.
src/templates/<mallens namn>- snippets - Här ligger mallens PHP filer
- scripts - Här finns alla Javascript som skall läggas med som hör till mallen, undvik att lägga till exempel bibliotek som jQuery – det är mycket bättre att ladda sådant från ett CDN
- mails - Här ligger grundfiler för hur olika e-post utskick skall se ut
- css - Dina stilmallar
- images - Olika typer av bilder som används av mallen, här skall man inte lägga produktbilder, bildspel och liknande utan använd för exempelvis små ikoner, flaggor för länder mm
- lang - Översättningar av mallen till olika språk lagras här i form av s.k. po/mo filer. Du behöver ett särskilt verktyg för att skapa översättningar, det vanligaste är PoEdit som finns till både Windows och Mac.
- template.xml - En kontrollfil som beskriver hur mallen är uppbyggd, vad som skall förladdas, Javascript referenser mm
- Nu är det dags att kompletera ditt projekt med API nyckel och Cloud URL som du fått från Kodmyran. Inne i Gitlab går du till ditt projekt, i vänsterspalten väljer du Settings -> CI/CD -> Variables
Här skall du skapa två nya variabler. Den första skall ha namnet LCM_API_KEY och värdet skall vara den API nyckel du fått från oss på Kodmyran. Den andra skall ha namnet LCM_CLOUD_URL och är en adress till dit resultatet skall lagras, även denna har du fått från oss på Kodmyran. Tänk på att båda dessa är för det specifika kontot och är något som skall förvaras säkert och inte delas hur som helst.
- Nu är det dags att checka in allt till Git. Ställ dig i rätt katalog och välj "git commit", välj alla filer/kataloger. Så snart det är klart gör du en "git push" så skrivs alla ändringar/nya filer över till Git.
Nu är allt klart för att du skall kunna göra dina egna ändringar
Justera det du behöver i mallen, följt av att göra "git commit" följt av "git push".
Om allt fungerar som det skall startar nu automatiskt ett jobb i Gitlab som tar alla filer och paketerar ihop dem, skickar över dem till Kodmyran Lifecycle Manager och sedan skickas den nya versionen ut till din butik. Det kan ta någon eller några minuter innan ändringen kommit fram, till skillnad mot i version 6 är inte ändringar omedelbara.
Du kan se och felsöka denna process inne i Gitlab under projektet, i vänstermenyn kan du klicka på Build -> Pipelines så ser du status. Du får normalt också ett e-post meddelande om något går snett.