*Developer guidelines and naming conventions — draft*

 Contents- [1. Architecture](#1-architecture)

- [2. Security](#2-security)
- [3. Field names](#3-field-names)

- [Type prefixes](#type-prefixes)
- [Auto-enter markers](#auto-enter-markers)

- [Keys](#keys)
- [Groups and separators](#groups-and-separators)

- [Display names](#display-names)
- [To-do marker](#to-do-marker)

- [4. Scripts](#4-scripts)
- [Numbering and groups](#numbering-and-groups)

- [Suffixes](#suffixes)
- [Parameters](#parameters)

- [Navigation](#navigation)
- [5. Table occurrences](#5-table-occurrences)

- [6. Layouts](#6-layouts)
- [7. Plug-ins and add-ons](#7-plug-ins-and-add-ons)

- [8. Custom functions](#8-custom-functions)

 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](http://filemakerkonsulterna.se/sv/kvp-26-documentation) has a [glossary](http://filemakerkonsulterna.se/sv/kvp-26-documentation#glossary) of the Swedish terms.

## 1. Architecture

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

 | File | Role | Contents |
|---|---|---|
| **KVP 26 ED** | Front end | Layouts, scripts, value lists and navigation. Its only tables are `Globaler` (global fields) and the two tables of the calendar add-on. |
| **KVP 26 ED Database** | Data | All business data in 39 tables, for example `Företag`, `Person`, `Händelser`, `Dokument`, `Order`, `Orderrader`, `Faktura`, `Fakturarader`, `Projekt`, `Artikel`, `Märke`, `Märkning`, `Nav` and `KVP` (settings). |
| **KVP 26 ED Documents** | Documents | Stored files (`Files`) and icons (`Icon`). |

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](http://filemakerkonsulterna.se/sv/kvp-26-documentation#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

 | Data type | Ordinary | Global | Calculation | Global calculation |
|---|---|---|---|---|
| Text | `tx` | `gtx` | `ctx` | `gctx` |
| Number | `n` | `gn` | `cn` | `gcn` |
| Date | `d` | `gd` | `cd` | `gcd` |
| Timestamp | `ts` | `gts` | `cts` | `gcts` |
| Time | `ti` | `gt` | `cti` | `gcti` |
| Container | `c` | `gb` | `cc` | `gcc` |

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 | Heading | Contents |
|---|---|---|
| 1 | **Internt** (Internal) | Start-up, closing, window handling, plug-in registration. |
| 2 | **Förflyttning** (Navigation) | `2.1 Navigering` and its sub-scripts, the history (back and forward). |
| 3 | **Gå till rel** (Go to related) | Moving between related records, for example from a portal row to the record. |
| 4 | **Poster** (Records) | Creating, deleting and copying records; guides that create records. |
| 5 | **Fält &amp; Beräkningar** (Fields and calculations) | Setting and inserting values, merge fields, notes, mass tagging. |
| 6 | **Sök** (Find) | Find scripts for each module. |
| 7 | **Sortera** (Sort) | Sort scripts for each module. |
| 8 | **Utskrifter** (Printing) | Printing and sending, with shared helper scripts in 8.0. |
| 9 | **Imp &amp; Exp** (Import and export) | Export of addresses, the import guide, sending by email. |
| 10 | **Övrigt** (Other) | Opening URLs, attachments to letter templates, and the collected functions below. |

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

 | Suffix | Meaning |
|---|---|
| `[Start]` | Entry point, started by the user. |
| `[Sub]` | Sub-script, only called by other scripts. |
| `[Knapp]` / `[Button]` | Run from a button. |
| `[MP]` | Takes a script parameter (*manusparameter*). |
| `[Remote]` | Called from another file. |

### 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**:

 | Suffix | View |
|---|---|
| `_Inmatning` | Entry view (form) for one record. |
| `_Lista` | List view. |
| `_Rapporter` | Printing and reports for the module. |
| `Kort` | Card window, for example `Händelser Kort`. |
| `_Utskrift` | Print layout. |

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

 | Function | File | Purpose |
|---|---|---|
| `SparaData`, `HämtaData`, `BytData` | Front end, data | Name–value pairs in script parameters. |
| `ChangeFilenamne.FMP.to.OS` | Front end | Converts a FileMaker path to the operating system's format. |
| `_BehörighetsnivåTillUppsättning` | Front end | Maps a KVP privilege level to a privilege set. |
| `_KontoFelmeddelande` | Front end | Turns an account error code into a message. |
| `FCCalendarConfig`, `FCCalendarDataURL` | Front end | Calendar add-on. |
| `TagbortFormat` | Data | Removes text formatting (styles, fonts and colours), for example from pasted text. |

 ![]()