Skillnad mellan versioner av "Utveckling"
Magpet (diskussion | bidrag) m |
Magpet (diskussion | bidrag) m |
||
| Rad 92: | Rad 92: | ||
| − | av: Magnus Pettersson e-post: magnus@entropy.nu | + | av: Magnus Pettersson |
| + | e-post: magnus@entropy.nu | ||
Versionen från 20 december 2021 kl. 10.00
Utvecklingen av Koha går snabbt framåt. Inom Koha:s community talar man om utveckling i form av buggar, men termen gäller för såväl buggar som ny funktionalitet. På den här sidan beskrivs hur ny utveckling blir en del av Koha:s kodbas inklusive kvalitetsgranskningsprocessen, lokala anpassningar och samarbetsområden.
(Här finns en implementeringschecklista att följa stegvis för de som vill gå över till Koha från ett annat bibliotekssystem)
Kohas utvecklingsprocess i korta drag
Koha är till sin natur ett distribuerat och demokratiskt projekt och de som bidragit har använt sin upphovsrätt för att garantera dig att du får anpassa din egen installation fritt. Men lokala förändringar blir snabbt ohanterliga vid uppgradering och därför bör du sträva efter att göra alla ändringar "uppströms", dvs få dem inkluderade som en del av en officiell Koha-version. På det viset minskar du problem för dig själv, ger tillbaka till gemenskapen och tvingar andra att förhålla sig till din kod när systemet utvecklas vidare. Den här texten är ett försök att ge en översikt till hur utvecklingsprocessen går till.
- Identifiera ny utveckling du vill göra eller en bugg du vill rätta. Notera att Koha communityt använder termen bug för såväl rena fel (buggar) som ny funktionalitet, ett språkbruk som ibland förvirrar nytillkomna användare.
- Försök ta reda på om någon annan redan rapporterat denna eller liknande information på Kohas ärendehanteringssystem Bugzilla[1].
- Om det verkligen är en ny funktion/bug - skapa en ny tråd på Bugzilla (file a bug [2] / välj "Koha") och beskriv så koncist som möjligt vad du vill åstadkomma. Fyll i component (vilken del av Koha utvecklingen rör), version (särskilt om det är en bug - "master" avser aktuell utvecklingsversion och funkar för önskad utveckling), summary (supertydligt och de viktigaste orden först - den här raden tenderar att dyka upp i t.ex. release notes) samt description. Severity kan du försöka sätta om du känner att du behärskar de olika stegen medan "hardware" och "OS" kanske används mera sällan men är viktiga i vissa mer avgränsade fall.
- I vissa fall slutar bibliotekets åtagande här. Det kan handla om rena önskemål om ny funktionalitet eller bug-rapportering, men där det inte finns möjlighet att driva utvecklingen vidare lokalt eller via leverantörer. Emellanåt tas buggen upp av någon annan part i Kohas community, som sköter själva kodningen. Det gäller framförallt buggar som anses kritiska. Men vill du vara säker på att det arbetas med utvecklingsinsatsen finns två alternativ: att koda själv eller att beställa utveckling från någon av de leverantörer som arbetar inom communityt. Texten som följer beskriver utvecklingsprocessen utifrån det första alternativet, men mycket av detsamma gäller även för beställd utveckling - bara det att leverantören står för koden samt ofta även hantering av tråden i Bugzilla. Mer information om beställa utveckling från leverantörer finns på wikisidan Tips vid extern leverantör.
- Gör den utveckling som du vill ha gjord - men sätt i så fall dig själv som "Asignee" på bugzillatråden (det finns antagligen en som är default, men det betyder bara att de bevakar vad som kommer in - inte att de skall koda allt som föreslås). Använd t.ex. en Kohadevbox[3] för att enkelt få en virtuell utvecklarmaskin. Läs in dig på Koha developer handbook[4] på den internationella wikin. Posta dina ändringar till Bugzilla (med git bz som du vet mer om efter att ha läst developer handbook). Var noga med att följa reglerna för hur man kodar i Kohaprojektet och att skriva en ordentlig testplan. Om du lämnar bort utvecklingen till en firma kan du fylla i fältet "Change sponsored" så att du/ditt bibliotek syns i release notes för den version där det du finansierar faktiskt kommer med.
- Ändra statusen på bugzillatråden till "Needs signoff" och vänta. När du skickat in din kod måste någon som inte är kopplad till dig granska det du gjort och godkänna det - en så kallad signoff. Den personen ändrar status-fältet på din Bugzilla-tråd och sätter det förhoppningsvis till "signed off". Det är helt ok att nämna att du har en färdig patch för testning men kom ihåg att du inte kan kräva något av någon, det är frivilliga som testar det du gjort (men troligen finns det svenska kollegor på Slack som är nyfikna åtminstone). Lättast att få sign-offs på det du skapar blir det om du också bidragit innan till att testa andras kod. Det kan hända att din kod inte klarar sign-off utan måste få ytterligare handpåläggning. I början är det rentav troligt.
- Nästa steg är QA (quality assurance). Det är ett team med frivilliga som har till uppgift att kontrollera att koden inte bara verkar göra det den skall utan bieffekter utan att den också följer den kodstandard som gäller i Koha. Här får du oftast "failed QA" eller "passed QA". Om du inte klarar QA har du ändå kommit långt - justera koden efter teamets instruktioner och ändra statusen på bugzillatråden igen. QA-ansvarig är i skrivande stund Katrin Fischer (cait på IRC) som är mycket hjälpsam.
- Efter att du passerat QA hamnar koden hos release manager för kommande Koha-version. Det är denna person som har sista ordet om ifall din kod kommer med eller inte. I regel får din bugzillatråd statusen "pushed to master" vilket betyder att den nu inkluderas i senaste utvecklarversionen av Kohas kodbas - det som skall bli nästa version. Notera att ny funktionalitet endast släpps vid halvårsversionerna av Koha medan rättningar av buggar och andra mindre justeringar kommer med i månadsversionerna. Det kan också hända att din patch plockas upp av de som ansvarar för äldre versioner av Koha.
- Vänta på att din patch kommer med i nästa släpp av Koha och nämns i release notes.
För den som innan har jobbat med mindre egna projekt upplevs den här processen troligen som långsam. För den som kodar ensam är jobbet klart när koden är skriven och fungerar, men i ett projekt av Kohas storlek är det då processen börjar. Att identifiera och kravställa utvecklingen, få koden skriven, vänta på sign-off och QA innan man kan vänta på nästa halvårsversion gör att man i regel får vänta något år från det man startar ett projekt tills man ser resultatet i en ny version av Koha.
Infoga egen HTML, Javascript (jQuery) och CSS
Kohas beteende kan ändras mycket med hjälp av systemparametrarna. Men när det inte räcker finns det goda möjligheter att ändra ytterligare med hjälp av javascript och CSS. Man kan naturligtvis ändra direkt i Kohas programkod, men det skapar problem med uppdateringar. Istället bör du använda de systemparametrar som redan finns förberedda för att infoga HTML, javascriptkod eller CSS i valda delar av systemet. På det sättet stannar ändringarna kvar när du uppdaterar Koha nästa gång. Det finns gott om nischade systemparametrar för att manipulera enskilda delar av gränssnittet, men de som är mest generella torde vara:
- OPACuserJS - Här klistrar man in kod som är som skall finnas tillgänglig på alla sidor i opac. Exempel som andra i nätverket funnit användbara finns på en egen wikisida Kohas OPACUserJS systeminställning
- OpacAdditionalStylesheet - Här länkar du till en extra stilmall utöver Kohas befintliga.
- opaclayoutstylesheet - Sökväg till en ny stilmall för opacen.
- OPACuserCSS - Extra CSS som skall finnas på alla sidor i opac i tillägg till de existerande stilmallarna (om du t.ex. infogat nya HTML-element.
- OpacMainUserBlock - HTML-kod som skall infogas i mittenytan på opacens förstasida.
- OpacNav - HTML-kod som skall visas i vänsterspalten på opacens förstasida.
- OpacNavRight - HTML-kod som skall visas i högerspalten på opacens förstasida.
- OpacNavBottom - HTML-kod för vänsterspalt på opacens förstasida och låntagarens konto (visas under OpacNav)
- opacheader - HTML-kod för sidhuvudet på alla sidor i opac.
- opaccredits - HTML-kod för sidfoten på alla sidor i opac.
(Notera att det finns ytterligare systemparametrar som låter dig infoga html på mer nischade ställen som t.ex. rutan för facetterna, ersätter sökrutan med egen kod, lägger till saker på vidaresökningsknappen osv)
- intranetstylesheet - Länk till en CSS-mall som ersätter den befintliga för Kohas personalgränssnitt.
- intranetUserCSS - CSS-kod som du vill lägga till utöver den befintliga i Koha.
- intranetcolorstylesheet - Länk till CSS-mall som låter dig skriva över delar av den befintliga CSS-mallen för personalgränssnittet.
- intranetmainUserblock - HTML som du vill visa i en egen kolumn på personalklientens förstasida (t.ex. djuplänkar till ofta använda funktioner eller widgets som visualiserar data från systemet). Lämpar sig bäst för mer statiskt innehåll - för t.ex. intern information lämpar sig antagligen det grafiska verktyget för att skriva nyheter bättre.
- intranetNav - Länkar som du vill lägga till under fliken "mer" i personalgränssnittets globala navigation.
- IntranetUserJS - Javascript (jQuery)-kod som du vill ladda på alla sidor i personalklienten. (vad som faktiskt körs kan dock naturligtvis styras med villkor som body-tagens id osv)
Du hittar fler under t.ex. personalklient/utseende och opac/utseende i systeminställningarna.
OBS! När du infogar javascript (troligen vill du använda använda jQuery som redan finns laddat, men vanlig rå javascript funkar naturligtvis också) så skall du låta sidan ladda färdigt genom att skriva din kod inuti följande kodsnutt.
$(document).ready(function(){ <skriv din kod här> });
Ändra XSLT-stilmallarna
XSLT används för att transformera XML till andra format. I Koha används XSLT för att göra om MarcXML till HTML. Genom att ändra XSLT-stilmallarna kan en bestämma själv vilken information som hämtas och visas från posten på detaljsidan, i listor och i sökresultat. För att ändra i XSLT-stilmallarna är det lämpligt att en kopierar originalfilerna och gör ändringar i dessa istället för att ändra direkt i originalfilerna. Det finns olika XSLT-stilmallar för varje språk. Länkarna till de ändrade filerna läggs in i systeminställningarna enligt följande:
Personalklient
- XSLTDetailsDisplay - används för en bibliografisk posts detaljsida.
- XSLTListsDisplay - används för listor.
- XSLTResultsDisplay - används för sökresultat.
OPAC
- OPACXSLTDetailsDisplay - används för en titels detaljsida.
- OPACXSLTListsDisplay - används för listor.
- OPACXSLTResultsDisplay - används för sökresultat.
Exempel på anpassningar av XSLT-stilmallarna som andra har funnit användbara
Att använda teman för att styla Koha
av: Magnus Pettersson e-post: magnus@entropy.nu
Man kan väldigt enkelt använda sig av admingränssnittet för att modifiera Koha. Det kan handla om att redigera olika delar på sidan med CSS eller lägga till funktionalitet med hjälp av Javascript. Det är däremot kanska långsamt att arbeta med, och eftersom man måste använda sig av webbgränssnittet så blir det snabbt krångligt och segt.
Men det finns ett alternativ i Koha, och det är att använda sig av teman. Teman i Koha fungerar så att man skapar en kopia på Koha's grundtema 'bootstrap 'och då har man tillgång till en egen version alla templates, bilder, Javascript filer. Eftersom man skapar en kopia så kan man göra vad man vill, man har alltid kvar grundtemat som backup.
Det finns många anledningar till att göra detta men de viktigaste är:
- Full kontroll
- Det går att dela teman med andra bibliotek.
- Det går att använda sig av externa editorer så som Vim, Atom, Notepad++ och operativsystemet Emacs. Vilket ökar utvecklingshastigheten.
- Det är säkrare, eftersom man skapat ett eget tema kan man byta till ett default tema om (när) något går sönder.
- Lägga till egna Javascript bibliotek och editera Koha's befintliga filer.
Hur skapar man och använder ett eget tema?
Koha lagrar all data i katalogen /usr/share/koha enklast är att göra en kopia på bootstrap som jag visar nedan.
Kopiera/ skapa teman
# för opac finns alla teman i katalogn /usr/share/koha/opac/htdocs/opac-tmpl # för intranät finns alla teman i katalogen /usr/share/koha/intranet/htdocs/intranet-tmpl # skapa ett nytt OPAC tema. cd /usr/share/koha/opac/htdocs/opac-tmpl cp -rp bootstrap test-tema # Dela med sig zip -r test-tema.zip test-tema/
Aktivera tema
För att aktivera temat får man gå till admingränssnittet och aktivera det, man kan söka på opacthemes för att hamna rätt, eller stega sig fram som nedan. Glöm inte att ladda om sidan innan, annars kommer det nya temat inte visa sig.
Koha administration -> Global System preferences -> OPAC -> Apperance -> opacthemes
tema-katalogens struktur
test-tema
├── css # All css som används.
│ ├── fonts
│ └── src
├── en # för enkelska sidor
│ ├── includes # delar av sidor, enstaka funktioner
│ ├── modules # hela sidor som är uppbyggda av bland annat inc filer
│ │ ├── clubs
│ │ ├── errors
│ │ ├── sci
│ │ ├── sco
│ │ ├── svc
│ │ └── text
│ └── xslt
├── images # loggor
│ └── datatables
├── itemtypeimg # bilder på exempelvis böcker, pilar etc.
│ ├── bridge
│ ├── carredart
│ ├── colors
│ ├── crystal-clear
│ ├── liblime-kids
│ ├── npl
│ ├── Seshat
│ └── vokal
├── js # Javascript skrivna för Koha
└── lib # externa javascript bibliotek så som jQuery.
├── bootstrap
│ └── js
├── famfamfam
│ ├── mini
│ └── silk
├── font-awesome
│ ├── css
│ ├── fonts
│ ├── less
│ └── scss
├── greybox
│ └── GreyBox_v5_5
│ ├── adobe_images
│ ├── compression_lib
│ ├── greybox_source
│ │ ├── base
│ │ ├── gallery
│ │ ├── set
│ │ └── window
│ └── static_files
└── jquery
├── images
└── plugins
Custom CSS
I Koha kan man definera extra css filer. Det gör man under rubriken OpacAdditionalStylesheet Tänk på att de här är "global". Den letar efter filen i css katalogen som finns i varje tema. Man kan även byta huvud css under rubriken opaclayoutstylesheet Även den här är global, så byter man huvud css så byter man det för alla teman. Det kommer att se konstigt ut om man byter huvudcss och filern inte finns i temats css katalog.
Istället för att använda sig av de här kan kan man skapa egna css och länka dem direkt från Koha's templates. ex. från opac-main.tt ,eller bara från de sidorna som man vill editera.
Exempel
I den här bilden, har jag bytt från att visa en lista av böcker vid sökning, till att istället visa ett rutnät av böcker.
Ett exempel på vad det skulle kunna gå att göra med teman i Koha.
Tipps och tricks
I macOS och i Linux kan man montera fjärrkataloger med hjälp av programmet sshfs. Tänk på att man måste ha root rättigheter på clienten och servern, och det måste gå att SSH till den.
mac
Tidigare har man kunnat installera dessa paket i från Brew (https://brew.sh/) men sedan en tid tillbaka får man installera dem manuellt. Adresserna finns nedan.
linux
I linux kan man istället (på en Debian 11 installation) installera sshfs direkt.
apt update && apt install -y sshfs
exempel
I både linux och mac använder man följande kommandon. Det är viktigt att inkludera idmap user eftersom det kommandot gör att du får de rättigheter som behövs på servern.
mkdir koha_mount # om den inte finns redan # Om man använder sig av ssh nyckel sudo sshfs -p <port> -o idmap=user -o allow_other,default_permissions,IdentityFile=<user home>/.ssh/id_rsa root@<ip addr>:/ koha_mount # tan ssh nyckel sudo sshfs -p <port> -o idmap=user -o allow_other,default_permissions root@<ip addr>:/ koha_mount # när man är klar sudo umount koha_mount
Externa editorer
De flesta editorer har funktioner för att göra livet lättare. Atom har en funktion som heter Atom Beautify som gör att man strukturerar obfuscate filer (filer anpassade till produktion) till läsbar text. Opac.css är huvud css filen till Koha.
Från detta
.alert{position:relative;padding:.75rem 1.25rem;margin-bottom:1rem;border:1px solid transparent;border-radius:.25rem}.alert-heading{color:inherit}.alert-link{font-weight:700}.alert-dismissible{padding-right:4rem}.alert-dismissible .close{position:absolute;top:0;right:0;z-index:2;padding:.75rem 1.25rem;color:inherit}.alert-primary{color:#004085;background-color:#cce5ff;border-color:#b8daff}.alert-primary hr{border-top-color:#9fcdff}.alert-primary .alert-link{color:#002752}.alert-secondary{color:#383d41;background-color:#e2e3e5;border-color:#d6d8db}.alert-secondary hr{border-top-color:#c8cbcf}.alert-secondary .alert-link{color:#202326}.alert-success{color:#155724;background-color:#d4edda;border-color:#c3e6cb}.alert-success hr{border-top-color:#b1dfbb}.alert-success .alert-link{color:#0b2e13}.alert-info{color:#143f6a;background-color:#d4e4f5;border-color:#c2d9f1}.alert-info hr{border-top-color:#adccec}.alert-info .alert-link{color:#0c263f}.alert-warning,.alert.alert-error{color:#856404;background-color:#fff3cd;border-color:#ffeeba}.alert-warning hr,.alert.alert-error hr{border-top-color:#ffe8a1}.alert-warning .alert-link,.alert.alert-error .alert-link{color:#533f03}.alert-danger{color:#601111;background-color:#f1d2d2;border-color:#ebc1c1}.alert-danger hr{border-top-color:#e5aeae}.alert-danger .alert-link{color:#350909}.alert-light{color:#818182;background-color:#fefefe;border-color:#fdfdfe}.alert-light hr{border-top-color:#ececf6}.alert-light .alert-link{color:#686868}.alert-dark{color:#1b1e21;background-color:#d6d8d9;border-color:#c6c8ca}.alert-dark hr{border-top-color:#b9bbbe}.alert-dark .alert-link{color:#040505}.breadcrumb{display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;padding:.75rem 1rem;margin-bottom:1rem;
Till detta
.alert {
position: relative;
padding: .75rem 1.25rem;
margin-bottom: 1rem;
border: 1px solid transparent;
border-radius: .25rem
}
.alert-heading {
color: inherit
}
.alert-link {
font-weight: 700
}
.alert-dismissible {
padding-right: 4rem
}
.alert-dismissible .close {
position: absolute;
top: 0;
right: 0;
z-index: 2;
padding: .75rem 1.25rem;
color: inherit
}