# Customizing the editing interface (customising_the_tabbed_interface)= ## Customizing the tabbed interface As standard, Wagtail organizes panels for pages into two tabs: 'Content' and 'Promote'. For snippets, Wagtail puts all panels into one page. Depending on the requirements of your site, you may wish to customize this for specific page types or snippets - for example, adding an additional tab for sidebar content. This can be done by specifying an `edit_handler` attribute on the page or snippet model. For example: ```python from wagtail.admin.panels import TabbedInterface, TitleFieldPanel, ObjectList class BlogPage(Page): # field definitions omitted content_panels = [ TitleFieldPanel('title', classname="title"), FieldPanel('date'), FieldPanel('body'), ] sidebar_content_panels = [ FieldPanel('advert'), InlinePanel('related_links', heading="Related links", label="Related link"), ] edit_handler = TabbedInterface([ ObjectList(content_panels, heading='Content'), ObjectList(sidebar_content_panels, heading='Sidebar content'), ObjectList(Page.promote_panels, heading='Promote'), ]) ``` Permissions can be set using `permission` on the `ObjectList` to restrict entire groups of panels to specific users. ```python from wagtail.admin.panels import TabbedInterface, TitleFieldPanel, ObjectList class FundingPage(Page): # field definitions omitted shared_panels = [ TitleFieldPanel('title', classname="title"), FieldPanel('date'), FieldPanel('body'), ] private_panels = [ FieldPanel('approval'), ] edit_handler = TabbedInterface([ ObjectList(shared_panels, heading='Details'), ObjectList(private_panels, heading='Admin only', permission="superuser"), ]) ``` For more details on how to work with `Panel` and `PanelGroup` classes, see [](forms_panels_overview). (rich_text_field)= ## Rich Text (HTML) Wagtail provides a general-purpose WYSIWYG editor for creating rich text content (HTML) and embedding media such as images, video, and documents. To include this in your models, use the `RichTextField` function when defining a model field: ```python from wagtail.fields import RichTextField from wagtail.admin.panels import FieldPanel class BookPage(Page): body = RichTextField() content_panels = Page.content_panels + [ FieldPanel('body'), ] ``` `RichTextField` inherits from Django's basic `TextField` field, so you can pass any field parameters into `RichTextField` as if using a normal Django field. Its `max_length` will ignore any rich text formatting. This field does not need a special panel and can be defined with `FieldPanel`. However, template output from `RichTextField` is special and needs to be filtered in order to preserve embedded content. See [](rich_text_filter). (rich_text_features)= ### Limiting features in a rich text field By default, the rich text editor provides users with a wide variety of options for text formatting and inserting embedded content such as images. However, we may wish to restrict a rich text field to a more limited set of features - for example: - The field might be intended for a short text snippet, such as a summary to be pulled out on index pages, where embedded images or videos would be inappropriate; - When page content is defined using [StreamField](../../topics/streamfield), elements such as headings, images, and videos are usually given their own block types, alongside a rich text block type used for ordinary paragraph text; in this case, allowing headings and images to also exist within the rich text content is redundant (and liable to result in inconsistent designs). This can be achieved by passing a `features` keyword argument to `RichTextField`, with a list of identifiers for the features you wish to allow: ```python body = RichTextField(features=['h2', 'h3', 'bold', 'italic', 'link']) ``` The feature identifiers provided on a default Wagtail installation are as follows: - `h2`, `h3`, `h4` - heading elements - `bold`, `italic` - bold / italic text - `ol`, `ul` - ordered / unordered lists - `hr` - horizontal rules - `link` - page, external and email links - `document-link` - links to documents - `image` - embedded images - `embed` - embedded media (see [](embedded_content)) We have a few additional feature identifiers as well. They are not enabled by default, but you can use them in your list of identifiers. These are as follows: - `h1`, `h5`, `h6` - heading elements - `code` - inline code - `superscript`, `subscript`, `strikethrough` - text formatting - `blockquote` - blockquote The process for creating new features is described in the following pages: - [](../../extending/rich_text_internals) - [](../../extending/extending_draftail) You can also provide a setting for naming a group of rich text features. See [WAGTAILADMIN_RICH_TEXT_EDITORS](wagtailadmin_rich_text_editors). (rich_text_image_formats)= ### Image Formats in the Rich Text Editor On loading, Wagtail will search for any app with the file `image_formats.py` and execute the contents. This provides a way to customize the formatting options shown to the editor when inserting images in the `RichTextField` editor. As an example, add a "thumbnail" format: ```python # image_formats.py from wagtail.images.formats import Format, register_image_format register_image_format(Format('thumbnail', 'Thumbnail', 'richtext-image thumbnail', 'max-120x120')) ``` To begin, import the `Format` class, `register_image_format` function, and optionally `unregister_image_format` function. To register a new `Format`, call the `register_image_format` with the `Format` object as the argument. The `Format` class takes the following constructor arguments: **`name`**\ The unique key used to identify the format. To unregister this format, call `unregister_image_format` with this string as the only argument. **`label`**\ The label used in the chooser form when inserting the image into the `RichTextField`. **`classname`**\ The string to assign to the `class` attribute of the generated `` tag. ```{note} Any class names you provide must have CSS rules matching them written separately, as part of the frontend CSS code. Specifying a `classname` value of `left` will only ensure that class is output in the generated markup, it won't cause the image to align itself left. ``` **`filter_spec`** The string specification to create the image rendition. For more, see [](image_tag). To unregister, call `unregister_image_format` with the string of the `name` of the `Format` as the only argument. ```{warning} Unregistering ``Format`` objects will cause errors when viewing or editing pages that reference them. ``` (custom_edit_handler_forms)= ## Customizing generated forms ```{eval-rst} .. class:: wagtail.admin.forms.WagtailAdminModelForm .. class:: wagtail.admin.forms.WagtailAdminPageForm ``` Wagtail automatically generates forms using the panels configured on the model. By default, this form subclasses [WagtailAdminModelForm](wagtail.admin.forms.WagtailAdminModelForm), or [WagtailAdminPageForm](wagtail.admin.forms.WagtailAdminPageForm) for pages. A custom base form class can be configured by setting the `base_form_class` attribute on any model. Custom forms for snippets must subclass [WagtailAdminModelForm](wagtail.admin.forms.WagtailAdminModelForm), and custom forms for pages must subclass [WagtailAdminPageForm](wagtail.admin.forms.WagtailAdminPageForm). This can be used to add non-model fields to the form, to automatically generate field content, or to add custom validation logic for your models: ```python from django import forms from django.db import models import geocoder # not in Wagtail, for example only - https://geocoder.readthedocs.io/ from wagtail.admin.panels import TitleFieldPanel, FieldPanel from wagtail.admin.forms import WagtailAdminPageForm from wagtail.models import Page class EventPageForm(WagtailAdminPageForm): address = forms.CharField() def clean(self): cleaned_data = super().clean() # Make sure that the event starts before it ends start_date = cleaned_data['start_date'] end_date = cleaned_data['end_date'] if start_date and end_date and start_date > end_date: self.add_error('end_date', 'The end date must be after the start date') return cleaned_data def save(self, commit=True): page = super().save(commit=False) # Update the duration field from the submitted dates page.duration = (page.end_date - page.start_date).days # Fetch the location by geocoding the address page.location = geocoder.arcgis(self.cleaned_data['address']) if commit: page.save() return page class EventPage(Page): start_date = models.DateField() end_date = models.DateField() duration = models.IntegerField() location = models.CharField(max_length=255) content_panels = [ TitleFieldPanel('title'), FieldPanel('start_date'), FieldPanel('end_date'), FieldPanel('address'), ] base_form_class = EventPageForm ``` Wagtail will generate a new subclass of this form for the model, adding any fields defined in `panels` or `content_panels`. Any fields already defined on the model will not be overridden by these automatically added fields, so the form field for a model field can be overridden by adding it to the custom form. (custom_page_copy_form)= ## Customizing the generated copy page form ```{versionadded} 6.0 ``` ```{eval-rst} .. class:: wagtail.admin.forms.CopyForm ``` When copying a page, Wagtail will generate a form to allow the user to modify the copied page. By default, this form subclasses [CopyForm](wagtail.admin.forms.CopyForm). A custom base form class can be configured by setting the `copy_form_class` attribute on any model. Custom forms must subclass [CopyForm](wagtail.admin.forms.CopyForm). This can be used to specify alterations to the copied form on a per-model basis. For example, auto-incrementing the slug field: ```python from django import forms from django.db import models from wagtail.admin.forms.pages import CopyForm from wagtail.admin.panels import FieldPanel from wagtail.models import Page class CustomCopyForm(CopyForm): def __init__(self, *args, **kwargs): """ Override the default copy form to auto-increment the slug. """ super().__init__(*args, **kwargs) suffix = 2 # set initial_slug as incremented slug parent_page = self.page.get_parent() if self.page.slug: try: suffix = int(self.page.slug[-1])+1 base_slug = self.page.slug[:-2] except ValueError: base_slug = self.page.slug new_slug = base_slug + f"-{suffix}" while not Page._slug_is_available(new_slug, parent_page): suffix += 1 new_slug = f"{base_slug}-{suffix}" self.fields["new_slug"].initial = new_slug class BlogPage(Page): copy_form_class = CustomCopyForm # Set the custom copy form for all EventPage models introduction = models.TextField(blank=True) body = RichTextField() content_panels = Page.content_panels + [ FieldPanel('introduction'), FieldPanel('body'), ] ```