starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

Plugin Development Documentation Extending Templates section out of date #5326

New Issue
Closed
opened 2025-12-29 19:26:41 +01:00 by adam · 6 comments
adam commented 2025-12-29 19:26:41 +01:00
Owner
Copy Link

Originally created by @991jo on GitHub (Sep 7, 2021).

Originally assigned to: @dvaccarosenna on GitHub.

Change Type

Correction

Area

Administration/development

Proposed Changes

Some NetBox internals regarding the UI have changed in NetBox v3.
I am currently porting my plugins to v3 and have to adopt to the new UI.

The "Extending the Base Template section" (https://netbox.readthedocs.io/en/stable/plugins/development/#extending-the-base-template) is still referring to the old base template. I think this template is no longer called base.html but base/base.html and some of the blocks have new names. But there is also a base/layout.html which implements a lot of the base structure of the NetBox pages.

The documentation should be updated to reflect these changes and comment on what to use and which parts are for what.

Originally created by @991jo on GitHub (Sep 7, 2021). Originally assigned to: @dvaccarosenna on GitHub. ### Change Type Correction ### Area Administration/development ### Proposed Changes Some NetBox internals regarding the UI have changed in NetBox v3. I am currently porting my plugins to v3 and have to adopt to the new UI. The "Extending the Base Template section" (https://netbox.readthedocs.io/en/stable/plugins/development/#extending-the-base-template) is still referring to the old base template. I think this template is no longer called `base.html` but `base/base.html` and some of the blocks have new names. But there is also a `base/layout.html` which implements a lot of the base structure of the NetBox pages. The documentation should be updated to reflect these changes and comment on what to use and which parts are for what.
adam added the status: acceptedtype: documentation labels 2025-12-29 19:26:41 +01:00
adam closed this issue 2025-12-29 19:26:41 +01:00
adam commented 2025-12-29 19:26:42 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Sep 7, 2021):

@991jo would you like to volunteer to update the documentation, given that you're in the ideal spot to do so?

@jeremystretch commented on GitHub (Sep 7, 2021): @991jo would you like to volunteer to update the documentation, given that you're in the ideal spot to do so?
adam commented 2025-12-29 19:26:42 +01:00
Author
Owner
Copy Link

@991jo commented on GitHub (Sep 7, 2021):

I am not in the position to do that, because that part defines a piece of the plugin development interface. If the documentation says "use template X" then as a plugin dev I would assume that this is a part of the official plugin API and is (more or less) stable.

Also I am currently digging through the templates and trying to figure out the changes required for my own plugins.

Also I would really appreciate it if some other templates like the generic/object_*.html templates and probably several others are declared as "safe for use in plugins" and would have some kind of documentation on what an object has to do to work with those templates.
(I tried it and i am currently getting errors from the viewname filter in generic/object.html because it just returns $my_plugin:$my_modelinstead of plugins:$my_plugins:$my_model for an url. Maybe this is off topic here, maybe there needs to be a general decision on whether some parts of NetBox should be opened up for plugins or not and how that has to work)

Anyway: I think I am not in the right spot to do the documentation atm, but I can do proof reading and testing because I have 3 plugins to port to the new UI.

@991jo commented on GitHub (Sep 7, 2021): I am not in the position to do that, because that part defines a piece of the plugin development interface. If the documentation says "use template X" then as a plugin dev I would assume that this is a part of the official plugin API and is (more or less) stable. Also I am currently digging through the templates and trying to figure out the changes required for my own plugins. Also I would really appreciate it if some other templates like the `generic/object_*.html` templates and probably several others are declared as "safe for use in plugins" and would have some kind of documentation on what an object has to do to work with those templates. (I tried it and i am currently getting errors from the `viewname` filter in `generic/object.html` because it just returns `$my_plugin:$my_model`instead of `plugins:$my_plugins:$my_model` for an `url`. Maybe this is off topic here, maybe there needs to be a general decision on whether some parts of NetBox should be opened up for plugins or not and how that has to work) Anyway: I think I am not in the right spot to do the documentation atm, but I can do proof reading and testing because I have 3 plugins to port to the new UI.
adam commented 2025-12-29 19:26:42 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Sep 7, 2021):

I am not in the position to do that, because that part defines a piece of the plugin development interface.

The documentation doesn't define it, the templates do, if that makes sense. The documentation is just for reference.

Also I am currently digging through the templates and trying to figure out the changes required for my own plugins.

Exactly. This makes you ideally situated to update the documentation with your own experience.

@jeremystretch commented on GitHub (Sep 7, 2021): > I am not in the position to do that, because that part defines a piece of the plugin development interface. The documentation doesn't define it, the templates do, if that makes sense. The documentation is just for reference. > Also I am currently digging through the templates and trying to figure out the changes required for my own plugins. Exactly. This makes you ideally situated to update the documentation with your own experience.
adam commented 2025-12-29 19:26:43 +01:00
Author
Owner
Copy Link

@991jo commented on GitHub (Sep 7, 2021):

I am not in the position to do that, because that part defines a piece of the plugin development interface.

The documentation doesn't define it, the templates do, if that makes sense. The documentation is just for reference.

I will quote the documentation regarding plugin development here (the first big WARNING block):

While very powerful, the NetBox plugins API is necessarily limited in its scope. The plugins API is discussed here in its entirety: Any part of the NetBox code base not documented here is not part of the supported plugins API, and should not be employed by a plugin. Internal elements of NetBox are subject to change at any time and without warning. Plugin authors are strongly encouraged to develop plugins using only the officially supported components discussed here and those provided by the underlying Django framework so as to avoid breaking changes in future releases.

It basically says "here are a set of things you are allowed to use as a plugin developer. Everything else can be used at your own risk, dont blame is if stuff breaks."

@991jo commented on GitHub (Sep 7, 2021): > > I am not in the position to do that, because that part defines a piece of the plugin development interface. > > The documentation doesn't define it, the templates do, if that makes sense. The documentation is just for reference. I will quote the documentation regarding plugin development here (the first big WARNING block): > While very powerful, the NetBox plugins API is necessarily limited in its scope. The plugins API is discussed here in its entirety: Any part of the NetBox code base not documented here is not part of the supported plugins API, and should not be employed by a plugin. Internal elements of NetBox are subject to change at any time and without warning. Plugin authors are strongly encouraged to develop plugins using only the officially supported components discussed here and those provided by the underlying Django framework so as to avoid breaking changes in future releases. It basically says "here are a set of things you are allowed to use as a plugin developer. Everything else can be used at your own risk, dont blame is if stuff breaks."
adam commented 2025-12-29 19:26:43 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Sep 7, 2021):

Yes, and it needs to be updated to reflect the new templates.

@jeremystretch commented on GitHub (Sep 7, 2021): Yes, and it needs to be updated to reflect the new templates.
adam commented 2025-12-29 19:26:43 +01:00
Author
Owner
Copy Link

@dvaccarosenna commented on GitHub (Sep 10, 2021):

I've also been looking through the documentation to port some plugins to v3 and it seems referring to the new template is the only required change. If it's agreed that base/layout.html is the suggested base template for plugins then I'm happy to submit a PR for this.

@dvaccarosenna commented on GitHub (Sep 10, 2021): I've also been looking through the documentation to port some plugins to v3 and it seems referring to the new template is the only required change. If it's agreed that `base/layout.html` is the suggested base template for plugins then I'm happy to submit a PR for this.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label status: accepted type: documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#5326
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?