Closes #15932: Update embedded documentation for generic templates

netbox/templates/generic/bulk_add_component.html

@@ -4,6 +4,20 @@
 {% load render_table from django_tables2 %}
 {% load i18n %}
 
+{% comment %}
+Blocks:
+  - title:    Page title
+  - tabs:     Page tabs
+  - content:  Primary page content
+
+Context:
+  - form:               The object creation form
+  - parent_model_name:  The name of the model to which the new component belongs
+  - model_name:         The name of the component model
+  - table:              The table of newly-created component objects
+  - return_url:         The URL to which the user is redirected after submitting the form
+{% endcomment %}
+
 {% block title %}
   {% trans "Add" %} {{ model_name|title }}
 {% endblock %}

netbox/templates/generic/bulk_delete.html

@@ -5,13 +5,15 @@
 
 {% comment %}
 Blocks:
-  message_extra: Supplementary warning message content
+  - title:    Page title
+  - tabs:     Page tabs
+  - content:  Primary page content
 
 Context:
-  model: The model class of the objects being deleted
-  form: The bulk delete form class
-  table: The table class for rendering list of objects being deleted
-  return_url: The URL to which the user is redirected after submitting the form
+  - model:       The model class of the objects being deleted
+  - form:        The bulk delete form class
+  - table:       The table class for rendering list of objects being deleted
+  - return_url:  The URL to which the user is redirected after submitting the form
 {% endcomment %}
 
 {% block title %}

netbox/templates/generic/bulk_edit.html

@@ -5,11 +5,16 @@
 {% load i18n %}
 
 {% comment %}
+Blocks:
+  - title:    Page title
+  - tabs:     Page tabs
+  - content:  Primary page content
+
 Context:
-  model: The model class of the objects being modified
-  form: The bulk edit form class
-  table: The table class for rendering list of objects being modified
-  return_url: The URL to which the user is redirected after submitting the form
+  - model:       The model class of the objects being modified
+  - form:        The bulk edit form class
+  - table:       The table class for rendering list of objects being modified
+  - return_url:  The URL to which the user is redirected after submitting the form
 {% endcomment %}
 
 {% block title %}

netbox/templates/generic/bulk_import.html

@@ -4,11 +4,16 @@
 {% load i18n %}
 
 {% comment %}
+Blocks:
+  - title:    Page title
+  - tabs:     Page tabs
+  - content:  Primary page content
+
 Context:
-  model: The model class being imported
-  form: The bulk import form
-  fields: A dictionary of form fields, to display import options (optional)
-  return_url: The URL to which the user is redirected after submitting the form
+  - model:       The model class being imported
+  - form:        The bulk import form
+  - fields:      A dictionary of form fields, to display import options (optional)
+  - return_url:  The URL to which the user is redirected after submitting the form
 {% endcomment %}
 
 {% block title %}{{ model|meta:"verbose_name"|bettertitle }} {% trans "Bulk Import" %}{% endblock %}

netbox/templates/generic/bulk_remove.html

@@ -3,6 +3,20 @@
 {% load render_table from django_tables2 %}
 {% load i18n %}
 
+{% comment %}
+Blocks:
+  - title:    Page title
+  - tabs:     Page tabs
+  - content:  Primary page content
+
+Context:
+  - form:              The bulk edit form class
+  - parent_obj:        The parent object
+  - table:             A table of objects being removed
+  - obj_type_plural:   The plural form of the object type
+  - return_url:        The URL to which the user is redirected after submitting the form
+{% endcomment %}
+
 {% block title %}
   {% trans "Remove" %} {{ table.rows|length }} {{ obj_type_plural|bettertitle }}?
 {% endblock %}

netbox/templates/generic/bulk_rename.html

@@ -3,6 +3,19 @@
 {% load form_helpers %}
 {% load i18n %}
 
+{% comment %}
+Blocks:
+  - title:    Page title
+  - tabs:     Page tabs
+  - content:  Primary page content
+
+Context:
+  - form:              The bulk edit form class
+  - obj_type_plural:   The plural form of the object type
+  - selected_objects:  A queryset matching the objects selected for bulk renaming
+  - return_url:        The URL to which the user is redirected after submitting the form
+{% endcomment %}
+
 {% block title %}
   {% trans "Renaming" %} {{ selected_objects|length }} {{ obj_type_plural|bettertitle }}
 {% endblock %}

netbox/templates/generic/object.html

@@ -9,13 +9,20 @@
 
 {% comment %}
 Blocks:
