Closes #5990: Deprecated display_field parameter for custom script ObjectVar and MultiObjectVar fields

Author: jeremystretch

docs/additional-features/custom-scripts.md

@@ -170,18 +170,13 @@ Similar to `ChoiceVar`, but allows for the selection of multiple choices.
 A particular object within NetBox. Each ObjectVar must specify a particular model, and allows the user to select one of the available instances. ObjectVar accepts several arguments, listed below.
 
 * `model` - The model class
-* `display_field` - The name of the REST API object field to display in the selection list (default: `'name'`)
+* `display_field` - The name of the REST API object field to display in the selection list (default: `'display'`)
 * `query_params` - A dictionary of query parameters to use when retrieving available options (optional)
 * `null_option` - A label representing a "null" or empty choice (optional)
 
-The `display_field` argument is useful when referencing a model which does not have a `name` field. For example, when displaying a list of device types, you would likely use the `model` field:
-
-```python
-device_type = ObjectVar(
-    model=DeviceType,
-    display_field='model'
-)
-```
+!!! warning
+    The `display_field` parameter is now deprecated, and will be removed in NetBox v2.12. All ObjectVar instances will
+    instead use the new standard `display` field for all serializers (introduced in NetBox v2.11).
 
 To limit the selections available within the list, additional query parameters can be passed as the `query_params` dictionary. For example, to show only devices with an "active" status:
 

docs/release-notes/version-2.11.md

@@ -84,6 +84,7 @@ The ObjectChange model (which is used to record the creation, modification, and
 
 * [#1638](https://github.com/netbox-community/netbox/issues/1638) - Migrate all primary keys to 64-bit integers
 * [#5873](https://github.com/netbox-community/netbox/issues/5873) - Use numeric IDs in all object URLs
+* [#5990](https://github.com/netbox-community/netbox/issues/5990) - Deprecated `display_field` parameter for custom script ObjectVar and MultiObjectVar fields
 
 ### REST API Changes
 

netbox/extras/scripts.py

@@ -180,14 +180,22 @@ class ObjectVar(ScriptVariable):
     A single object within NetBox.
 
     :param model: The NetBox model being referenced
-    :param display_field: The attribute of the returned object to display in the selection list (default: 'name')
+    :param display_field: The attribute of the returned object to display in the selection list (DEPRECATED)
     :param query_params: A dictionary of additional query parameters to attach when making REST API requests (optional)
     :param null_option: The label to use as a "null" selection option (optional)
     """
     form_field = DynamicModelChoiceField
 
-    def __init__(self, model=None, queryset=None, display_field='name', query_params=None, null_option=None, *args,
-                 **kwargs):
+    def __init__(self, model=None, queryset=None, query_params=None, null_option=None, *args, **kwargs):
+
+        # TODO: Remove display_field in v2.12
+        if 'display_field' in kwargs:
+            warnings.warn(
+                "The 'display_field' parameter has been deprecated, and will be removed in NetBox v2.12. Object "
+                "variables will now reference the 'display' attribute available on all model serializers by default."
+            )
+        display_field = kwargs.pop('display_field', 'display')
+
         super().__init__(*args, **kwargs)
 
         # Set the form field's queryset. Support backward compatibility for the "queryset" argument for now.

netbox/utilities/forms/fields.py

@@ -276,6 +276,7 @@ class DynamicModelChoiceMixin:
     filter = django_filters.ModelChoiceFilter
     widget = widgets.APISelect
 
+    # TODO: Remove display_field in v2.12
     def __init__(self, display_field='display', query_params=None, initial_params=None, null_option=None,
                  disabled_indicator=None, brief_mode=True, *args, **kwargs):
         self.display_field = display_field