diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index 1e0d5c31e..e9ff7bd9f 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -40,14 +40,22 @@ Related custom fields can be grouped together within the UI by assigning each th This parameter has no effect on the API representation of custom field data. -### Visibility +### Visibility & Editing -When creating a custom field, there are three options for UI visibility. These control how and whether the custom field is displayed within the NetBox UI. +!!! info "This feature was improved in NetBox v3.7." -* **Read/write** (default): The custom field is included when viewing and editing objects. -* **Read-only**: The custom field is displayed when viewing an object, but it cannot be edited via the UI. (It will appear in the form as a read-only field.) +When creating a custom field, users can control the conditions under which it may be displayed and edited within the NetBox user interface. The following choices are available for controlling the display of a custom field on an object: + +* **Always** (default): The custom field is included when viewing an object. +* **If Set**: The custom field is included only if a value has been defined for the object. * **Hidden**: The custom field will never be displayed within the UI. This option is recommended for fields which are not intended for use by human users. +Additionally, the following options are available for controlling whether custom field values can be altered within the NetBox UI: + +* **Yes** (default): The custom field's value may be modified when editing an object. +* **No**: The custom field is displayed for reference when editing an object, but its value may not be modified. +* **Hidden**: The custom field is not displayed when editing an object. + Note that this setting has no impact on the REST or GraphQL APIs: Custom field data will always be available via either API. ### Validation diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md index bf0c4755a..e68ddb79d 100644 --- a/docs/models/extras/customfield.md +++ b/docs/models/extras/customfield.md @@ -64,16 +64,25 @@ Defines how filters are evaluated against custom field values. | Loose | Match any occurrence of the value | | Exact | Match only the complete field value | -### UI Visibility +### UI Visible -Controls how and whether the custom field is displayed within the NetBox user interface. +Controls whether the custom field is displayed for objects within the NetBox user interface. -| Option | Description | -|-------------------|--------------------------------------------------| -| Read/write | Display and permit editing (default) | -| Read-only | Display field but disallow editing | -| Hidden | Do not display field in the UI | -| Hidden (if unset) | Display in the UI only when a value has been set | +| Option | Description | +|--------|----------------------------------------------------------------| +| Always | The field is always displayed when viewing an object (default) | +| If set | The field is displayed only if a value has been defined | +| Hidden | The field is not displayed when viewing an object | + +### UI Editable + +Controls whether the custom field is editable on objects within the NetBox user interface. + +| Option | Description | +|--------|------------------------------------------------------------------------------| +| Yes | The field's value may be changed when editing an object (default) | +| No | The field's value is displayed when editing an object but may not be altered | +| Hidden | The field is not displayed when editing an object | ### Default