Wikipedia:Formalkrav til maler

Denne siden er et utkast til en offisiell retningslinje på Wikipedia. Det er fritt fram for redigering av siden, men det anbefales at endringer beskrives på diskusjonssiden, og at omfattende endringer diskuteres der før de gjøres slik at andre lettere kan følge prosessen.

Formalkrav til maler beskriver felles grunnleggende krav for bruk, kode, stil og dokumentasjon av malverk. Maler kan i tillegg følge regler gitt av andre anbefalte regler og retningslinjer og være underlagt regler gitt etter diskusjoner på Wikipedia:Tinget. Det kan også finnes utkast til regler og retningslinjer som er av betydning for hvordan maler bør settes opp og hvordan de bør brukes, selv om de kun er etablert gjennom konsensus og ikke via avstemming.

Maler som i vesentlig grad endrer prosesser og rutiner på Wikipedia bør tas opp til diskusjon før de settes i produksjon.

Stilark

Det er et krav at maler skal bruke klasser fra felles stilark, i utgangspunktet Mediawiki:Common.css, og deretter drakt-spesifikke tilpassinger ved behov. Forsøk i størst mulig grad å unngå bruk av lokal stil via style-attributtet, dette skaper problemer fordi disse stilene motstår sentralt gitte stiler. Merk at dette også gjelder for høyde og bredde.

Hvis maler er interaktive så kan det være akseptabelt å bruke en lokal stil for å gi en spesifikk åpningstilstand. Dette er for at en skal få en kjent og ønsket tilstand som kan manipuleres videre i Javascript. Vurder i hvert tilfelle om det er mer ønskelig å sette en klasse for å få denne åpningstilstanden, eller om også åpningstilstanden bør settes med Javascript.

Stiler knyttet til manipulering av maler bør som hovedregel settes opp som en tilleggsfunksjon som er påslått for alle. Dette sikrer at stiler med spesiell funksjon skilles ut og får konsistent dokumentasjon.

Alle stiler, både de som gis lokalt i en mal og globalt via stilark, skal ta høyde for responsivt design.

Javascript

Maler skal i utgangspunktet ikke være avhengig av Javascript for korrekt funksjon. Hvis det av noen grunner er nødvendig å bruke Javascript så skal malens standard funksjon være slik at all nødvendig informasjon som standard er fullt tilgjengelig uten Javascript.

Merk at Javascript som henter ut brukergenerert innhold, og som deretter endrer egen programflyt på bakgrunn av dette innholdet, er utsatt for et sikkerhetsproblem control hijacking og bør derfor sjekkes av erfarne programmerere.

Script knyttet til manipulering av maler bør som hovedregel settes opp som en tilleggsfunksjon som er påslått for alle. Dette sikrer at script med spesiell funksjon skilles ut og får konsistent dokumentasjon.

Se også mw:Manual:Coding conventions/JavaScript for mer om konvensjoner om hvordan bruke dette scriptspråket.

Lua

Lua er et mer avansert scriptspråk for maler. Det er et fullt programmeringsspråk, med de problemer et slikt vil medføre. Hvis en mal er ikke-triviell å sette opp som en ordinær mal så bør det vurderes om det bør skrives en Lua-modul.

Fordi Lua er et programmeringsspråk så bør det stilles krav til testbarhet og kodekvalitet, men for øyeblikket er mulighetene til å kreve slikt noe begrenset. Fordi Lua kjøres i et sterkt begrenset miljø på Wikimedia Foundations egne servere er risikoen for brukere på internett begrenset. Spør likevel erfarne programmerere før kode settes i produksjon.

Se også mw:Lua scripting for mer om hvordan du bruker dette scriptspråket.

Dokumentasjon

Alle maler skal ha dokumentasjon som forklarer bruksområdet. Det er flere mekanismer som er i bruk for dokumentasjon, men det er to som skiller seg ut og som bør brukes.

{{dokumentasjon}}

Denne løsningen er sterkt anbefalt for alle nye maler.

Ved å sette inn <noinclude>{{dokumentasjon}}</noinclude> på malsiden vil det dukke opp flere lenker på siden når den vises frem. En av disse viser til undersiden /dok, og følges denne lenken så vil en få opp en ferdig formatert dokumentasjonsside. (Ser ut som om dette feiler i preview.) Svært ofte følges en fast struktur, men det er også en del fritt formaterte sider.

Formatering av dokumentsajonsunderside

{{Dokumentasjonsunderside}}
<!-- LEGG TIL KATEGORIER PÅ BUNNEN AV DENNE SIDEN -->
== Formål ==

== Bruk ==

== Eksempler ==

== Se også ==

<includeonly>
<!-- KATEGORIER UNDER DENNE LINJEN -->
</includeonly>

Hvis en mal er av en gruppe maler som har felles funksjon (slik som {{Buskerud}}, {{Oppland}} og {{Hedmark}}) og ingen eller identiske parametre, eller så kan undersiden være en omdirigering til en felles dokumentasjonsside (slik som Mal:Fylkesmaler/dok brukes på malene for Buskerud, Oppand og Hedmark). Hvis funksjonen bare er delvis lik så kan en sette inn det som er felles dokumentasjon ved transkludering på undersiden. Det bør fremgå av dokumentasjonssiden hvilke deler som er felles.

TemplateData

Denne løsningen er sterkt anbefalt for alle maler som brukes på innholdssider.

Det er flere måter å beskrive template parametre, men den helt klart beste er å bruke tag-funksjonen <templatedata>. Når denne er lagt inn på malens dokumentasjonsside så vil det bli mulig å bruke et eget verktøy for å dokumentere malen og dens parametre, denne dokumentasjonen vil bli synlig på dokumentasjonssiden, og den vil bli tilgjengelig under redigering i VisualEditor.

Sett inn template data slik

<templatedata>
{
  "description": "Tekst som beskriver malen",
  "params": {
  }
}
</templatedata>

Hvis blokken legges på en dokumentasjonsunderside så plasseres template data i seksjonen «Bruk».

Se også mw:Help:TemplateData for mer informasjon om hvordan du bruker template data.