Developer guidelines and naming conventions — draft

This document describes how KVP 26 is built, and the rules a developer follows when changing it. Names in the solution are in Swedish and are quoted exactly as they appear in FileMaker. The User documentation has a glossary of the Swedish terms.

1. Architecture

KVP 26 uses the separation model with three files, all hosted on FileMaker Server:

External data sources:

• The front end reaches the data through KVP 26 databases and the documents through KVP26_Dokument. Both use relative file: paths, so the solution works wherever the three files are hosted together.
• The data file and the documents file point back to the front end (KVP 26 and KVP 26 ED), so that a user who opens one of them directly is sent to the front end.

Start-up:

• The front end runs 1.2 Vid Start. It checks the account (Konto – efter inloggning [Sub]), sets the global filters and dates, registers the MBS plug-in (1.8 Kontrollera och registrera pluggar) and opens the start menu.
• The data file runs Start, which hands over to the front end.

2. Security

Security is described for users in the user documentation, under Users and privileges. The technical points:

• Every user has an account in each of the three files, with the same name, password and privilege set: Kundutvecklare, Superuser, Användare or Titta. The owner's Admin account has [Full Access].
• The account scripts keep the three files in step. Konto – alla filer [Sub] runs Konto – utför [Sub] in the data file, the documents file and the front end, in that order, and rolls back if a step fails.
• Scripts that run with full access check the caller's privileges with Get ( AccountPrivilegeSetName ) and Get ( AccountExtendedPrivileges ), which return the real account even inside a full-access script.
• The extended privileges AdmLosen (administer users) and BytLosen (change one's own password) control the account functions.
• File Access protection is on in all three files, and the files are authorised for one another only.
• Passwords exist only in script variables, never in fields or logs.

3. Field names

Every field name carries a prefix that tells the field's storage and data type. The data type decides the prefix, never an older name.

Type prefixes

Time and container are deliberately different from the other rows: a global time field is gt, but a calculated one is cti; a global container is gb, but an ordinary one is c.

Summary fields start with stat followed by a capital letter, for example statSummaInbetalt.

Auto-enter markers

An ordinary field with an auto-enter lookup or calculation says so right after the type prefix: al for a lookup and ac for a calculation. Examples: txalBenämning and txacInnehåll. Serial numbers, variables and constants get no marker.

Keys

• Primary key: IDP_<own table>, a number with an auto-enter serial number. Example: IDP_Företag.
• Foreign key: IDF_<target table>. Example: IDF_Projekt.
• Several keys to the same table get a suffix taken from their role, never a number: IDF_Person.Best and IDF_Person.Lev. Pairs are kept symmetrical.
• A match field is not a key unless its name contains "ID". Artikel::txArtikelnummer, for example, is a natural key.
• ID, ID1 … ID5 are constant fields for relationships and are left as they are.

Groups and separators

A functional group prefix is kept after the type prefix and marker, without its underscore: txalBest_Adress. Global fields have no underscores. Square brackets are written as a dot, so that the name can be used without quotes in a calculation: cnStatSum obet.portal1.

Display names

Every prefixed field has a FileMaker 26 display name equal to its name without the prefix. Users see Bankgiro where the schema says gtxBankgiro. Keys keep their full name as the display name.

To-do marker

A name ending in ## is the developer's own marker for something to come back to. It is never removed during a rename or a clean-up.

4. Scripts

Numbering and groups

Scripts are numbered group.subgroup.script, and each group starts with a heading script. The main groups are:

Group 10 also holds functions that are kept together, with their original numbers, under their own sub-headings:

• 10.3 Lösenord och bilagor (Passwords and attachments): the password buttons on the person card and email attachments.
• 10.4 Importguiden (Import guide): creating companies and persons from imported rows.
• 10.5 Importguiden: Fält och beräkningar (Import guide: fields and calculations): choosing matches and copying imported values field by field.
• 10.6 Diverse (Miscellaneous): mass email, the event dialog, saved event selections, the relationship guide and the confirmation emails.

Three groups are not numbered on purpose:

• Konto – (Account): the account scripts. Their names describe what they do, for example Konto – byt eget lösenord [Start].
• FCCalendar: Claris's calendar add-on, in its own folder, unchanged.
• The script Avsluta (Quit) is shown in the Scripts menu.

Suffixes

Parameters

Scripts pass several values in one parameter as name–value pairs, built and read with the custom functions SparaData ( name ; value ) and HämtaData ( parameter ; name ). BytData replaces a value in such a list. Example:

SparaData ( "PeID" ; Person::IDP_Person ) & SparaData ( "Ursprung" ; "Person" )

Navigation

All moves between modules go through 2.1 Navigering with a navigation code as parameter, for example "2:2". The codes are kept as records in the table Nav:

• txNavCode: the code;
• txNavLayout: the layout to go to;
• txNavScript: a sub-script to run after the move;
• txNavReturn: whether to return to the original layout.

2.1.2 _record_NavHistory records each move, so that the yellow back and forward buttons work.

Important: layout names are stored as data in Nav::txNavLayout. Renaming a layout breaks navigation until the name in Nav is changed as well.

5. Table occurrences

Table occurrences in the front end are named anchor_target_purpose:

• Anchor: the occurrence the relationship starts from. Example: Företag.
• Target: the table the occurrence shows. Example: Händelser.
• Purpose or key: what makes the relationship special. Examples: Företag_Händelser_FöID and Projekt_Händelser_filter.

A dot qualifies the relationship further, often by the field it matches on: Import_Foretag.ctxForetag.

Short forms are used in long chains: Dok_ (Dokument), Imp_ (Import), Pers_ (Person), Före_ (Företag).

Two families are generated by pattern and belong together:

• Agenda_Händelser_DagN_HH_HH: one occurrence per day and hour in the week view of the agenda, anchored at Agenda_Vecka.
• Översiktpersons_Händelser_HH_HH: one occurrence per hour in the staff overview.

Occurrences used only to create records through a relationship end in _skapa or _Skapa, for example Person_Märke_Skapa.

6. Layouts

Layouts are grouped in folders by module: Meny, Koncern, Företag, Person, Händelser, Projekt, Kalender, Order, Dokument, Faktura and Artikel. In addition:

• Dev holds developer and working layouts. They are hidden from the Layouts menu.
• System holds technical layouts.
• FCCalendar Addon holds the calendar add-on's layouts.
• Meny Start, the start menu, is the first layout in the list, outside the folders.

Layout names are built as module_view:

Print and report layouts are named after what they print, for example Faktura Bokf underlag Fakturor. Only end-user layouts are shown in the Layouts menu. All layouts in the front end use the KVP26 theme.

7. Plug-ins and add-ons

• MBS plug-in (MonkeyBread Software), for email with attachments, file dialogs and cURL. 1.8 Kontrollera och registrera pluggar checks at start-up that the plug-in is installed and registered. If it is missing, the script installs it from a container field in the settings (KVP::cMBS_Mac and KVP::cMBS_Win).
• FileMaker Calendar add-on (Claris), for the calendar views. Its settings are stored in FCCalendarAddon::ConfigStore and name the fields of Händelser and the event card Kalender_Händelser Kort. The add-on fetches events with Execute FileMaker Data API on that card, and the Data API returns only fields that are on the layout. Every field the configuration names must therefore stay on Kalender_Händelser Kort, including the primary key Händelser::IDP_Händelser. The key is placed outside the visible area and hidden with "Hide when: 1".

8. Custom functions