FileMaker Development Conventions
Med årene er FileMaker blevet et avanceret udviklerværktøj. Det stiller krav til præcision og dokumentation. Hvis flere udviklere skal arbejde sammen, eller hvis en udvikler skal overtage, hvor en anden slap, er det vigtigt, at løsningen er til at gennemskue. En stringent, konsekvent og logisk anvendelse af et passende sæt konventioner kan hjælpe med dette. FileMaker udgav i 2005 et dokument, der indeholder forslag til navngivningskonventioner:
FileMaker Development Conventions
Dette dokument (herefter forkortet FDC) er en reference. Man kan følge anbefalingerne, eller de kan fraviges, hvor det er fordelagtigt. Enhver udvikler bør gøre dette, så designbeslutninger dokumenteres.
Denne tekst er blevet til i samarbejde mellem Jens Rasmussen og André Just Vedgren. Oprettet 15. marts 2006, revideres løbende, senest i marts 2009.
Table of Contents
1 FILES
2 TABLES
3 FIELDS
4 TABLE OCCURRENCES
5 LAYOUTS
6 CUSTOM FUNCTIONS
7 SCRIPTS
8 CALCULATIONS
9 VALUE LISTS
10 ACCOUNTS & SECURITY
Indledning
Om navngivning gælder generelt, at FDC følges i alle kapitler. Tilladte tegn er således a-z (store og små bogstaver) samt cifrene 0-9. Danske tegn (æøåÆØÅ) omskrives til ae, oe, aa.
Endvidere underscore (_), enkelt eller dobbelt, som bruges til at adskille ord. Mellemrum er generelt ikke tilladt, medmindre det udtrykkeligt specificeres.
Navne må generelt ikke starte med et tal. Generelt foretrækkes "UpperCamelCase".
-1-
Navngivning af mapper og databasefiler
Mappenavne er ikke nævnt i FDC. Det er dog relevant, dels når databasen oprettes, dels når den ligger på FileMaker Server.
1.3, punkt 4:
Versionering af løsninger skal foretages på mappeniveau. Filnavnet skal således ikke ændres for hver version.
1.3, punkt 5 og 8:Filer skal indeholde netop 1 punktum, nemlig det der adskiller filnavn fra extension. Filnavne slutter på .fp7.
1.3, punkt 10:Selve navnet bør indeholde kundens navn og løsningens formål, gerne i forkortet form.
Eksempel:FBI_Bookingsystem.fp7.
TukanWine_salg.fp7
TJEKLISTE FOR NY DATABASEFIL, FØR DEN LÆGGES PÅ SERVER:
Ny database, opret to scripts ved navn START og SLUT.File Options:
Under Open/Close skal der ikke være kryds i:
- Log in using
eller
- Switch to layout
men der skal vælges åbne- og lukke-scripts, se under Scripts for navngivning af disse.
Stavekontrol afhænger af ordbog installeret hos brugeren, så denne kan med fordel slås fra:
Under Text, Data Entry skal vælges "Always use current system settings":
Import af grafik vil normalt være slået fra, men det kan slås til efter behov. Kun relevant på Mac OS X.
-2-
Navngivning af tabeller
2.3.8. (side 16):
Basetabeller skal navngives konsistent. Er der tale om noget, vi kan kalde en entitet eller en klasse, benævnes denne blot i ental.
Eksempel:
Kunde
Booking
Ordre
Faktura
2.3, punkt 3:
Der bruges ental i tabelnavne.
Join-tabeller navngives, hvis ikke andet falder lige for, blot efter de to tabeller, de knytter sammen, i alfabetisk rækkefølge.
Eksempel:
KomikerProdukt.
Mod-eksempel:
Ordrelinje - her tilsiger praksis, at tabellen hedder således, og ikke OrdreVare.
En undtagelse fra den generelle tabelnotation er tabellen "_", som er tom, se i øvrigt under TO-afsnittet. Underscore-tabellen er der kun for at basere separator-layouts på en tom tabel / TO.
Tabeller, der lægges brugerdata i, navngives simplest muligt.
Visse tabeller tilføjes et præfiks med z, for at havne i bunden af listen:
zi__ for interne tabeller til styring af bruger- og system-indstillinger. En ren tabel med globale felter ville også havne her.
Data, der er givet udefra, og dermed er udenfor databasebrugerens kontrol, gives også et præfiks:
zx__ for eksempel til postnummertabel, landetabel m.v.
-3-
Navngivning af felter
Felter falder i tre kategorier: brugerfelter, nøglefelter, udviklerfelter.
Brugerfelter (kap. 3.3.1) har naturlig navngivning, dvs. uden præfiks eller suffiks.
Nøglefelter har præfiks, se nedenfor.
Udviklerfelter har præfiks og suffiks, se nedenfor.
I alle tabeller skal flg. felter oprettes: Oprettet (kontonavn + timestamp), Rettet (kontonavn + timestamp), ID.
Repeating fields skal så vidt muligt undgås. Ingen særlige konventioner defineres til disse.
Der bruges ental i feltnavne.
Da 'Global Storage' nu er en option på alle felter, skal det fremgå af feltnavnet, om det er et 'lokalt' eller 'globalt' felt.
3.3.1, punkt 6:
For felter anbefales en navngivning passende til alfabetisk sortering, som det også er nævnt for tabeller.
3.3.1, punkt 8:
Gruppering af felter tilstræbes.
Eksempel:
TelefonDirekte
TelefonMobil
Uge.
3.3.1, punkt 9:
Om et felt er bruger- eller udvikler-felt, vil afhænge af, om det skal med i en eksport foretaget af brugeren, og om det forekommer på layouts. Hvis vi er i tvivl, vil det være et udvikler-felt.
3.3.2, punkt 6:
Primærnøgler navngives med "__kp" i starten.
Eksempel:
__kpln__KundeID
Fremmednøgler navngives med "_kf" i starten.
Eksempel:
_kfln__KundeID
3.3.3.6.
Udvikler-felter samt felter, der bruges i alle tabeller, skal ligge sidst i den albabetiske rækkefølge. Iflg. FDC navngives de som vist.
Eksempel:
zz__OprettetKonto__lxt
zz__OprettetTidsstempel__lxm
zz__RettetKonto__lxt
zz__RettetTidsstempel__lxm
-4-
Navngivning af TO'er
I dialogboksen for Manage Database hedder det Relationships, men selve "trådene" kan ikke navngives. Det kan derimod "boksene", altså tabel-forekomsterne, TO'erne.
I valget mellem metoderne FSG, FTOG, HTOG foretrækkes HTOG, også kaldet anker-bøje-metoden.
Navngivningen er dog med visse modifikationer.
HTOG medfører, at et layout altid er forankret i TO'en længst til venstre i gruppen (TOG'en).
TO'er skal have navnet på basetabellen som en del af deres navn. TO-navne bliver længere, jo længere til højre de befinder sig.
4.4.
Her afviger vi lidt:
"_" skal bruges som præfiks til enhver Primary Table Occurrence.
Dermed kommer PTO'erne først i den alfabetiske rækkefølge.
Eksempel:
_Adresse
_Kunde
Alt dette kan virke lidt teoretisk. Men efter at have taget anker-bøje-metoden i brug, har jeg sparet megen tid og øget overskueligheden.
Her ses et eksempel på skift fra gammel til ny fremgangsmåde.
-5-
Navngivning af layouts
Layouts falder i to grupper: Udvikler/system-layouts, som brugeren aldrig ser samt brugernes layouts.
PTO-layouts navngives med basetabellens navn præfikset med _
Eksempel:
_Adresse
_Kunde.
Dermed sorteres de først. Basis-layouts skjules for brugeren dvs. de vises ikke i layoutrullemenuen.
Brugerlayouts sættes altid til udelukkende en visning: Form eller List. Table er som regel ikke relevant pga. manglende mulighed for tilpasning af layout, knapper etc. Brugerlayouts navngives parallelt med TO'erne i Anker-Bøje-metoden: Præfiks er trebogstavsforkortelsen fra TOG'en, herefter følger et _F for Form eller _L for list og endelig følger selve layoutnavnet.
Er der tale om et søgelayout sættes suffikset FIND på.
Udskriftslayouts får suffikset PRINT.
Hver gruppe af Layouts adskilles med vandrette linjer skabt af et layout navngivet - og baseret på den tomme "_"-tabel.
-6-
Navngivning af Custom Functions
Brugerdefinerede funktioner navngives, så de minder mest muligt om de indbyggede funktioner. Vi afviger her fra konventionerne, idet der ikke anvendes suffiks: Hverken tabeller eller felter har i deres navn angivet, hvad de er for nogle, så der er næppe heller grund til at gøre dette for CF'er (som ikke har noget dansk navn).
Nyttige steder at søge efter funktioner:
www.fmfunctions.com
og
www.briandunning.com
-7-
Navngivning af scripts
Scriptnavn({parameter 1, parameter 2, ...}): {Returværdi 1, returværdi 2, ...}
Hvis der ikke er parametre (script parameter), efterlades parentesen tom. Er der ingen returværdier (exit script result) skrives der ikke noget efter kolonnet. Parametre adskilles med linjeskift hvilket gør det let at finde de enkelte parametre med GetValue-funktionen.
Gruppering: Scripts grupperes funktionelt med generelle scipts først, herefter scripts bundet til knapper grupperet efter TOG'er i anker-bøje-metoden.
På trods af, at scripts kan kaldes udefra, vil vi generelt tillade alle bogstaver samt mellemrum i selve script-navnet .
Enhver løsning skal som minimum indeholde et start- og et slut-script navngivet START og SLUT som kaldes ved hhv. login og close.
Scripts bundet til knapper navngives med den TO, knappen findes på, dvs. TBF_Scriptnavn. Scripts, der kan kaldes direkte af brugeren, kan vise dialogbokse og dermed styres af brugervalg.
Scriptet skal efterlade databasen på samme layout, faneblad og post som før kald med mindre scriptets formål netop er at skifte til et andet layout, finde poster etc.
Hvis der benyttes fastkodede værdier, der ikke blot er indstillinger, der kan ændres af bruger eller er synlige for disse, angives disse til sidst i kommentarblokken.
Script-parametre overføres med det samme til lokale variable af samme navn og konverteres eksplicit til den ønskede datatype vha. GetAs…-funktionen, fx GetAsDate().
Scripts starter altid med følgende kommentarer - hver enkelt i sin egen Comment-linje:
Beskrivelse
ÅÅÅÅ-MM-DD INT: Versionsnoter
...
Ind:
1. Parameter 1
...
Ud:
1. Uddata 1
...
Afhængigheder
..
{Fastkodede værdier}
..
Eksempel:
===
KSD_Omsaetning(KundeID, DatoStart, DatoSlut): Omsaetning
#Gennemløb alle fundne kunder og opgør omsætning i periode
#2006-06-01 JR: Oprettet
#2006-06-01 AJV: Fejl i opgørelse rettet - kreditnotaer blev ikke medregnet
#Ind:
#1. KundeID
#2. DatoStart
#3. DatoSlut
#Ud:
#1. Kundens omsætning i perioden
#Afhængigheder:
#- Kaldes fra Kunde i browse mode med de relevante kunder fundet
#Fastkodede værdier
#- Regnskabsår løber fra 1. januar til 31. december
#
Set Variable [$kundeID; Value:GetAsNumber(GetValue(Get(ScriptParameter); 1))]
Set Variable [$DatoStart; Value:GetAsDate(GetValue(Get(ScriptParameter); 2))]
Set Variable [$DatoSlut; Value:GetAsDate(GetValue(Get(ScriptParameter); 3))]
#
Exit Script [$Omsaetning]
Om datatyper skal uddrages som vist, kan man diskutere. Men overvej altid datatype og gyldige værdier.
-8-
Kalkulationer
Formatet hjælper med at afkode, hvilke funktioner, der er indlejret. Som hovedregel indrykkes med enkelt mellemrum.
Se eksempler
-9-
Navngivning af værdilister
Værdilister er enten statiske eller baseret på tabeller. Hvis de er baseret på tabeller kan de enten være baseret på alle poster eller relaterede poster.
Statiske værdilister og værdilister baseret på én bestemt tabel præfikses med _. Da relaterede værdilister typisk benyttes i en bestemt TOG præfikses de med denne, fx KUN_Leveringsadresser.
Eksempel:
_Bool__c - dette er en værdiliste, der bør findes i alle databaser, da den bruges til tjekbokse, hvor der enten er kryds eller ej. Den har én værdi: 1.
KUN_KundeID__d
-10-
Navngivning af konti, grupper, privilegiesæt
External Server Authentication
Kan bruges både ved Open Directory, typisk Apple-servere og Active Directory på Windows.Eksemplet herunder beskriver Mac OS X Server
I Workgroup Manager oprettes gruppen
fm_bruger
som gøres til medlem af den primære arbejdsgruppe.
Indstil FM-server til "FileMaker and external server accounts"
I stedet for individuelle brugere i FileMaker kan der nu oprettes en gruppe, som hedder fm_bruger:
