Panel API¶
This document describes the reference API for the base Panel
and the BoundPanel
classes that are used to render Wagtail’s panels. For available panel types and how to use them, see Panel types.
Panel
¶
- class wagtail.admin.panels.Panel(heading='', classname='', help_text='', base_form_class=None, icon='', attrs=None)¶
Defines part (or all) of the edit form interface for pages and other models within the Wagtail admin. Each model has an associated top-level panel definition (also known as an edit handler), consisting of a nested structure of
Panel
objects. This provides methods for obtaining aModelForm
subclass, with the field list and other parameters collated from all panels in the structure. It then handles rendering that form as HTML.The following parameters can be used to customise how the panel is displayed. For more details, see Panel customization.
- Parameters:
heading – The heading text to display for the panel.
classname – A CSS class name to add to the panel’s HTML element.
help_text – Help text to display within the panel.
base_form_class – The base form class to use for the panel. Defaults to the model’s
base_form_class
, before falling back toWagtailAdminModelForm
. This is only relevant for the top-level panel.icon – The name of the icon to display next to the panel heading.
attrs – A dictionary of HTML attributes to add to the panel’s HTML element.
- bind_to_model(model)¶
Create a clone of this panel definition with a
model
attribute pointing to the linked model class.
- on_model_bound()¶
Called after the panel has been associated with a model class and the
self.model
attribute is available; panels can override this method to perform additional initialisation related to the model.
- clone()¶
Create a clone of this panel definition. By default, constructs a new instance, passing the keyword arguments returned by
clone_kwargs
.
- clone_kwargs()¶
Return a dictionary of keyword arguments that can be used to create a clone of this panel definition.
- get_form_options()¶
Return a dictionary of attributes such as ‘fields’, ‘formsets’ and ‘widgets’ which should be incorporated into the form class definition to generate a form that this panel can use. This will only be called after binding to a model (i.e. self.model is available).
- get_form_class()¶
Construct a form class that has all the fields and formsets named in the children of this edit handler.
- get_bound_panel(instance=None, request=None, form=None, prefix='panel')¶
Return a
BoundPanel
instance that can be rendered onto the template as a component. By default, this creates an instance of the panel class’s innerBoundPanel
class, which must inherit fromPanel.BoundPanel
.
- property clean_name¶
A name for this panel, consisting only of ASCII alphanumerics and underscores, suitable for use in identifiers. Usually generated from the panel heading. Note that this is not guaranteed to be unique or non-empty; anything making use of this and requiring uniqueness should validate and modify the return value as needed.
BoundPanel
¶
- class wagtail.admin.panels.Panel.BoundPanel(panel, instance, request, form, prefix)¶
A template component for a panel that has been associated with a model instance, form, and request.
In addition to the standard template component functionality (see Creating components), this provides the following attributes and methods:
- panel¶
The panel definition corresponding to this bound panel
- instance¶
The model instance associated with this panel
- request¶
The request object associated with this panel
- form¶
The form object associated with this panel
- prefix¶
A unique prefix for this panel, for use in HTML IDs
- id_for_label()¶
Returns an HTML ID to be used as the target for any label referencing this panel.
- is_shown()¶
Whether this panel should be rendered; if false, it is skipped in the template output.