From a694dbb0200e5ac971fd194a169b88c3a7465fe4 Mon Sep 17 00:00:00 2001
From: Jeremy Stretch <jeremy@netverity.dev>
Date: Tue, 16 Mar 2021 11:08:34 -0400
Subject: [PATCH] Closes #5990: Deprecated display_field parameter for custom
 script ObjectVar and MultiObjectVar fields

---
 docs/additional-features/custom-scripts.md | 13 ++++---------
 docs/release-notes/version-2.11.md         |  1 +
 netbox/extras/scripts.py                   | 14 +++++++++++---
 netbox/utilities/forms/fields.py           |  1 +
 4 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/docs/additional-features/custom-scripts.md b/docs/additional-features/custom-scripts.md
index 28d1bf856..3ed910791 100644
--- a/docs/additional-features/custom-scripts.md
+++ b/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:
 
diff --git a/docs/release-notes/version-2.11.md b/docs/release-notes/version-2.11.md
index ff4aa68e0..777dcfce9 100644
--- a/docs/release-notes/version-2.11.md
+++ b/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
 
diff --git a/netbox/extras/scripts.py b/netbox/extras/scripts.py
index 3ef8741a5..062b90ea9 100644
--- a/netbox/extras/scripts.py
+++ b/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.
diff --git a/netbox/utilities/forms/fields.py b/netbox/utilities/forms/fields.py
index 05f4b4e7e..f959d53f2 100644
--- a/netbox/utilities/forms/fields.py
+++ b/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