🛠️ User Settings Override

📄 Overview

To support instance-level default UI preferences, the application allows selective overriding of user settings via the config.json file. These overrides apply only if the user has not explicitly set a value through the UI settings panel.

This mechanism ensures that:

Users retain control over their preferences
Instances can enforce sensible defaults for new or unconfigured users

⚙️ How It Works

The system tracks which settings a user has explicitly configured.
During initialization, any setting defined in userUiSettingsDefaults will be applied only if the user has not set it themselves.
This is a non-destructive override — user-defined values always take precedence.
Settings are applied in the api’s public/config.json

🧪 Example

json

CODE

{
  "userUiSettingsDefaults": {
    "searchCountEnabled": true,
    "sortResultsArchivesByResultsCount": false,
    "alwaysOpenNewTab": false
  }
}

If the user has previously set alwaysOpenNewTab to true, that value will remain unchanged. The other two settings will be applied from the defaults.

🧾 Supported Settings

The following properties can be included in userUiSettingsDefaults. All are optional and must match the expected type:

Setting	Type	Description
`alwaysOpenNewTab`	`boolean`	Always open documents in a new tab
`annotationNoteDefaultFillColor`	`string`	Default background color for note annotations
`annotationNoteDefaultFontName`	`GenericFont`	Default font name for note annotations
`annotationNoteDefaultFontSize`	`number`	Default font size for note annotations
`archiveHistoryResultsPerPage`	`number`	Results per page in archive history
`archiveResultsPerPage`	`number`	Results per page in archive view
`currentLanguage`	`string`	UI language preference
`customStamps`	`string[]`	User-defined stamp annotations
`deleteInboxDocumentOnInsert`	`boolean`	Delete inbox document after insert
`deleteSearchDocumentsOnInsert`	`boolean`	Delete search documents after insert
`doubleClickOpen`	`boolean`	Double-click opens document
`dxcAppendToMultivalue`	`boolean`	Append matched values to multivalues
`dxcSearchSystemFields`	`boolean`	Include system fields in DXC lookups
`enabledTasksList`	`string[]`	List of enabled GlobalAction tasks
`hideArchivesWithNoResults`	`boolean`	Hide empty archives
`indexerReloadAfterSave`	`boolean`	Reload fields after save
`keepBaseSearchDocumentOnInsert`	`boolean`	Keep base document after insert
`keyfreeUseOcr`	`boolean`	Use local OCR for keyfree
`keyfreeAutoOcr`	`boolean`	Auto-enable OCR when no text layer is found
`persistArchiveImportData`	`boolean`	Persist import data across sessions
`refreshResultsWhenClosingDocumentTabs`	`boolean`	Refresh results when closing tabs (requires `alwaysOpenNewTab`)
`searchCountEnabled`	`boolean`	Load search counts in archive menu
`showDomainInHistoryResults`	`boolean`	Show domain in history results
`showFavoriteSearches`	`boolean`	Show favorite searches in sidebar
`showGlobalActionTasks`	`boolean`	Show GlobalAction tasks in sidebar
`showVersionsArchive`	`boolean`	Show versions archive
`sortResultsArchivesByResultsCount`	`boolean`	Sort multi-archive search by result count
`themeMode`	`ThemeMode`	UI theme mode (`light`, `dark`, etc.)
`usePreviousSearchCriteriaInRelatedSearch`	`boolean`	Use previous criteria in related search
`viewerAutoSave`	`boolean`	Autosave changes in internal viewer
`viewerUseInternal`	`boolean`	Use internal document viewer
`viewerUseInternalForImport`	`boolean`	Use internal viewer for imports

🧠 Best Practices

Use userUiSettingsDefaults sparingly to avoid overriding user intent.