TKL
Dokumentation
Index Data
TKL (Toolkit Lite) er et softwaresystem til at drive informations-drevne portaler. Med portaler tænkes på websites der stiller informationsressourcer til rådighed af forskellig art. Det kan være firma- eller personlige hjemmesider, "subject gateways", eller mange andre ting. Med TKL leveres en "basisportal", der kan rumme en hierarkisk organiseret samling metadata-links til eksterne ressourcer, men som også kan præsentere sit eget indhold; artikler, nyheder, mm. Ved at udvide basisportalen, eller konstruere en ny basis-skabelon kan stort set alle mulige typer af informations-sites konstrueres.
TKL kan ses som et alternativ til egentlige, lukkede "content-management" systemer eller til special-konstruerede, database-drevne systemer. Specielt til sites der naturligt er organiseret som samlinger af dokumenter kan med fordel implementeres over TKL. Og systemet er specielt velegnet i situationer hvor adskillelsen imellem information og præsentation betragtes som vigtig.
TKL organiserer en informationsportal som en samling af dokumenter af forskellige typer. Dokumenterne er gerne organiseret i en katalog-struktur der afspejler den logiske struktur i portalen. Dokumenterne er repræsenteret i standard XML. En portal består i reglen af forskellige dokument-typer, hvor hver type er givet af et XML-schema, der beskriver hvilke felter der indgår, hvilke felter der må gentages, etc. XML-schemaet rummer også TKL-specifik information, f.eks. om et givet felt er søgbart, skal forekomme på flere sprog, etc.
XML-filerne ligger gemt som helt almindelige tekstfiler på serverens filsystem (eller på en sådan måde at de kan nåes derfra, f.eks. via netværksdrev). Alle TKL-dokumenter har endelsen .tkl. Webserveren er sat således op, at når brugeren forsøger at læse et dokument med .tkl-endelsen, så startes TKL-s "brugerskal". Brugerskallen er ansvarlig for at vise dokumentet til brugeren på en passende måde.
Til fremvisningsformål er hver dokument-type tilknyttet et bestemt fremvisningsformat. Således vises f.eks. en hjælpefil anderledes end en emnegruppe, og så fremdeles. Fremvisningsformaterne består af "stylesheets" i standard-sproget XSLT. Det er altså bruger-skallens opgave, for et givent dokument, at afgøre hvilket XSLT-stylesheet der skal benyttes for at vise dokumentet. Udover dokumentet selv stiller bruger-skallen en række oplysninger og hjælpefunktioner til rådighed for stylesheetet. Det kan f.eks. være oplysninger om hvor i portalens hierarki dokumentet befinder sig, og om der ligger andre dokumenter i nærheden, men det er også tjenester som f.eks. søgning.
En TKL-portal består altså af tre grundlæggende elementer:
Dokumenterne er kærnen i hele systemet – de definerer selve portalens indhold. Dokument-typerne, især deres XML-schemas, bliver mest benyttet når en portal vedligeholdes. Præsentations-formaterne benyttes når brugeren skal se et givent dokument.
Sammen med TKL leveres et eksempel på en basisportal. Denne portal er et eksempel på en anvendelse af TKL, og den kan frit udvides og benyttes som udgangspunkt for nye portaler.
Alle portalens sider er bygget op om en fælles grundstruktur, der består af en grafisk bar i toppen af siden der giver portalen identitet. Nedenunder findes en menu med visse faste funktioner inklusive en søgeknap. Til venstre findes den egentlige hovedmenu for portalen der også giver mulighed for at skifte sprog. I midten er indholdsvinduet, hvor portalens egentlige indhold præsenteres. Til højre er et nyhedsvindue.
Hovedsiden for portalen viser toppen af emnehierarkiet for portalen. Man kan klikke på de enkelte emneområder og på den måde navigere sig rundt i emnestrukturen. Man kan også herunder se de enkelte metadata, eller referencer, til eksterne ressourcer som er katalogiseret i portalen.
Ved at klikke på en nyhedsartikel, "vis flere nyheder" linket (som vises når der er flere nyheder end der er plads til i vinduet), eller "Nyheder"-menupunktet i hovedmenuen, så kommer man til en nyhedsside hvor den fulde tekst af alle nyheder i systemet kan vises.
Ved at klikke på "Hjælp" i den øverste menu kommer man til et system af hjælpesider.
Ved at klikke på "Artikler" i venstremenuen kommer man til et system af lokale artikler.
Ved at indtaste et eller flere søgeord i søgefeltet, kan man udføre en søgning i portalen. Administratoren kan selv styre hvilke dele af portalen der søges i.
Artikler og hjælpefiler er begge beskrevet af den samme dokumenttype, document.tkl. Dette er en generel artikel-type, der har den egenskab at den i fremvisning kan præsentere en "mini-menu" over eventuelle under-dokumenter. Således er det muligt at bruge denne dokumenttype som en art byggeklods til at opbygge enddog meget komplekse strukturer af dokumenter.
Bemærk – visse af de herunder givne eksempler refererer til basisportalen tkl-test1.
En portals indhold administreres generelt ved hjælp af TKLs administrationsgrænseflade (admin). Siden portalens indhold er repræsenteret som filer i serverens filsystem er det også muligt at vedligeholde filerne via en almindelig brugerkonto, eller via egne scripts, mv. Men admin muliggør kontrolleret vedligeholdelse af portalens væsentligste indhold via en almindelig browser, og under kontrollerede forhold (f.eks. adgangkontrol, re-indeksering af søgeindekser efter behov, mv.).
Administrationsskallen startes ved at angive URL'en for scriptet admin.php (den præcise URL afhænger af installationen, med parametren cwd som skal angive hvor portalen findes i forhold til serveren dokumentkatalog.
For eksempel, hvis testportalen er installeret under htdocs/tkl på serveren www.indexdata.dk (således at den kan nåes med URLen http://www.indexdata.dk/tkl/), og de administrative scripts ligger under kataloget htdocs/tkl-admin, så kan admin-skallen nås således:
http://www.indexdata.dk/tkl-admin/admin.php?cwd=tkl
Nu skulle admin-fladens hovedvindue gerne vise sig, og vi vil i de følgende afsnit beskrive de enkelte elementer i denne grænseflade.
Vi vil i det efterfølgende beskrive hvorledes data konkret er organiseret i filsystemet i kasser som denne. Administratorer, som helt eller primært påtænker at administrere portalen via admin-grænsefladen kan gå udenom disse kasser efter ønske.
Øverst i grænsefladen vises først katalogerne under portalen – disse vil typisk svare til helt grundlæggende under-afsnit af portalen. I tkl-test1 findes således flg. kataloger
Man kan til hver en tid slette (tomme) kataloger, og oprette nye kataloger. Man kan ligeledes omdøbe kataloger, men man skal huske, at visse af de helt grundlæggende kataloger forventes at ligge bestemte steder. I tkl-test1-portalen gælder det f.eks. link-kataloget.
Hvis man klikker på et katalognavn hopper admin-fladen ned til det givne katalog. Man kan til hver en tid komme tilbage ved at klikke på brødkrummestien i toppen af vinduet.
Admin-skallen viser filer og kataloger der findes på det givne niveau i serverens filsystem. Dog skjules visse system-specifikke underkataloger for at forenkle grænsefladen.
En portals hovedkatalog eller rodkatalog er defineret som det katalog der indeholder en fil ved navn "tkl.config". Alle funktioner i systemet tager udgangspunkt i dette rodkatalog når der henvises til stier, mv.
Under katalogerne vises en liste over de dokumenter, der ligger i det givne katalog. De fleste dokumenter kan umiddelbart rettes, dog med visse undtagelser.
Filerne users.tkl og directory.tkl kan kun rettes af brugere med administrative privilegier. Filen users.tkl beskriver brugerne i systemet, directory.tkl beskrives herunder.
Hvis der ligger en fil ved navn index.tkl i kataloget, så er det det dokument som den almindelige bruger får at se hvis han hopper ind på det givne katalog med sin browser. Dette svarer helt til filen index.html i en almindelig website.
Alle kataloger kan rumme en fil ved navn directory.tkl. den beskriver forskellige egenskaber der kan knyttes til et givent katalog (og alle underkataloger, undtaget underkataloger der selv indeholder en directory.tkl fil). Disse filer kan indeholde flg. elementer.
|
Felt |
Beskrivelse |
|
Søgbart |
Angiver om kataloget (og underkataloget) skal være søgbart. |
|
Autoindex-fil |
Angiver, om der automatisk skal oprettes en index.tkl-fil når et nyt underkatalog oprettes, og i givet fald efter hvilket format (schema). |
|
Tilladt schema (kan gentages) |
Angiver hvilket/hvilke dokument-typer der kan/må være i et givet katalog (og underkataloger). F.eks. må man i basisportalen tkl-test1 kun oprette nye dokumenter af typen news. Man kan også her angive hvorledes nye filer af den givne type skal navngives i filsystemet – dette er så en administrator ikke selv skal tænke på at navngive f.eks. et nyt nyhedsdokument. |
Alle dokumenter kan (såfremt man har rettigheder hertil) redigeres via et fælles redigeringsvindue. Forskellige dokumenttyper vil tage sig forskelligt ud i vinduet, med forskellige felter, mv. F.eks. har metadata-poster for web-ressourcer et "url"-felt forsynet med en særlig "link-checker" knap.
Editoren er forsynet med knapper til at valiedere dokumentet, dvs. checke om alle felter er udfyldt korrekt, til at gemme dokumentet (her bliver ligeledes foretaget en validering), samt til at lukke editor-vinduet og vende tilbage til admin-vinduet.
For elementer der er sprog-afhængige bliver man bedt om at udfylde elementet på alle relevante sprog.
Beskrivelse af schema-editoren her.
Brugerlisten findes i portalens hovedkatalog, i filen users.tkl. Den kan kun redigeres af brugere med administrator-privilegier. Her kan man operette nye brugere, eller ændre egenskaber for eksisterende brugere.
Grundportalen består af fire hovedområder, der ses som kataloger når man åbner admin-fladen under hovedsiden:
Nyhederne har den enkleste struktur. Hvis man hopper ned til dette katalog finder man, at man kun kan oprette filer af een type, nemlig typen news. For at oprette en ny artikel klikker man simpelthen på "Opret post" og udfylder de givne felter. Filen "index.tkl" i dette katalog kan ikke redigeres da den ikke har noget egentligt indhold – den definerer siden man kommer til for at se de detaljerede nyheder, men denne sides indhold udgøres alene af de enkelte nyheds-dokumenter, så selve index.tkl er altså tomt her.
Går man tilbage til toppen og klikker på Artikler, finder man dels en index.tkl-fil, dels en samling underkataloger. index.tkl er det dokument man kommer til ved at vælge "artikler" fra portalens hovedmenu. Underkatalogerne definerer underdokumenter, som man i portalens grænseflade finder i en liste nederst på siden. Hvert af disse underkataloger rummer selv en index.tkl fil der definierer indholdet af dette (under)dokument, og det kan også indeholde flere underkataloger, og så fremdeles. Ved at opbygge et hierarki af artikler, kan man f.eks. opbyge en hel encyklopædi eller en artikel-samling til sin portal. Det er også muligt at udvide portalen ved at lave flere forskellige slags "Artikel"-kataloger som man så kan nå fra hovedmenuen. Bemærk filen directory.tkl (mere om den ovenfor) i artikel-kataloget. Det er den, der bestemmer at i dette katalog må der altså kun være dokumenter af typen "document", og ikke f.eks. nyheds-dokumenter. Men man kan også i directory.tkl angive om kataloget skal være søgbart, og således bestemme om portalens søgefunktion også skal omfatte artikelsamlingen.
Hjælpe-kataloget er opbygget på præcis samme måde som artikel-kataloget.
Link-kataloget har derimod en anden struktur. Klikker man på dette finder man en samling underkataloger svarende til de øverste niveauer af portalens emne-hierarki. Under disse kataloger findes flere underkataloger og, i visse tilfælde, metadata om eksterne ressourcer. Hvert emne-katalog indeholder en index.tkl fil af typen "subject", som angiver navnet på emnegruppen. Hvis der er katalogiseret ressourcer under den givne emnegruppe, så ligger de i dokumenter af typen "link". Man kan tilføje nye ressourcer blot ved at oprette nye filer af typen "link", og man kan oprette nye kategorier på ethvert niveau blot ved at oprette et nyt underkatalog. Man vil automatisk blive bedt om at udfylde et subject-dokument for den nye emnegruppe, med gruppens navn. Man kan selv vælge navnene på de enkelte underkataloger – disse katalognavne bliver ikke vist for portalens brugere.
Admin-fladen sørger for, hver gang et dokument er blevet skrevet, at undersøge om det skal gøres søgbart – dette gøres ved at læse filen directory.tkl i samme katalog som filen selv eller derover (op til roden af portalen). Hvis filen er søgbar kaldes index-programmet, som øjeblikkelig lægger filen ind i de inverterede filer for søgefunktionen. Man kan også fra administrationsfladen foretage en total reindexering (f.eks. hvis man har lavet om på, hvilke kataloger der skal være søgbare), samt stoppe og starte søge-serveren.
Dette afsnit beskriver funktionen af TKLs brugerflade, samt administrationen af den egentlige brugergrænseflade. Generelt fordrer administration af grænsefladen – i modsætning til portalens indhold – tekniske fagkundskaber – specielt et basalt kendskab til arbejde med filer og kataloger under Unix, samt XML og XSLT.
I Apache-konfigurationsfilen er fil-typen .tkl sat op til at skulle håndteres af scriptet shell.php der følger med TKL. Dette er brugerskallen for TKL, det program der sørger for at et givent dokument bliver knyttet sammen med det rette fremvisningsformat (i form af et XSLT stylesheet).
Det første brugerskallen gør er at finde roden for den portal, det givne .tkl dokument tilhører. Det gøres ved at undersøge hvert katalog, fra .tkl-filens placering og opefter og søge efter filen tkl.config. Det er en fejl hvis denne fil ikke findes. Portalens rod-katalog danner basis for en række referencer man kan foretage internt i sine stylesheets. Ved at knytte roden til placeringen af tkl.config-filen sikres det, at man med lethed kan drive flere TKL-baserede portaler på den samme maskine, endda under den samme webserver.
Herefter afgøres det hvilket stylesheet der skal bruges til at vise filen for brugeren. Til dette formål findes navnet på dokumentets dokument-tag, f.eks. <subject>. Herefter kigger brugerskallen i det nuværende katalog, og derefter opad imod portalens rod efter en .xsl-fil med samme navn (bemærk, at dette gør det muligt at have flere .xsl-filer for samme dokumenttype – brugerskallen vil altid bruge den der er tættest på dokumentet i den hierarkiske struktur). Hvis der ikke findes nogen .xsl-fil vises den rå XML-fil, men det må nok betragtes som en fejl i portalens opsætning.
Det næste skridt er at foretage en forbehandling af både .tkl-dokumentet og stylesheetet. Herunder fjernes alle XML-elementer der har en xml:lang attribut der IKKE matcher brugerens aktuelle sprogvalg. Brugeren vælger sprog ved at angive en "lang"-parameter i HTTP-forespørgslen, og sproget gemmes i en cookie-baseret sessionsvariabel fra forespørgsel til forespørgsel. Denne teknik til at håndtere sprog giver en simpel måde at styre sprogvalg på. Admin-fladens XML-editor sørger selv for at bede brugeren om at levere sprog-varianter af sprog-afhængige felter. XSLT-forfatteren skal så blot huske at lave forskellige sprog-varianter af relevante dele af stylesheetet. Optræder en enkelt sprog-afhængig tekst midt i en større mængde HTML kan man benytte <span> elementet med en xml:lang attribut til at indkapsle de enkelte sprogvarianter. Man behøver altså generelt ikke tage højde
Nu foretages en konvertering af .tkl-dokumentet med det givne stylesheet, og resultatet sendes til brugeren (det antages naturligvis, at stylesheetet producerer HTML der kan vises for brugeren [1]).
Fordi stylesheetet skal vide noget om dokumentets placering og kontekst i den større sammenhæng, stiller brugerskallen en række parametre og tjenester til rådighed for stylesheetets udførelse. Det drejer sig dels om parametre der kan læses fra stylesheetet, og særlige retrieval schemes der kan nås via XSLT's standard document() function og som kan returnere forskellige typer af information.
Ved blot at erklære en parameter (via <xsl:parameter>) kan programmøren få adgang til eventuelle brugerparametre i HTTP-forespørgslen.
Bemærk, at lang-parameteren altid er tilgængelig, uanset om brugeren har angivet den eller ej.
Desuden findes visse system-specifikke parametre der kan benyttes efter behov, specielt
Undertiden er det nyttigt at kunne associere parametre med brugerens session – for at undgå at føre en lang parameterstreng rundt i hele systemet. I brugerskallen kan dette gøres ved hjælp af en særlig tag. Eksempel:
<xsl:param name="sort"/>
<portcom:session-var name="sort" default="title"
xmlns:portcom="http://www.indexdata.dk/TKL"/>
<xsl:param>-taggen introducerer en parameter på normal vis. <portcom:session-var> informerer brugerskallen om at den givne parameter skal gemmes og knyttes til brugerens session. Default-parameteren er valgfri. Den gemte værdi overskrives hvis brugeren (via GET/POST) leverer en værdi for den givne parameter.
Hjælpefunktionerne er nøglen til brugerskallens funktion, og det er vigtigt at forstå de muligheder de stiller til rådighed hvis man vil bruge TKL seriøst.
Da der pt. mangler en god standardiseret metode til at definere/kalde eksterne funktioner har vi valgt at implementere vores hjælpefunktioner som private URL-schemes der kan benyttes i document()-funktionen, men også f.eks. i <xsl:import> og <xsl:include>.
Herunder beskrives de enkelte hjælpefunktioner. Alle funktionerne returnerer deres resultat i form af et XML-dokument, der efterfølgende kan behandles på normal vis i XSLT.
Bemærk, at når disse funktioner kaldes inde fra XSLT, skal & repræsenteres som &
tkl-file
Funktion: Læser en fil.
Synopsis: tkl-file:path
Resultat: Indholdet af filen under path.
Dette scheme minder til forveksling om det almindelige file: scheme som er standard i XSLT. Der er to væsentlige forskelle.
Hvis stinavne angives relativt, så tager de udgangspunkt i det katalog hvor .tkl-dokumentet blev fundet – ikke i det katalog hvor stylesheetet er placeret. Dette er væsentligt, da dokumentets placering tit har en betydning. Endnu vigtigere: Hvis stien er absolut (starter med //), så tager den udgangspunkt i portalens rodkatalog. Dette er en praktisk måde at inkludere globale stylesheet-moduler som interface.xsl og news.xsl i basisportalen.
Den anden forskel er, at det givne dokument bliver forbehandlet ligesom stylesheetet selv, det vil primært sige at evt. sprog-adhængige elementer (xml:lang) bliver filtreret før dokumentet returneres.
tkl-find
Funktion: Finder filer der matcher en maske.
Synopsis:
tkl-find://?path=pathmask&mask=filemask&select=fieldmask&level=number
Resultat: Liste af <file> elementer der rummer de elementer der er angivet i fieldmask.
Eksempel:
tkl-find:/?path=*/index.tkl&select=title
<?xml version="1.0" encoding="ISO-8859-1"?><tkl-find> <file path="./news/index.tkl"> <title>Nu med links!</title> </file> <file path="./oldcheese/index.tkl"> <title>Gammel ost på nye flasker</title> </file> .....</tkl-find>
Funktionen tkl-find kan bruges på to måder. I den simple version søger den efter filer der matcher path-parametre (kan sammenlignes med opslag via filename patterns i en Unix-shell. Den returnerer et antal file-elementer der hver rummer de elementer der er valgt af fieldmask-parametren.
Fieldmask-parametren har formen element|element|.... altså et vilkårligt antal element-navne adskilt af lodrette streger.
Funktionen kan også benyttes mere ligesom Unix's find-kommando, der rekursivt traverserer eet eller flere undertræer.
Dette eksempel fra basisportalen tkl-test1 finder alle index.tkl-filer i underkataloger under links/* i to niveauer.
tkl-find:/?path=links/*&mask=index.tkl&select=title&level=2
<?xml version="1.0" encoding="ISO-8859-1"?><tkl-find> <dir path="./links/27/" level="1" att="2"> <file path="./links/27/index.tkl"> <title xml:lang="en">General Subjects</title> </file> <dir path="./links/27/01/" level="2" att="2"> <file path="./links/27/01/index.tkl"> <title xml:lang="en">Cross-disciplinary subjects</title> </file> </dir> <dir path="./links/27/03/" level="2" att="2"> <file path="./links/27/03/index.tkl"> <title xml:lang="en">Library collections</title> </file> </dir> </dir> ................</tkl-find>
(bemærk at strukturen ovenfor repræsenterer et hierarki hvor kataloger både kan rumme filer og andre kataloger).
Hvis path-udtrykket kun matcher filer er der ingen grund til at angive en maske. Hvis path-udtrykket matcher kataloger vil rutinen undersøge disse underkataloger og kigge efter filer der matcher mask-parameteren, indtil level niveauer.
Både <dir> og <file> elementer har en path-attribut der giver den relative sti til filen i forhold til det oprindelige .tkl-dokument. Dette betyder som regel at disse stier uden videre kan anvendes f.eks. i et HTML <A> element som relative URL'er.
Bemærk dog at hvis path-udtrykket er absolut (starter med "/"), så bliver det behandlet som absolut med respekt til portalens rod, og path-attributten i <dir> og <file> elementerne kan direkte benyttes som server-absolutte URL'er, f.eks.
tkl-find://?path=/news/news*.tkl&select=date|title <tkl-find> <file path="/tkl/news/news1.tkl"> <date>2002-07-08</date> <title xml:lang="en">The test has begun</title> </file> <file path="/tkl/news/news429.tkl"> <date>2002-07-10</date> <title xml:lang="en">The news entries have been cleaned out</title> </file></tkl-find>
Bemærk, at tkl-find, ligesom de andre funktioner, forbehandler deres resultater således at sprog-markerede elementer filtreres. Man bør altså normalt ikke behøve bekymre sig om sprog-varianter i sine stylesheets.
tkl-path
Funktion: Returnerer en "brødkrummesti" til portalens rod.
Synopsis: tkl-path:/?select=title
Eksempel:
<?xml version="1.0" encoding="ISO-8859-1"?><tkl-path> <step path='./../../../'> <title xml:lang="en">Bibliotheca</title> </step> <step path='./../'> <title xml:lang="en">Social Sciences</title> </step> <step path='./'> <title xml:lang="en">Law</title> </step></tkl-path>
Tkl-path returnerer en XML-repræsentation af brødkrummestien fra et givent dokument til portalens rod. I Basisportalen tkl-test1, interface.xsl findes i skabelonen insert-path et eksempel på brugen af denne funktion – den benyttes i basisportalens sider til at indsætte en klikbar brødkrummesti på hver side.
Funktionen virker ved at kigge i alle kataloger op til roden efter en index.tkl fil. For alle index.tkl filer returneres et <step> element med en path-attribut der angiver en relativ sti. Stien kan generelt benyttes direkte som relativ URL i en HTML <A> tag.
tkl-search
Funktion: Søger i en Z39.50 database
Synopsis
tkl-search://unix:/home/indexdata/html/tkl/db/socket?query=@attrset idxpath
computer &start=1&syntax=xml&number=6
Eksempel:
<?xml version="1.0" encoding="ISO-8859-1"?><search> <start>1</start> <number>6</number> <server url="unix:/home/indexdata/html/tkl/db/socket" status="1"> <hits>6</hits> <end>6</end> <record offset="1"> <subject xmlns:idzebra="http://www.indexdata.dk/zebra/"> <title xml:lang="en">Computer science</title> <idzebra:size>153</idzebra:size> <idzebra:localnumber>332</idzebra:localnumber> <idzebra:filename>links/30/05/index.tkl</idzebra:filename> </subject> </record> ............... <record offset="6"> ....... </record> </server></search>
Tkl-search udfører en søgning imod den angivne Z39.50 server. Addressen på serveren følger generelt Z39.50 URL-formatet, selvom eksemplet ovenfor ikke er standard, men en Index Data-specifik udvidelse der tillader brugen af UNIX filsystem-sockets (UNIX domain sockets) i stedet for internet host-adresser og portnumre. Til TKLs lokale søgefunktion benyttes UNIX-domain sockets i stedet for internet-adresser for at undgå at skulle allokere en TCP/IP port til hver portal – herved forenkles administrationen af TKL.
Parametrene start, number, og syntax fungerer som man forventer, og queries angives i PQF-formatet (beskrevet på http://www.indexdata.dk/yaz/doc/tools.php#AEN2265).
Resultatet kommer tilbage i en struktur som vist ovenfor. Specielt bliver brugerens start- og number- parametre gentaget i XML-strukturen. I server-understrukturen (som med tiden kan gentages når der opstår et behov for multi-target-søgning) findes antallet af fund, samt det højeste postnummer, som er returneret. Herefter følger et antal record elementer der hver især rummer een post fra serveren.
I TKL benyttes tkl-search-funktionen til at søge imod portalens søgeindex som ligger i en Zebra-serveren. Bemærk ovenfor, at Zebra for hver enkelt post inkluderer postens sti i elementet <idzebra:filename>.
tkl-soap
Funktion: Giver adgang til funktioner på fjernsystemer via SOAP remote procedure calls.
Synopsis: tkl-soap:/MyTestService.wsdl?tkl:fun=weirdFunction&Hello
World
Eksempel
<?xml version='1.0' ?><env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction"env:encodingStyle="http://example.com/encoding"
env:mustUnderstand="true" > 5 </t:transaction> </env:Header> <env:Body> <m:reserveAndChargeResponse env:encodingStyle="http://www.w3.org/2001/12/soap-encoding" xmlns:rpc="http://www.w3.org/2001/12/soap-rpc" xmlns:m="http://travelcompany.example.org/"> <rpc:result>m:status</rpc:result> <m:status>confirmed</m:status> <m:reference>FT35ZBQ</m:reference> <m:viewAt> http://travelcompany.example.org/reservations?code=FT35ZBQ </m:viewAt> </m:reserveAndChargeResponse> </env:Body></env:Envelope>
Tkl-soap giver adgang til vilkårlige, SOAP-baserede sk. web-services hvorsomhelst på internettet. Parametrene til funktionen består af en service-definitionsfil (WSDL), et funktionsnavn, og en række parametre. Parametrene kan struktureres på forskellig vis for at muliggøre brugen af forskelligartede funktioner.
WSDL-filen kan angives som et relativt eller absolut stinavn (disse bliver som sædvanlig fortolket med udgangspunkt i TKL-dokumentets placering, eller som en HTTP URL).
Forskellige funktioner stiller forskellige krav til strukturen af deres parametre. F.eks. kan Google kaldes med en liste af unavngivne parametre, som en normal funktion. Det følgende eksempel er en lovlig Google-søgning som den ser ud i et stylesheet.
INDSÆT fra tkl-test1/soap/google/google.xsl
Bemærk, at '&' skal repræsenteres som XML-entity i stylesheetet. I eksemplet bruges 'concat' til at konstruere argumenterne alene for at øge læsbarheden. Man kan forestille sig at "$query" i eksemplet herover er en parameter der er leveret fra brugerens forespørgsel (se ovenfor om parametre i brugerskallen).
Parametre til SOAP-funktioner kan også navngives eksplicit – f.eks.
tkl-soap:MyTestService.wsdl?tkl:fun=myFunction&alpha=1&beta=2
Visse funktioner kræver struktureret data. F.eks. giver argumenterne
primitive=test&alpha.a=bob&alpha.b=bub
strukturen:
primitive=>test, alpha=>{a=>bob, b=>bub}
Understrukturer kan også være anonyme, f.eks:
.a=bob&.b=bub
strukturen
{a=>bob, b=>bub}
Konkret kan Amazon.com søges på denne måde
<xsl:variable name="result" select="document(concat( 'tkl-soap:AmazonWebServices.wsdl?', 'tkl:fun=KeywordSearchRequest', '&.keyword=', $squery, '&.page=2', '&.mode=books', '&.tag=webservices-20', '&.type=lite','&.devtag=', token,
'&.format=xml', '&.version=1.0' ))"/>
Hvis debugging er slået til (se nedenfor), vil både SOAP request-pakken og svaret blive vist, så man let kan afgøre om man har konstrueret de rigtige parametre i forhold til den givne webservice.
Ved at tilføje HTTP-parameteren debug=1 til enhver given side i portalen kan ses et diagnostisk output. Her vises dels den forbehandlede version af stylesheetet, dels alle dokumenter der er loadet via brugerskallens private fil-schemes. Dette kan være meget nyttigt hvis man skriver skabeloner der håndterer resultatet af een af de private scheme-funktioner.
Dette afsnit beskriver den tekniske opbygning af basisportalen tkl-test1. Det er generelt kun nødvendigt at gå igennem dette afsnit hvis du overvejer at ændre i basisportalens grænseflade, eller hvis du generelt er interesseret i mekanikken bag TKL.
Basisportalens grænseflade er realiseret i standard XHTML med minimal brug af grafiske elementer og almindelig anvendelse af CSS stylesheets. Dvs. at en del af portalens fremtræden kan finjusteres ved blot at justere det medfølgende CSS stylesheet. Mere omfattende justeringer af grænsefladen finder sted ved at ændre på de medfølgende .xsl-filer, og det kræver altså et vist kendskab til XSLT-standarden, og desuden til de ekstra-funktioner som brugerskallen stiller til rådighed (se ovenfor).
Denne fil, som findes i portalens rodkatalog (husk, at rodkataloget for en portal simpelt hen er det katalog som indeholder filen tkl.config), definerer den overordnede ramme for portalgrænsefladen. Interface.xsl svarer ikke til en bestemt dokumenttype, men bliver inkluderet af de andre stylesheets. Kigger man i filen, udgøres dens primære indhold af templaten "main-page". Denne template producerer selve den overordnede HTML (XHTML) struktur for siden. Inde i HTML-koden kaldes så forskellige andre templates for at producere det egentlige indhold af siden. Disse templates leveres så af det stylesheet som kalder main-page templaten.
Interface.xsl leverer selv default-versioner af de nævnte templates, mest for at minde programmøren om at erstatte dem med noget andet. Alt efter temperament kan man sammenligne fremgangsmåden omkring interface.xsl med objektorienteret programmering hvor hver dokumenttype nedarver et basis-layout fra interface.xsl, eller som en callback-baseret metode, hvor main-page "kalder tilbage" til det overordnede stylesheet.
Udover main-html definerer interface.xsl også skabelonerne insert-path, som laver en brødkrummesti fra dokumentets placering op til portalens rod, og menu, som konstruerer menuen der findes i venstre side (baseret på data fra index.tkl i portalens rod-katalog).
Der findes typisk kun eet dokument af typen "portal" i en given portal, og det er index.tkl i hovedkataloget. portal.xsl definerer indholdet af portalens forside. Men den er også et ganske typisk eksempel for et stylesheet for en dokumenttype, og det er værd at kigge på dens indhold i lidt flere detaljer end vi gør for typerne nedenfor.
Stylesheetet sparkes i gang af en template som matcher dokument-elementet – i dette tilfælde "/portal". Det eneste denne skabelon gør – og det er typisk – er at den kalder skaelonen main-page som er defineret i interface.xsl. Det er main-page der sidenhen sørger for at kalde de øvrige skabeloner i filen – main-news-content og main-body.
Main-news-content er hurtigt overstået, og er iøvrigt i tkl-test1 den samme for alle dokumenttyper (det behøvede den ikke at være, hvis man f.eks. ønskede at bruge højre-rammen til mere kontekst-afhængige ting under visse sider). Her kalder den en skabelon ved navn read-news som er defineret i news.xsl. Denne template læser kataloget "news" og finder de fire nyeste news-entries, og viser dem frem. Hvert nyheds-entry linker til den tilsvarende artikel på news-siden.
Skabelonen main-body laver det egentlige arbejde – den definerer som sagt hvad der kommer til at stå i hovedvinduet, i midten af skærmen. Her benytter den document()-funktionen og schemet "tkl-find for at finde oplysninger om alle emnegrupper under kataloget "links", to niveauer ned. Koden nedenunder – de to indlejrede for-each løkker – sørger for at vise overskrifterne for brugeren, med links ned til de relevante emnegrupper.
Forskellige typer af emne-hierarkier tager sig bedst ud ved forskellige præsentationsformer. Det kan således sagtens tænkes, at hvis du ønsker at benytte et væsentligt anderledes emnehierarki, så vil det kunne betale sig at ændre i fremgangsmåden der bliver benyttet her. I yderste konsekvens foretrækker du måske simpelt hen at styre det hele selv – i så fald kan du blot skrive almindelig XHTML-kode i skabelonen main-body.
Fremvisningsformatet subject.xsl er knyttet til filer af typen subject. Disse filer ligger som index.tkl i hvert katalog under "link"-kataloget og representerer metadata om de egentlige emnegrupper. Filen subject.xsl følger samme interne struktur som portal.xsl – en skabelon matcher dokument-elementet -- <subject>. Herfra kaldes main-page som producerer siden med hjælp fra "call-back"-funktionerne.
skabelonen main-body udfører to opgaver. Først undersøger den om der findes underkategorier – det gøres ved at kigge efter underkataloger med en index.tkl fil.
Herefter leder main-body efter ressourcer katalogiseret i denne emnegruppe. Det gøres ved at kigge efter filer i samme katalog der matcher masken link*.tkl.
Link-typen gør sig bemærket ved ikke at have en egen xsl-fil. Dette skyldes at portalbrugeren aldrig betragter link-filerne direkte – de bliver fremvist af subject.xsl når brugeren åbner et emnekatalog, og desuden af search.xsl når brugeren foretager en søgning.
Document-typen er tænkt som en generel arbejdshest – den kan bruges til at vedligeholde enhver type af struktureret hierarki af dokumenter.
Ser man i document.xsl kan man se hvorledes stylesheetet dels viser indholdet af det givne dokument, dels søger efter underkataloger med index.tkl filer. Hvis sådanne findes, bliver der lavet en liste med pegere til dem i bunden af det fremviste dokument.
I basisportalen er document.xsd/xsl ganske simple, de består blot af en titel, en forfatter, en beskrivelse, og en brødtekst (som i sig selv behandles som XHTML, så den kan rumme almindelig tekst med tags. Det er muligt i vidt omfang at tilpasse denne fil til bestemte applikationer – f.eks. kunne den vise illustrationer, overskrifter, kapitelinddelinger, etc.
Search.xsl udfører søgninger når brugeren trykker på "søg"-knappen i portalens top-menu. Den følger den sædvanlige sidestruktur, og igen er det skabelonen main-body der udfører det meste af det egentlige arbejde.
Øverst i skabelonen erklæres tre parametre, portpath, query, og start. Portpath er en "Indbygget" parameter der stilles til rådighed af brugerskallen. Den rummer den absolutte sti til roden af portalen – den skal bruges til senere at få fat i søge-serveren. Parametrene query og start kommer fra brugerens HTTP-førespørgsel.
Det første main-body gør (udover at udskrive en overskrift) er at kalde skabelonen rpn-wordlist (defineret længere nede), som tager brugerens søgning og udskifter mellemrum med AND-operatorer. Resultatet gemmes i variablen rpnquery.
Herefter testes om query faktisk var sat (hvis ikke, bliver der skrevet en formaning til brugeren), og så begynder arbejdet. Søgningen udføres ved hjælp af metoden tkl-search som stilles til rådighed af brugerskallen. Den bliver rettet imod en server med en UNIX-domain adresse under db/socket under portalens rodkatalog (se beskrivelsen af brugerskallens søgefunktion ovenfor).
Hvis søgningen gik godt vises antallet af fund. Herefter kaldes skabelonen previous-next (defineret længere nede) der laver pegerne frem og tilbage, afhængigt af positionen i svarsættet (start-parametren) og søgesættets størrelse.
Endelig bliver posterne vist, i en for-each løkke. Her checkes først om der er tale om interne dokumenter, eller link-dokumenter med eksterne URL'er. Linket, som enten er lokalt eller eksternt bliver anbragt i variablen url. Der skelnes også imellem om der er tale om en emnegruppe eller en anden type dokument – emnegrupper vises med en lille firkant foran i stedet for en trekant. Endelig vises titlen som et hyperlink til URLen efterfulgt af et evt. description-felt.
Skabelonen rpn-wordlist er et simpelt eksempel på en rekursiv skabelon. Såfremt den kaldes med et enkelt ord (uden mellemrum) returnerer den blot ordet selv. Men findes der et mellemrum, så returnerer den en AND-operator (husk at søgesproget er en prefix-notation [2]), efterfulgt af et rekursivt kald til skabelonen med resten af søgestrengen (alt hvad der kommer efter det første mellemrum. Og sådan bliver det ved, indtil der ikke er flere mellemrum og hele søgestrengen er oversat til PQF-sproget. For eksempel bliver søgestrengen
niels christian andersen
til søgeudtrykket
@and niels @and christian andersen
som på mere traditionelt boolesk betyder
niels AND
christian AND andersen
Skabelonen previous-next er godt nok længere, men nok også mere gennemskuelig. Den regner simpelt hen ud om der er behov for pegere frem eller tilbage i søgesættet, og returnerer dem efter behov.
Dokumenttypen news bliver, ligesom links, ikke vist af sit eget stylesheet. I stedet bliver news-dokumenter vist, enten af skabelonen read-news i news.xsl (som igen bliver inkluderet af de fleste andre stylesheets), eller af stylesheetet newspage.xsl, som ligger i news-kataloget. Newspage.xsl producerer den side man ser, når man beder om at se nyhederne i detaljer.
TKL er konstrueret til at dele sit dataindhold via The Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH). Den nuværende version understøtter tilstrækkelig meget af protokollen til at støtte sin rolle i DEF-samarbejdet, men det forventes at protokol-understøttelsen vil udvides med tiden. Pt. understøttes tjenesterne (verberne) Identify, ListMetadataFormats og ListRecords.
OAI-PMH muliggør brugen af flere forskellige udvekslingsformater, men kræver support for et simpelt Dublin-Core-baseret format kaldet oai_dc. Desuden benyttes i DEF-samarbejdet et format kaldet oai_def_portal, defineret ved schemaet
http://www.technomat.hu/def/oai_def_portal/1.0/oai_def_portal.xsd
TKL muliggør delingen af alle typer af dokumenter, ikke bare metadata for eksterne webresourcer. Generelt bliver et dokument tilbudt til udveksling hvis det findes i et katalog som er markeret med oai-exchange flaget (i en directory.tkl fil), og hvis der findes et passende konverteringsfilter. Filteret søges i kataloget schemas under portalens rod, og har et filnavn af formen:
schemanavn--metadataprefix.xsl
Hvor schemanavnet er navnet på rod-elementet i det givne dokument, og metadataprefix er det metadata-prefix som klienten (service provideren) har bedt om.
Basisportalen tkl-test1 rummer således en fil ved navn
tkl-test1/schemas/link--oai_dc.xsl
som definerer oversættelsen fra et link-dokument til oai_dc formatet.
Basis-URL'en for en TKL portal er simpelt hen URL'en til portalens hovedside. Hvis f.eks. en portal er installeret under
http://www.indexdata.dk/tkl/
så vil følgende forespørgsel levere en beskrivelse af portalen efter OAI-PMH:
http://www.indexdata.dk/tkl/?verb=Identify
Installationen af TKL selv består af ganske enkle ændringer af Apache's konfigurationsfil. Men før dette fungerer skal man sikre sig at visse valgfrie PHP moduler er installeret på maskinen. Proceduren for installationen af disse kan findes i filen doc/tkl-installation.html sammen med installationen. Den kan også læses online, f.eks. her:
http://www.indexdata.dk/lite/tklite/doc/tkl-installation.html
[1] Faktisk kan man også forestille sig at stylesheetet producerer andet XML – hvis man f.eks. ønsker at en TKL-baseret portal skal kunne indgå i en tre-lags arkitektur baseret på XML-protokoller.
[2] Jo, vi ved godt at rpn betyder at noget er en suffix-notation. Årsagerne til denne forvirring fortaber sig i historien.