Mappestruktur i archtreet

bin - Executeables som cron-jobben som timer ut billettkjøp.
doc - Dokumentasjon som pakkeavhengigheter og diverse.
door - Alt som har med dørklienten å gjøre.
include - Konfigurasjon og egenutviklede biblioteker til Billig.
pdf - Maler for hvordan billettene skal se ut.
print - Kode for printerdemonen.
sql - Script til databasen(e), lagrede prosedyrer o.l.
templates - Template-filer for Billig web.
tmp - Område hvor webben lagrer temporære filer (f.eks genererte PDF'er)
web - kode for webdelen. Disse filene eksekveres ved browsing av billig.samfundet.no, resultatet presenteres i sin korresponderende template-fil i templates-mappa vha Template-modulen.

include

Billig/ - Katalog for moduler i Billig-biblioteket
Billig.pm - Hovedmodul for Billig-biblioteket
config.pm - generell fil for configurasjonsparametere til Billig.
config.local.pm - Installasjonsspesifikke configurasjonsparametere (Ikke i git, pga sikkerhet.)

include brukes av webdelen og inneholder filer som ikke behøver å ligge på web. Dette inkluderer et bibliotek med conveniencemetoder og felles funksjonalitet til Billig. I utgangspunktet skal funksjoner som brukes mer enn ett script i webdelen legges her. De viktigste funksjonalitetene i modulen er beskrevet under.

Billig biblioteket

Billig::

db_connect() - Koble til database.
process_template($page, $title, $vars) - Evaluere template. $page er navnet på template, $title er tittelfeltet på siden og $vars er input til template.
execute_other($script, $tmpl, $params) - Evaluere et annet script, med eventuelle ekstraparametere. $script er annet script, $tmpl er template for ekstraparametere og $params er parametere til ekstra template.
print_header() - Printer http-headere.
get_cookie_parms() - Henter registrert lokalisjon og printer fra cookie.
get_seller() - Henter innlogget selger.
compute_hmac($num) - Genererer hmac for ticketid $num.
validate_hmac($serial) - Validerer en hmac og returner ticketid ved suksess.

Billig::Print::

pdf_page($ticketno, $event, $ticket_group, $price_group, $price, $epoch, $note1, $note2, $layout) - Genererer billett i PDF-format.
pdf_page_from_db($dbh, $ticketno, $layout) - Generer billett i PDF-format basert på data hentet fra db (convenience).
print_tickets($printer_id, $dbh, $ticket_layout, $tickets) - Legger billetter i billettkø-

Billig::Untaint::

text($text) - Untaint tekststreng.
uint($text) - Untaing usigned int.
ufloat($text) - Untaing usigned float.
datetime($text) - Untaint dato, format yyyy-mm-dd [hh:mm[ss]].
point($text) - Untaint point. Brukt på layout til billetten.
box($text) - Untaint boundingbox. Brukt på layout til billetten.
any_of($text, @alternatives) - Untaint tekst, sjekk om tekst matcher noe i @alternatives.
checkbox($text) - Untaint valgt ikke valgt.
htmlize($text) - Untaint og htmlencode.

templates

Templates i Billig er skrevet etter XHTML 1.1. For å validere output brukes et perlbibliotek som validerer HTML generert av templatemotoren. Motoren brukt er et annet perlbibliotek "Template Toolkit" (dokumentasjon finnes her: http://www.template-toolkit.org/docs/index.html). Valideringen bør skues av på produksjonsapplikasjonen. Dette styres av '$validate_html' i configfila.

Vi prøver å holde mest mulig logikk i webkoden og utenfor templates. Dette gir et logisk skille mellom visningslogikk og bedriftslogikk.

For å holde antall klikk nede bruker vi execute_others. Dette gjør det mulig å vise to templates og kjøre to script. Typisk bruksområder er at siden for fullført salg også skal vise siden for salg av nye billetter.

For å vise feilmeldinger brukes en liste med errors. Templates hvor feil kan oppstå har en forløkke som looper over denne listen og printer eventuelle feil.

web

I webkatalogen ligger alle filene som kan aksesseres fra web. Filene følger regler for kodestil, navngivning, flyt o.l. som beskrevet her.

Flyt i script

Perl er et funksjonelt språk og script kjøres fra topp til bunn. Feilsjekker fører til at scriptet gir nødvendig output og avslutter. Ved normal kjøring uten feil vil man forvente at programmet avslutter i bunn.

Indentering og kodestil.

Det beste rådet er å lese kode som allerede ligger inn. Men noen retningslinjer finnes

Lange linjer bør brekkes.
Kode skal se ryddig ut.
Det er lov å bruk mellomrom. Feks mellom if og parantesene som holder en condition, og mellom condition og krølleparentes.
Parametere et script tar inn lese inn øverst og valideres med en gang.

Navngivning

En funksjon pr script.
Navn på script skal reflektere funksjon.
En script for å vise skjema for salg heter sell.pl,

Når bruker man POST og GET

TODO: (vegarwe) flyt i script, indentering, navngiving av filer, et script pr funksjon, POST/GET

Webgrensesnitt

Grensesnittet er skrevet i Perl, og bruker Template Toolkit for generering av HTML. Man har også skrevet en Billig-modul hvor man har samlet generelle ting knyttet til rammeverket, printing og convenience-funksjoner. Alle templates ligger i ./templates, mens Perl-scriptene som kjøres ligger i ./web. Configfiler og Billig-modulene ligger i ./include, trygt utenfor webrooten, slik at man ikke ved et uhell eksponerer databasepassord og lignende. Systemet kan kjøre under både CGI og mod_perl, men yter naturlig nok bedre under sistnevnte. (Utover ytelsen er de to kjøremåtene stort sett identiske.)

Rammeverket som er laget, pakker inn funksjonaliteten fra Template Toolkit og tilbyr Billig::print_headers(), Billig::process_template() og Billig::execute_other(). (Det finnes også en del nyttefunksjoner relatert til bl.a. utskrift, feilhåndtering, databasetilkobling, tilgangskontroll, HMAC-generering, og mye mer – med unntak av utskrift, som ligger i Billig::Print, ligger det meste av slikt delt funksjonalitet rett i Billig-modulen.)

print_headers vil sette Content-type og lignende.
process_template vil laste den gitte templatefilen og parse denne med de gitte parametrene.
execute_other vil først parse en gitt template med de gitte parametrene. Deretter vil den kjøre et annet Perl-script etter ønske. Dette gjøres f.eks. når man har kjøpt billetter og ønsker å vise hvilke billetter som er kjøpt. Da kan man etter å ha vist resultat for det gitte salget, fortsette med å vise selgergrensesnittet slik at man raskt kan selge flere billetter.

Når man selger billetter vil det bli dyttet PDF-er inn i en printerkø i databasen slik at winprint (printerdemonen; se Billig utskrift) får tak i disse. For at scriptet skal vite hvilken printerkø den skal legge PDF-en i, vil det settes en cookie i nettleseren. Denne settes når man forsøker å selge billetter, eller prøver å reprinte gamle ordre (med andre ord, omtrent idet man trenger den første gang).

Tilgangskontroll løses på to nivåer: Grunntilgang (som stort sett kun innebærer å kunne liste opp arrangementer og selge billetter) sjekkes i Apache-configen ved bruk av mod_auth_itk (altså med SSO og det hele); videre tilgang skjer «manuelt» i scriptene vha. ITKACL.

Lenker: Start, billig, billig, hvordan utvikle