-  breadcrumbs: Breadcrumb list items (HTML <li> elements)
-  object_identifier: Unique identifier for the object
-  extra_controls: Additional action buttons to display
-  content: Page content
+  - page-header:          Content displayed above the primary page content
+    - breadcrumbs:        Breadcrumb list items (HTML <li> elements)
+    - object_identifier:  Unique identifier for the object
+  - title:                Page title
+  - subtitle:             Additional context displayed below the title
+  - controls:             Control elements displayed between the header and content
+    - control-buttons:    Action buttons (add/edit/delete/etc.)
+      - extra_controls:   Any additional action buttons to display
+  - tabs:                 Page tabs
+  - content:              Primary page content
+  - modals:               Any pre-loaded modals
 
 Context:
-  object: The object instance being viewed
+  - object: The object being viewed
 {% endcomment %}
 
 {% block page-header %}

netbox/templates/generic/object_children.html

@@ -2,6 +2,27 @@
 {% load helpers %}
 {% load i18n %}
 
+{% comment %}
+Blocks:
+  - content:                   Primary page content
+    - table_controls:          Control elements for the child objects table
+    - bulk_controls:           Bulk action buttons which appear beneath the child objects table
+      - bulk_edit_controls:    Bulk edit buttons
+      - bulk_delete_controls:  Bulk delete buttons
+      - bulk_extra_controls:   Other bulk action buttons
+  - modals:                    Any pre-loaded modals
+
+Context:
+  - base_template:  The template which this template extends
+  - object:         The parent object
+  - child_model:    The model of child objects being displayed
+  - table:          The table containing child objects
+  - table_config:   The ID of the table configuration modal
+  - actions:        A list of enabled bulk actions
+  - tab:            The currently active tab
+  - return_url:     The URL to which the user is redirected after performing a bulk action
+{% endcomment %}
+
 {% block content %}
     {% block table_controls %}
         {% include 'inc/table_controls_htmx.html' with table_modal=table_config %}

netbox/templates/generic/object_delete.html

@@ -4,11 +4,15 @@
 {% load i18n %}
 
 {% comment %}
+Blocks:
+  - title:      Page title
+  - content:    Primary page content
+
 Context:
-  object: Python instance of the object being deleted
-  form: The delete confirmation form
-  form_url: URL for form submission (optional; defaults to current path)
-  return_url: The URL to which the user is redirected after submitting the form
+  - object:      Python instance of the object being deleted
+  - form:        The delete confirmation form
+  - form_url:    URL for form submission (optional; defaults to current path)
+  - return_url:  The URL to which the user is redirected after submitting the form
 {% endcomment %}
 
 {% block title %}

netbox/templates/generic/object_edit.html

@@ -3,13 +3,18 @@
 
 {% comment %}
 Blocks:
-  form: Content within the <form> element
-  buttons: Form submission buttons
+  - title:      Page title
+  - controls:   Control elements displayed between the header and content
+  - tabs:       Page tabs
+  - content:    Primary page content
+    - form:     Content within the <form> element
+    - buttons:  Form submission buttons
+  - modals:     Any pre-loaded modals
 
 Context:
-  object: Python instance of the object being edited
-  form: The edit form
-  return_url: The URL to which the user is redirected after submitting the form
+  - object:      Python instance of the object being edited
+  - form:        The edit form
+  - return_url:  The URL to which the user is redirected after submitting the form
 {% endcomment %}
 
 {% block title %}

netbox/templates/generic/object_list.html

@@ -8,17 +8,21 @@
 
 {% comment %}
 Blocks:
-  extra_controls: Additional action buttons
-  bulk_buttons: Additional bulk action buttons to display beneath the objects
-    list
+  - title:             Page title
+  - controls:          Control elements displayed between the header and content
+    - extra_controls:  Any additional action buttons to display
+  - tabs:              Page tabs
+  - content:           Primary page content
+    - bulk_buttons:    Additional bulk action buttons to display beneath the objects list
+  - modals:            Any pre-loaded modals
 
 Context:
-  model: The model class being listed
-  table: The table class used for rendering the list of objects
-  actions: A list of buttons to display. This template checks for add, import,
-    export, bulk_edit, and bulk_delete.
-  filter_form: The bound filterset form for filtering the objects list (optional)
-  return_url: Return URL to use for bulk actions (optional)
+  - model:        The model class being listed
+  - table:        The table class used for rendering the list of objects
+  - actions:      A list of buttons to display. This template checks for add, import, export,
+                  bulk_edit, and bulk_delete.
+  - filter_form:  The bound filterset form for filtering the objects list (optional)
+  - return_url:   Return URL to use for bulk actions (optional)
 {% endcomment %}
 
 {% block title %}{{ model|meta:"verbose_name_plural"|bettertitle }}{% endblock %}