Dokumentnamn Dokumenttyp Datum Dokumentmallar i praktiken Handledning 2009-08-13 Diarienr/Projektnr Upprättad av Godkänd av Version Magnus Österlund, Daniel Madsén 0.4 Dokumentmallar i praktiken, Nyps 1 (10)
Innehållsförteckning Revisionshistorik... 2 Allmänt... 3 Att skapa mallar i Word... 3 Vanliga taggar... 4 @@VALUE{{object.attribute}}... 4 @@ENUMERATION{{object, enum_template}}... 4 @@ENUMERATION{{object, lookup_specification, enum_template}}... 5 @@USER{{object.attribute, userattribute}}... 5 @@SHORTCODE_VALUE{{object.attribute, type, includecode=true}}... 6 @@VALUE{{current}}... 6 Formatering... 6 @@FORMAT{{TAG, numbergroups=true, nrofdecimals=2}}... 6 Att efterbehandla och verifiera mallar... 7 Radbrytningar... 7 Varningsmeddelande om header... 7 Bilder i dokumentmallar... 8 Formatmallsinformation i malltaggarna... 9 Revisionshistorik Författare Ändringsbeskrivning Version Datum Daniel Madsén Dokumentet är uppdaterat 0.4 2009-08-12 - Ändrad dokumentmall Magnus Österlund Ida Infront Dokumentet skapat 0.3 (1.4) 2007-04-13 2 (10)
Allmänt NYPS dokumenthantering bygger på att dokument i systemet skapas i html-format, utifrån dokumentmallar som också är i html-format. NYPS har dessutom ganska kraftfulla funktioner för att hämta information från systemet och automatiskt infoga den i de dokument som skapas. Dessa funktioner bygger på att man i dokumentmallarna infogar så kallade»taggar«som beskriver vilka data som ska hämtas, samt hur data ska formateras. Kombinationen av ett kraftfullt taggspråk, formatvalet html och det faktum att flertalet användare är hänvisade till Word för att skapa sina mallar har dock visat sig ge upphov till en del fallgropar. Det här dokumentet ska försöka peka ut dessa och beskriva hur man undviker att falla i dem (eller åtminstone hur man klättrar upp igen). Mycket grovt kan man säga att mallarna skapas i steg: 1. Formge själva dokumentet/mallen. Lägg in rubriker, standardtexter, tabeller, ramar, etc. Detta är normal Word-användning och ligger utanför vad det här dokumentet vill lära ut. 2. Lägg till taggar som hämtar data från NYPS. Beskrivs kort i avsnittet»att skapa mallar i Word«nedan. 3. Spara dokumentet som html. I Word: Arkiv/Spara som / välj Filformat 4. Efterbehandla dokumentmallen i en textredigerare, exempelvis Notepad, för att skapa korrekta referenser till bilder samt rätta eventuella fel som Word gett upphov till. Beskrivs i avsnittet»att efterbehandla och verifiera mallar«nedan. Att skapa mallar i Word Det här avsnittet är en kort sammanfattning av innehållet i dokumentet»design Mallhantering«som i detalj beskriver alla möjligheter att hämta data från NYPSsystemet till de dokument som skapas i systemet. Det dokumentet bör användas som referens och allra helst läsas igenom ordentligt. Ambitionen med det här avsnittet är att ge en introduktion så att du kan komma igång och med hjälp av Word skapa dokumentmallar för NYPS. En tagg ser ut såhär: @@NAMN{{parametrar}} Tagg-markering Namn Starttecken Parametrar Sluttecken Namnet är CONTACT, parametrarna är Kontakt kontrollant och ct_name. Första parametern anger vilken typ av kontaktobjekt värdet ska tas från, andra parametern anger vilket attribut som värdet ska tas ifrån. Malltaggarna är alltså ett sätt att hämta information från systemet och automatiskt infoga den informationen i ett dokument. Deras speciella utformning beror på att systemet analyserar mallen och letar efter taggar som ska behandlas av dokumentskaparfunktionen. Taggen måste alltså vara logiskt uppbyggd och följa standarden eftersom den ska tolkas maskinellt. 3 (10)
Vanliga taggar @@VALUE{{object.attribute}} Används för att ersätta taggen med ett värde från systemet. @@VALUE{{pro_prep.pro_approved_amount}} ger godkänt belopp från ett ärendebeslut för ett projektmedelsärende. @@ENUMERATION{{object, enum_template}} Används tillsammans med några speciella taggar för att visa flervärda attribut. object anger objekttyp, enum_template är en bit mall som ska upprepas för varje värde. Används typiskt för att generera tabeller. Exempel: @@ENUMERATION{{rub_prep_cost, @@ENUMERATION_VALUE{{rub_cost_type}} @@ENUMERATION_VALUE{{rub_approved_support_basis}} kr }} Eftersom Word radbryter kan det vara lite svårt att se vad som händer, men i mallen så är det endast ett mellanslag mellan de två @@ENUMERATION_VALUE-taggarna. Beskrivet i ord gör mallen ovan följande: Objektet är rub_prep_cost. Det är kostnadstabellen i Nyps. Alltså: För varje kostnadsrad, gör följande: @@ENUMERATION_VALUE{{rub_cost_type}} ersätts med kostnadstyp för aktuell rad @@ENUMERATION_VALUE{{rub_approved_support_basis}} ersätts med godkänt stödunderlag för aktuell rad. tillslut skrivs kr ut en gång per kostnadsrad. Ett ärende med två godkända kostnader, 15 000 på Anläggningar och 20 000 på Personal skulle alltså ge följande två rader: Anläggningar 15000 kr Personal 20000 kr Det här kallas i programspråk för en loop, därav namngivningen av @@GENERATION_LOOP som fungerar på liknande sätt som ovan, fast över generationer (flera ärendebeslut eller utbetalningsbeslut). 4 (10)
@@ENUMERATION{{object, lookup_specification, enum_template}} I grunden utför denna tagg samma sak som enumeration taggen ovan den används för att visa flervärda attribute. Som i den andra enumeration taggen anger object vilken objekttyp som ska användas och enum_template den del av mallen som ska upprepas för varje värde. Skillnaden är att denna tagg tillåter att det i lookup_specification specificeras vilka värden som ska visas, exempelvis vilka kostnandstyper som ska visas ur en kostnadstabell. lookup_specification består av två delar, dels en del som specificerar vilket attribut som kontrollen ska ske mot och dels en lista med värden. För att göra det enkelt att visa bara något värde eller nästan alla värden specificeras det om listan med värden innehåller godkända eller icke godkända värden. Detta gör att man enkelt kan visa bara ett värde, eller alla utom ett värde. Den syntax som används av lookup_specification är följande: TYPE <attribut_namn> LOOKUP <värde_1>;;<värde_1> END (visar endast enum_tempalte om objektets attribut <attribut_namn> har värdet <värde_1> eller <värde_2>) eller TYPE <attribut_namn> NOT <värde_1>;;<värde_1> END (visar endast enum_tempalte om objektets attribut <attribut_namn> inte har värdet <värde_1> eller <värde_2>) Observera att man inte kan blanda både LOOKUP och NOT. Exempel: Ett ärende har tre godkända kostnader, 15 000 på Anläggningar, 20 000 på Personal och 30 000 på Övrigt. @@ENUMERATION{{rub_prep_cost, TYPE rub_cost_type LOOKUP Anläggning;;Övrigt END, @@ENUMERATION_VALUE{{rub_cost_type}} @@ENUMERATION_VALUE{{rub_approved_support_basis}} kr }} Resultat: Anläggningar 15 000 kr Övrigt 30 000kr @@ENUMERATION{{rub_prep_cost, TYPE rub_cost_type NOT Övrigt END, @@ENUMERATION_VALUE{{rub_cost_type}} @@ENUMERATION_VALUE{{rub_approved_support_basis}} kr }} Resultat: Anläggning 15 000 kr Personal 20 000kr @@USER{{object.attribute, userattribute}} En tagg för att hämta användarinformation. Information om användare lagras i ett system utanför NYPS, men kan hämtas in. Exempel: @@USER{{case.ca_case_manager, telephonenumber}} I case.ca_case_manager lagras en kortkod för användaren (ärendehanteraren). Den kortkoden används sedan för att slå upp telephonenumber i det externa systemet (LDAP). @@USER{{case.ca_case_manager,cn}} ger det fullständiga namnet på ärendehanteraren. 5 (10)
@@SHORTCODE_VALUE{{object.attribute, type, includecode=true}} Den här taggen används för att hämta beskrivningen av en kortkod, alltså den textbeskrivning som är kopplad till en kortkod. Den första parametern anger vilket kortkods attribut som ska hämtas. Kortkoden för Län-Kommun-Församling är speciell och för att hämta ut en del av den (Län, Kommun eller Församling) används type parametern. Type parametern behövs bara anges om det är ett Län-Kommun-Församling attribut. Genom att ange LKF_COUNTY som type hämtas länet ut, LKF_MUNICIPAITY för kommunen och LKF_PARISH för församlingen. Anges includecode=true kommer även kortkoden att hämtas och läggas till kortkodsbeskrivningen. @@VALUE{{current}} Ett specialfall av den generella @@VALUE-taggen. Den här taggen ersätts med dagens datum. Formatering Namn-delen av taggen kan användas för att styra hur värdet som Nyps ersätter taggen med kommer presenteras. Står det CONTACT, och värdet på ct_name för det aktuella ärendet är tillexempel nisse, så kommer det i det genererade dokumentet stå NISSE. Står det Contact, blir värdet Nisse och slutligen contact skulle ge nisse, oavsett hur ct_name är angivet i systemet. @@FORMAT{{TAG, numbergroups=true, nrofdecimals=2}} @@FORMAT-taggen kan användas för att styra formateringen på värden som ska presenteras. Man kan ange en eller bägge av parametrarna. @@FORMAT kan användas med taggarna @@VALUE, @@ENUMERATION_VALUE, @@FUNCTION, @@ENUMERATION_FUNCTION och @@FORECAST. I exemplet med @@ENUMERATION_VALUE ovan visades att en rad skrevs ut som t.ex. Anläggningar 15000 kr Det normala är ju att presentera belopp med tusentalsseparator, och det kan man göra med @@FORMAT: Omslut @@ENUMERATION_VALUE såhär: @@FORMAT{{@@ENUMERATION_VALUE{{rub_approved_support_basis}}, numbergroups=true}} och beloppet kommer skrivas som 15 000 istället. På samma sätt kan nrofdecimals styra antalet decimaler. @@FORMAT{{@@VALUE{{case.ca_approved_amount}}, nrofdecimals=2}} presenterar godkänt belopp på ärendet med två decimaler. Bägge parametrarna kan användas samtidigt och ordningen spelar ingen roll. 6 (10)
Att efterbehandla och verifiera mallar Tyvärr är inte Word speciellt bra på att hantera html (som är det valda dokumentformatet), och den stora stötestenen är att dokument sparade i Word som html ofta innehåller extra information som inte syns när man redigerar dokumentet. En grundregel som är bra att minnas är att om man tittar i ett rent textverktyg (Wordpad eller Notepad) så ska det mellan @@ och }} i en tagg inte finnas något som inte mallskaparen skrivit dit! Radbrytningar När man sparar en filtrerad webbsida i Word så skapar ibland Word en radbrytning mitt i en Nypstagg. Det gör att dokumentmallshanteringen inte kan tolka taggen. Det här uppträder ofta då taggen ska ha ett mellanslag i sig. Exempel: @@CONTACT{{Kontakt - kontrollant,ct_name}} Det måste, tillexempel med valfritt textredigeringsverktyg såsom Notepad eller Wordpad, korrigeras till: @@CONTACT{{Kontakt - kontrollant,ct_name}} innan mallen importeras till NYPS. Varningsmeddelande om header @page {mso-footnote-separator:url("./ris%20beslutsbrev%20slututbetalningfiler/header.htm") fs; mso-footnote-continuationseparator:url("./ris%20beslutsbrev%20slututbetalning-filer/header.htm") fcs; mso-endnote-separator:url("./ris%20beslutsbrev%20slututbetalningfiler/header.htm") es; mso-endnote-continuationseparator:url("./ris%20beslutsbrev%20slututbetalning-filer/header.htm") ecs; mso-facing-pages:yes;} Ovanstående utdrag ur en skapad html-mall är referenser till en separat fil som Word skapar som heter header.htm. Den filen importeras inte, och innehåller ingen relevant information. Den här texten ska därför tas bort ur mallen, annars visas ett felmeddelande när man skapar ett dokument med hjälp av mallen. 7 (10)
Bilder i dokumentmallar Dokumentmallformatet är html. Det innebär att en bild som syns i ett html-dokument är en länk till antingen a) en fil på hårddisken eller b) en länk till en bild som finns på en webbserver. Bilden finns inte fysiskt lagrad i dokumentet. Bilderna ska alltså läggas någonstans publikt åtkomligt, eftersom dokumenten ska mailas till de stödsökande/aktörerna. Varje organisation som använder NYPS kommer därför att publicera en katalog med de bilder som är unika för respektive länsstyrelse/organisation. Word har inte något bra stöd för att hantera länkade bilder (och har tyvärr inte bra stöd för html alls). Det förmodligen smidigaste arbetssättet utan att använda en dedikerad html-redigerare är att använda TEMPORÄRA bilder som platshållare där bilden i dokumentet ska sitta, spara dokumentet i Word som en filtrerad webbsida och sen manuellt i till exempel Wordpad eller Notepad ersätta de temporära bildlänkarna som Word skapar med riktiga länkar till den publika bildkatalogen. Exempel: Word skapar en bildlänk som ser ut ungefär såhär: <img [...] src="dok1-filer/image001.jpg"> ([...] står här för ett antal attribut som man behöver röra) Länken refererar till en bild, image001.jpg, som finns på hårddisken. Den får ersättas manuellt med något i stil med: <img [...] src="http://www.nutek.se/nyps-bilder/logotype_lst-bd.jpg"> Placeringen av bilden och bildnamnet är här bara ett exempel: Word har även skapat lite VML-information (VML är ett språk för enklare grafikhantering) som inte är nödvändigt (eller ens önskvärt). I exemplet ovan markeras även den delen. Inleds med <! [if gte vml 1]> och avslutas med <[!endif]>. Själva bildlänken finns inuti det här området och inleds med <img src. 8 (10)
Ovan har allt det gamla ersatts med en enkel länk till en bild, som alltså måste finnas upplagd (och åtkomlig från både innanför länsstyrelsens brandvägg och dels även publikt). Formatmallsinformation i malltaggarna Word har en tendens att stoppa in överflödig information om vilket typsnitt och stil som ska användas. Om sådan information råkar hamna inuti en tagg, som ovan, så fungerar inte taggen. Man måste därför se till att taggarna hänger ihop. Det här är i grunden samma problem som radbrytningarna som nämndes tidigare. Notera att exemplet ovan innehåller en tagg separerad i TRE delar. Den andra delen kommer efter markeringen, och den tredje är efter ett liknande stycke som det som är markerat. Det måste också tas bort. Nedan en bild på hur det ser ut då de två formatinformationsblocken tagits bort. 9 (10)
Till sist två bilder som visar hela taggen markerad före och efter redigering. Att söka efter @@ är ett bra knep för att hitta taggar för granskning. 10 (10)