Wagtail CMS

Warnings

• breaking The `wagtail.core` module was deprecated and removed in Wagtail 3.0+. Core components like `Page`, `Site`, `StreamField`, and `Image` were moved to more specific modules.
  Fix: Update all import paths. For example, change `from wagtail.core.models import Page` to `from wagtail.models import Page`, and `from wagtail.core.fields import StreamField` to `from wagtail.fields import StreamField`.
• breaking The `wagtail.admin.edit_handlers` module was removed and replaced by `wagtail.admin.panels` in Wagtail 3.0+. Panel classes (`FieldPanel`, `MultiFieldPanel`, etc.) and their API have changed significantly.
  Fix: Update import paths from `wagtail.admin.edit_handlers` to `wagtail.admin.panels` and refactor panel definitions according to the new API. Consult the Wagtail 3.0+ upgrade guide for detailed changes.
• breaking For `StreamField` definitions, `use_json_field=True` is now the default and implicitly required for new fields in Wagtail 3.0+. Projects upgrading from older versions where `StreamField` might have used a different underlying storage may require manual data migrations.
  Fix: Always include `use_json_field=True` for new `StreamField` definitions for clarity. Review the official Wagtail upgrade guides for detailed data migration strategies if upgrading an existing project with `StreamField`s.
• gotcha Wagtail has strict requirements on the supported Django versions for each major release. Using an unsupported Django version will lead to integration issues, runtime errors, or unexpected behavior.
  Fix: Before upgrading Wagtail or Django, always consult the official Wagtail documentation for the compatibility matrix for your specific Wagtail version (e.g., Wagtail 7.x requires Django 4.2 to 6.0).
• gotcha When rendering `StreamField` content in templates, ensure you correctly use Wagtail's template tags like `{% include_block %}` or `{{ self.body|richtext }}`. Custom block templates need careful setup, and direct iteration over `StreamField` values may not provide the full block context for rich rendering.
  Fix: Refer to Wagtail's StreamField template documentation for best practices. Use `{% include_block %}` with appropriate block templates for complex blocks, and ensure custom block rendering logic handles `self` and `parent_context` correctly.

Install

• pip install wagtail Install Wagtail

Imports

• Page

  from wagtail.models import Page

  The `wagtail.core` module was deprecated and removed in Wagtail 3.0+. Core models moved to `wagtail.models`.
• StreamField

  from wagtail.fields import StreamField

  The `wagtail.core` module was deprecated and removed in Wagtail 3.0+. Core fields moved to `wagtail.fields`.
• blocks

  from wagtail import blocks

  The primary way to import Wagtail's built-in block types (e.g., `blocks.CharBlock`).
• FieldPanel

  from wagtail.admin.panels import FieldPanel

  The `edit_handlers` module was removed and replaced by `wagtail.admin.panels` in Wagtail 3.0+.

Quickstart

This code snippet demonstrates a basic Wagtail `Page` model with a `StreamField`. The `StreamField` allows content editors to dynamically add and reorder various content blocks (like headings, paragraphs, images, and embeds) on a page. This model should be placed in `models.py` within a Django app of your Wagtail project, then migrate and set up a superuser to access the Wagtail admin.

from django.db import models
from wagtail.models import Page
from wagtail.fields import StreamField
from wagtail import blocks
from wagtail.admin.panels import FieldPanel

class HomePage(Page):
    """
    A simple example of a Wagtail Page model with a StreamField.
    This defines a flexible content structure editable in the Wagtail admin.
    """
    body = StreamField([
        ('heading', blocks.CharBlock(form_classname="full title")), # Simple text block
        ('paragraph', blocks.RichTextBlock()),                      # Rich text editor
        ('image', blocks.ImageChooserBlock()),                     # Image picker
        ('embed', blocks.RawHTMLBlock(icon='code')),               # Raw HTML embed
    ], use_json_field=True, blank=True, null=True)

    # Define the fields that will appear in the Wagtail admin editor
    content_panels = Page.content_panels + [
        FieldPanel('body'),
    ]

    # You would typically also define a template (e.g., home/home_page.html)
    # and potentially an `abstract` page for common fields across your site.