Clarify ObjectVar behavior in Custom Scripts #3808

New Issue

adam · 2025-12-29T18:31:18+01:00

adam commented

2025-12-29 18:31:18 +01:00

Originally created by @tyler-8 on GitHub (Jun 25, 2020).

Change Type

[X] Addition
[ ] Correction
[ ] Deprecation
[ ] Cleanup (formatting, typos, etc.)

Area

[ ] Installation instructions
[ ] Configuration parameters
[X] Functionality/features
[ ] REST API
[ ] Administration/development
[ ] Other

Proposed Changes

The ObjectVar field for Custom Scripts changed behaviors in recent months and the documentation could be improved to clarify the new functionality.

The example could be updated with this snippet to show the only built-in method for filtering:

switch_model = ObjectVar(
    description="Access switch model",
    queryset = DeviceType.objects.all(),  # filtering not supported here
    widget=APISelect(
        display_field="display_name",
        additional_query_params={
            "manufacturer": "cisco",
            "model": ['catalyst-3560x-48t', 'catalyst-3750x-48t'],  # list of slugs
        },
    ),
)

Under Default Options a think an expanded note explaining the usage of widget would be beneficial as well. Users cannot drop-in a Django widget 'out of the box' to change the behavior of the ObjectVar, they must create a new widget based on a Django widget.

Ideally an example of that could also be included here (I'll start looking in to that myself) but if anyone has that readily available we could include it as well.

The main things to be covered I think

Without a custom widget, querysets can't use filter(), they can only use .all()
Without a custom widget, filtering must be done using APISelect and the additional_query_params field
Explanation of the display_field parameter for APISelect

Perhaps to cover 2 and 3 we include the docstring for APISelect?

Originally created by @tyler-8 on GitHub (Jun 25, 2020).  ### Change Type [X] Addition [ ] Correction [ ] Deprecation [ ] Cleanup (formatting, typos, etc.) ### Area [ ] Installation instructions [ ] Configuration parameters [X] Functionality/features [ ] REST API [ ] Administration/development [ ] Other  ### Proposed Changes The ObjectVar field for Custom Scripts changed behaviors in recent months and the [documentation](https://github.com/netbox-community/netbox/blob/9fc1e88d9f5d3a93cb0288a6aee85c6a2333152b/docs/additional-features/custom-scripts.md#custom-scripts) could be improved to clarify the new functionality. The example could be updated with this snippet to show the only built-in method for filtering: ```python switch_model = ObjectVar( description="Access switch model", queryset = DeviceType.objects.all(), # filtering not supported here widget=APISelect( display_field="display_name", additional_query_params={ "manufacturer": "cisco", "model": ['catalyst-3560x-48t', 'catalyst-3750x-48t'], # list of slugs }, ), ) ``` Under [Default Options](https://github.com/netbox-community/netbox/blob/9fc1e88d9f5d3a93cb0288a6aee85c6a2333152b/docs/additional-features/custom-scripts.md#default-options) a think an expanded note explaining the usage of widget would be beneficial as well. Users cannot drop-in a Django widget 'out of the box' to change the behavior of the ObjectVar, they must create a new widget based on a Django widget. Ideally an example of that could also be included here (I'll start looking in to that myself) but if anyone has that readily available we could include it as well. The main things to be covered I think 1) Without a custom widget, querysets can't use `filter()`, they can only use `.all()` 2) Without a custom widget, filtering must be done using `APISelect` and the `additional_query_params` field 3) Explanation of the `display_field` parameter for `APISelect` Perhaps to cover 2 and 3 we include the docstring for `APISelect`?

adam added the status: accepted type: documentation labels 2025-12-29 18:31:19 +01:00

adam closed this issue

2025-12-29 18:31:19 +01:00

adam commented

2025-12-29 18:31:19 +01:00

@jeremystretch commented on GitHub (Jun 25, 2020):

As discussed, APISelect is not and will not be part of the public API for custom scripts. #4789 has been opened to propose the functionality in play, but in the interim the documentation just needs to be updated to remove the outdated example.

@jeremystretch commented on GitHub (Jun 25, 2020): As discussed, APISelect is not and will not be part of the public API for custom scripts. #4789 has been opened to propose the functionality in play, but in the interim the documentation just needs to be updated to remove the outdated example.

Sign in to join this conversation.

Branches Tags

main

update-changelog-comments-docs

feature-removal-issue-type

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#3808