From ba1c0d6d84c86bec980b5b93c7a37d72c8a14e40 Mon Sep 17 00:00:00 2001 From: Martin Hauser Date: Tue, 30 Sep 2025 20:16:36 +0200 Subject: [PATCH] Closes #20449: Add user preferences documentation (#20460) --- docs/configuration/default-values.md | 4 +- docs/development/user-preferences.md | 2 + docs/features/customization.md | 8 ++-- docs/features/user-preferences.md | 63 ++++++++++++++++++++++++++++ docs/models/extras/tableconfig.md | 5 ++- mkdocs.yml | 1 + 6 files changed, 76 insertions(+), 7 deletions(-) create mode 100644 docs/features/user-preferences.md diff --git a/docs/configuration/default-values.md b/docs/configuration/default-values.md index 1d1992a8e..c1ca904e9 100644 --- a/docs/configuration/default-values.md +++ b/docs/configuration/default-values.md @@ -4,7 +4,7 @@ This parameter controls the content and layout of user's default dashboard. Once the dashboard has been created, the user is free to customize it as they please by adding, removing, and reconfiguring widgets. -This parameter must specify an iterable of dictionaries, each representing a discrete dashboard widget and its configuration. The follow widget attributes are supported: +This parameter must specify an iterable of dictionaries, each representing a discrete dashboard widget and its configuration. The following widget attributes are supported: * `widget`: Dotted path to the Python class (required) * `width`: Default widget width (between 1 and 12, inclusive) @@ -63,6 +63,8 @@ DEFAULT_USER_PREFERENCES = { For a complete list of available preferences, log into NetBox and navigate to `/user/preferences/`. A period in a preference name indicates a level of nesting in the JSON data. The example above maps to `pagination.per_page`. +See also: [Clearing table preferences](../features/user-preferences.md#clearing-table-preferences) for resolving errors caused by saved table columns or ordering. + --- ## PAGINATE_COUNT diff --git a/docs/development/user-preferences.md b/docs/development/user-preferences.md index deb469bfb..9944b5060 100644 --- a/docs/development/user-preferences.md +++ b/docs/development/user-preferences.md @@ -2,6 +2,8 @@ The `users.UserConfig` model holds individual preferences for each user in the form of JSON data. This page serves as a manifest of all recognized user preferences in NetBox. +For end‑user guidance on resetting saved table layouts, see [Features > User Preferences](../features/user-preferences.md#clearing-table-preferences). + ## Available Preferences | Name | Description | diff --git a/docs/features/customization.md b/docs/features/customization.md index 1fbace3c5..4ea39691c 100644 --- a/docs/features/customization.md +++ b/docs/features/customization.md @@ -2,6 +2,8 @@ While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs. +For end‑user personalization topics (bookmarks, table preferences, language, CSV delimiter, and more), see [Features > User Preferences](../features/user-preferences.md). + ## Tags Most objects in NetBox can be assigned user-created tags to aid with organization and filtering. Tag values are completely arbitrary: They may be used to store data in key-value pairs, or they may be employed simply as labels against which objects can be filtered. Each tag can also be assigned a color for quicker differentiation in the user interface. @@ -18,10 +20,6 @@ The `tag` filter can be specified multiple times to match only objects which hav GET /api/dcim/devices/?tag=monitored&tag=deprecated ``` -## Bookmarks - -Users can bookmark their most commonly visited objects for convenient access. Bookmarks are listed under a user's profile, and can be displayed with custom filtering and ordering on the user's personal dashboard. - ## Custom Fields While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs. @@ -38,7 +36,7 @@ Custom links allow you to conveniently reference external resources related to N http://server.local/vms/?name={{ object.name }} ``` -Now, when viewing a virtual machine in NetBox, a user will see a handy button with the chosen title and link (complete with the name of the VM being viewed). Both the text and URL of custom links can be templatized in this manner, and custom links can be grouped together into dropdowns for more efficient display. +Now, when viewing a virtual machine in NetBox, a user will see a handy button with the chosen title and link (complete with the name of the VM being viewed). Both the text and URL of custom links can be templatized in this manner, and custom links can be grouped together into dropdowns for a more efficient display. To learn more about this feature, check out the [custom link documentation](../customization/custom-links.md). diff --git a/docs/features/user-preferences.md b/docs/features/user-preferences.md new file mode 100644 index 000000000..6c0a2884f --- /dev/null +++ b/docs/features/user-preferences.md @@ -0,0 +1,63 @@ +# User Preferences + +NetBox stores per‑user options that control aspects of the web interface and data display. Preferences persist across sessions and can be managed under **User → Preferences**. + +## Table configurations + +When a list view is configured using **Configure**, NetBox records the selected columns and ordering as per‑user table preferences for that table. These preferences are applied automatically on subsequent visits. + +### Clearing table preferences + +Saved table preferences may need to be reset, for example, if a table fails to render or after an upgrade that changes available columns. + +To clear saved preferences for one or more tables: + +1. Click the username in the top‑right corner. +2. Select **Preferences** from the dropdown. +3. Scroll to the **Table Configurations** section. +4. Select the tables to reset. +5. Click **Submit** to clear the selected preferences. + +After clearing preferences, reopen the list view and use **Configure** to set the desired columns and ordering. + +!!! note + Per‑user table preferences are distinct from **Table Configs**, which are named, reusable configurations managed under *Customization → Table Configs*. Clearing preferences does not delete any Table Configs. See [Table Configs](../models/extras/tableconfig.md) for details. + +## Other preferences + +### Language +Selects the user interface language from installed translations (subject to system configuration). + +### Page length +Sets the default number of rows displayed on paginated tables. + +### Paginator placement +Controls where pagination controls are rendered relative to a table. + +### HTMX navigation (experimental) +Enables partial‑page navigation for supported views. Disable this preference if unexpected behavior is observed. + +### Striped table rows +Toggles alternating row backgrounds on tables. + +### Data format (raw views) +Sets the default format (JSON or YAML) when rendering raw data blocks. + +### CSV delimiter +Overrides the delimiter used when exporting CSV data. + +## Bookmarks + +Users can bookmark frequently visited objects for convenient access. Bookmarks appear under the user menu and can be displayed on the personal dashboard using the bookmarks' widget. See [Bookmark](../models/extras/bookmark.md) for model details. + +## Notifications and subscriptions + +Users may subscribe to objects to receive notifications when changes occur. Notifications are listed under the user menu and can be marked as read or deleted. See [Features > Notifications](notifications.md) and the data‑model references for [Subscription](../models/extras/subscription.md) and [Notification](../models/extras/notification.md). + +## Admin defaults + +Administrators can define defaults for new users via [`DEFAULT_USER_PREFERENCES`](../configuration/default-values.md#default_user_preferences). Users may override these values under their own preferences. + +## See also + +- [Development > User Preferences](../development/user-preferences.md) (manifest of recognized preference keys) diff --git a/docs/models/extras/tableconfig.md b/docs/models/extras/tableconfig.md index e5484ec64..b12fc4a4c 100644 --- a/docs/models/extras/tableconfig.md +++ b/docs/models/extras/tableconfig.md @@ -4,6 +4,9 @@ This object represents the saved configuration of an object table in NetBox. Tab For example, you might wish to create a table config for the devices list to assist in inventory tasks. This view might show the device name, location, serial number, and asset tag, but omit operational details like IP addresses. Once applied, this table config can be saved for reuse in future audits. +!!! note + Per‑user table preferences (columns and ordering remembered for an individual user) are distinct from Table Configs. If a list view fails to render due to outdated saved preferences, see [Clearing table preferences](../../features/user-preferences.md#clearing-table-preferences). + ## Fields ### Name @@ -20,7 +23,7 @@ The type of NetBox object to which the table config pertains. ### Table -The name of the specific table to which the table config pertains. (Some NetBox object use multiple tables.) +The name of the specific table to which the table config pertains. (Some NetBox objects use multiple tables.) ### Weight diff --git a/mkdocs.yml b/mkdocs.yml index 4df1b5d43..fd6d7e4f2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -86,6 +86,7 @@ nav: - Change Logging: 'features/change-logging.md' - Journaling: 'features/journaling.md' - Event Rules: 'features/event-rules.md' + - User Preferences: 'features/user-preferences.md' - Notifications: 'features/notifications.md' - Background Jobs: 'features/background-jobs.md' - Auth & Permissions: 'features/authentication-permissions.md'