app-model.json

The application model of a database: title, icon, start form, ribbon, language of the components, the user interface of each mode, the modes each connection profile may run in, and what an administrator may adjust in operation. WklApplication keeps it in the table USysWklApp of the database; the build tool reads it from the file named by appModel in access-app.json.

Signature

{
  "version": 1,
  "title": "Kunden",
  "icon": "kunden.ico",
  "iconForFormsAndReports": true,
  "startForm": "frmAppShell",
  "ribbon": "AppRibbon",
  "language": "de",
  "modes": {
    "administration": { "navigationPane": false },
    "production": { "statusBar": false }
  },
  "profiles": [
    { "profile": "PROD", "modes": ["production"] },
    { "profile": "TEST", "modes": ["administration", "production"] }
  ],
  "adjustments": {
    "relink": true,
    "condition": { "function": "IsAdmin" },
    "options": [
      { "key": "Mail.Server", "label": "Mailserver", "default": "smtp.example.com" },
      { "key": "Branch", "label": "Filiale", "kind": "choice", "default": "Wien", "choices": ["Wien", "Graz"] }
    ]
  }
}

Summary

One JSON object in UTF-8. Every key except version is optional; a key left out keeps its default. An unknown key, a wrong type or an unknown value is refused with wkeInvalidValue naming the place, never ignored.

Keys

Key	Type	Default	Meaning
`version`	number	-	Format version; `1`. Required. A newer format than the components read is refused.
`title`	text	empty	Title of the Access window (AppTitle); empty keeps Access's own title.
`icon`	text	empty	File name of an .ico or .bmp file stored with the model (`WklApplication.SaveIcon`, or the build tool from the folder of the model file); becomes AppIcon.
`iconForFormsAndReports`	true/false	false	Shows the icon in the title bars of forms and reports too (UseAppIconForFrmRpt).
`startForm`	text	empty	Form opened at the start (StartUpForm); empty for none.
`ribbon`	text	empty	Ribbon of the application (CustomRibbonID), a name in USysRibbons; empty for Access's ribbon.
`language`	text	empty	Language of the application: a language code in lower case (`de`, `fr` …); the WKL components take it when it is `en`, `de`, `sl`, `hr` or `it`. Empty for automatic (Office, then Windows, then English).
`modes`	object	defaults below	User interface per mode, keys `development`, `administration`, `production`.
`profiles`	array	none	Rules: the modes a connection profile may run in.
`adjustments`	object	none	What may be adjusted in operation without development access.

modes

Each mode is an object with the following switches, all true/false. Only values that differ from the default of that mode are written; a mode left out keeps all its defaults.

Switch	Startup property	`development`	`administration`	`production`
`navigationPane`	StartUpShowDBWindow	true	true	false
`statusBar`	StartUpShowStatusBar	true	true	true
`fullMenus`	AllowFullMenus	true	false	false
`shortcutMenus`	AllowShortcutMenus	true	true	false
`builtInToolbars`	AllowBuiltInToolbars	true	false	false
`specialKeys`	AllowSpecialKeys	true	false	false
`bypassKey`	AllowBypassKey	true	false	false

The mode is never configured; WklApplication measures it: an ACCDB is development, an ACCDE in full Access administration, an ACCDE in the Access Runtime production.

profiles

An array of objects with profile (a connection profile of the Linked Tables Manager, for example PROD) and modes (an array of mode names). A profile used in a mode its rule does not name is reported by EnsureApplication, never refused.

adjustments

Key	Type	Meaning
`relink`	true/false	Allows pointing the connections to another server or database in `ShowSettings`.
`condition`	object	Who may open `ShowSettings`: `profiles` (array of profile names), `fileKinds` (array of `accdb`, `accde`, `runtime`), `function` (name of a VBA function returning True); all given parts must hold. Left out: everyone.
`options`	array	Options of the application in dialog order: `key` (letters, digits, underscore, dot; unique), `label` (text in the dialog; empty shows the key), `kind` (`text` default, `number`, `yesNo`, `choice`), `default` (in the notation of the kind: invariant number, `true`/`false`), `choices` (array, for `choice`). The application reads a value with `WklApplication.OptionValue`.

Remarks

Without a model nothing is set. A database without a saved model keeps its startup properties as they are: EnsureApplication returns an empty text and changes nothing, in every mode. The locked-down defaults of production apply only once a model is saved; the smallest model is { "version": 1 }, which applies exactly the defaults of the table above.

When the values act. WklApplication.Apply, Save and EnsureApplication write the startup properties of the current mode. Title and icon act at once; every other startup property acts at the next opening of the database. Call EnsureApplication at the start of the application (for example in the start form), so an ACCDE built for one mode and opened in another corrects itself from the next opening on. The build tool writes the startup properties of each deploy target into the delivered copy without opening it.

Same bytes. WklApplication.Canonical returns the model with the keys in the order of this page and the defaults left out, so the same model always gives the same text and the file can be kept in source control. The designer and Save store this form.

Code example

Dim app As New WklApplication
Debug.Print app.Check("{ ""version"": 1, ""title"": ""Kunden"" }")   ' empty: no problems
app.Save "{ ""version"": 1, ""title"": ""Kunden"", ""startForm"": ""frmAppShell"" }"