navpane.json

The model of the navigation pane of a database: one custom category of Access's own navigation pane with its groups and shortcuts, the group the pane shows at the start, whether Access's group of unassigned objects is hidden, whether the pane is locked, and conditions under which a group or a shortcut is shown. WklNavPane keeps the model in the table USysWklNavPane of the database. The build tool reads it from the file named by navPaneModel in access-app.json; in a WKL Office SDK project, it reads navigation/navpane.json from the project sources.

Signature

{
  "version": 1,
  "category": "Kunden",
  "defaultGroup": "Daten",
  "hideUnassigned": false,
  "lock": true,
  "groups": [
    {
      "name": "Daten",
      "entries": [
        { "kind": "form", "object": "frmCustomer", "label": "Kunden" },
        { "kind": "report", "object": "rptCustomerList", "label": "Kundenliste" }
      ]
    },
    {
      "name": "Verwaltung",
      "condition": { "profiles": ["DEV", "TEST"], "fileKinds": ["accdb"] },
      "entries": [
        { "kind": "table", "object": "tblCustomer" },
        { "kind": "module", "object": "basAdmin", "condition": { "function": "IsAdmin" } }
      ]
    },
    { "name": "Archiv", "hidden": true }
  ]
}

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. Comments are not allowed.

Keys

Key	Type	Default	Meaning
`version`	number	-	Format version; `1`. Required. Another number is refused.
`category`	text	empty	Name of the custom category, as the heading of the pane and the list of categories show it. Required before the model can be saved (at most 255 characters).
`defaultGroup`	text	empty	The group the pane is filtered to when the model is applied; empty shows the whole category. Must name a group of the model that is not hidden (case is ignored).
`hideUnassigned`	true/false	true	Hides Access's group „Unassigned Objects“ of the category; `false` shows there every object in the database that isn't in any group.
`lock`	true/false	false	Locks the pane against deleting, renaming and changing groups (`DoCmd.LockNavigationPane`).
`groups`	array	none	The groups of the category, in this order.

Group

Key	Type	Default	Meaning
`name`	text	-	Caption of the group. Required, at most 255 characters, unique within the category (case is ignored).
`hidden`	true/false	false	The group exists but is hidden: Access shows it grayed out only when hidden objects are shown. A hidden group cannot be the `defaultGroup`.
`condition`	object	none	When the group is shown; see Condition. A group whose condition does not hold is not written at all.
`entries`	array	none	The shortcuts of the group. The pane sorts them by display name on its own.

Entry

Key	Type	Default	Meaning
`kind`	text	-	The kind of object: `table` (local or linked), `query`, `form`, `report`, `macro` or `module` (standard or class module). Required.
`object`	text	-	Name of the object in the database (for example `frmCustomer`). Required. The same object may appear only once per group.
`label`	text	empty	Name the pane shows for the shortcut (at most 255 characters); empty shows the object name.
`condition`	object	none	When the shortcut is shown; see Condition.

Condition

The same form as the conditions of the ribbon commands. Every part that is given must hold; a condition left out always holds.

Key	Type	Meaning
`profiles`	array of text	The connection profiles (for example `DEV`, `TEST`, `PROD` of the Linked Tables Manager) under which it is shown; case is ignored. The profile is the one set with `WklNavPane.Profile` or `WklRibbon.Profile`, else the profile most linked tables use.
`fileKinds`	array of text	`accdb` (an ACCDB in full Access), `accde` (an ACCDE in full Access), `runtime` (any database in the Access Runtime); shown when the database is one of the kinds given. A database in the Runtime counts as `runtime` only.
`function`	text	Name of a public VBA function without arguments; shown when it returns True or a number other than 0. A function that fails counts as False.

Remarks

When conditions act. Conditions are evaluated when the model is applied (WklNavPane.Apply, and Save unless its second argument is False). What does not hold is not written into the pane, so a user cannot make it visible through the Navigation Options. The pane keeps what was written last: an application whose pane differs per environment calls Apply when it starts, for example in the Load event of its startup form. Conditions are a convenience, not a protection; whoever opens the database can still open the object some other way.

Missing objects. An entry may name an object the database does not have yet (a later build adds it). Check does not count it as a problem; Apply leaves the entry out and returns one line per missing object.

Same bytes. WklNavPane stores the model with the keys in the order of this page and the defaults left out (hideUnassigned only when false, lock and hidden only when true), indented with two spaces, with LF line endings and a final line ending. A model read and written again gives the same text, so the file can be kept in source control.

Built-in categories. Only the custom category is written. Access's built-in categories (Object Type, Tables and Related Views) stay as they are.

Code example

Dim pane As New WklNavPane
Debug.Print pane.Check("{ ""version"": 1, ""category"": ""Kunden"" }")   ' empty: no problems
pane.Save "{ ""version"": 1, ""category"": ""Kunden"", ""groups"": [ { ""name"": ""Daten"" } ] }"