0
# Wagtail
1
2
A Django content management system focused on user experience, offering precise control for designers and developers. Wagtail provides a comprehensive CMS framework with a fast and attractive interface for content authors, complete control over front-end design, and powerful content management capabilities.
3
4
## Package Information
5
6
- **Package Name**: wagtail
7
- **Language**: Python
8
- **Installation**: `pip install wagtail`
9
- **Documentation**: https://docs.wagtail.org
10
11
## Core Imports
12
13
```python
14
import wagtail
15
from wagtail.models import Page
16
```
17
18
Common imports for building pages:
19
20
```python
21
from wagtail.models import Page
22
from wagtail.fields import RichTextField, StreamField
23
from wagtail.blocks import CharBlock, TextBlock, StructBlock
24
from wagtail.admin.panels import FieldPanel, MultiFieldPanel
25
```
26
27
## Basic Usage
28
29
```python
30
from wagtail.models import Page
31
from wagtail.fields import RichTextField
32
from wagtail.admin.panels import FieldPanel
33
34
# Create a basic page model
35
class BlogPage(Page):
36
body = RichTextField(blank=True)
37
38
content_panels = Page.content_panels + [
39
FieldPanel('body'),
40
]
41
42
# In your Django settings
43
INSTALLED_APPS = [
44
'wagtail.contrib.forms',
45
'wagtail.contrib.redirects',
46
'wagtail.embeds',
47
'wagtail.sites',
48
'wagtail.users',
49
'wagtail.snippets',
50
'wagtail.documents',
51
'wagtail.images',
52
'wagtail.search',
53
'wagtail.admin',
54
'wagtail',
55
56
'django.contrib.admin',
57
'django.contrib.auth',
58
'django.contrib.contenttypes',
59
# ... other Django apps
60
]
61
62
# URL configuration
63
from wagtail import urls as wagtail_urls
64
from wagtail.admin import urls as wagtailadmin_urls
65
66
urlpatterns = [
67
path('admin/', admin.site.urls),
68
path('cms/', include(wagtailadmin_urls)),
69
path('', include(wagtail_urls)),
70
]
71
```
72
73
## Architecture
74
75
Wagtail's architecture is built on Django's foundation with key components:
76
77
- **Page Models**: Hierarchical content structure using Django models with tree-based organization
78
- **StreamField**: Flexible content blocks allowing structured content without rigid templates
79
- **Admin Interface**: React-based admin panel with extensible editing interface
80
- **Revision System**: Complete version control with draft/publish workflow
81
- **Search Integration**: Built-in search using Django ORM, PostgreSQL, or Elasticsearch
82
- **Collections**: Media organization system for images, documents, and snippets
83
- **Workflows**: Approval processes with task-based content moderation
84
- **Multi-site Support**: Single installation managing multiple websites
85
86
This design provides a scalable CMS that integrates seamlessly with Django applications while offering rich content management capabilities.
87
88
## Capabilities
89
90
### Page Models and Content Structure
91
92
Core page functionality including the Page model hierarchy, content fields, and tree-based organization. Provides the foundation for all content in Wagtail.
93
94
```python { .api }
95
class Page(MP_Node):
96
title: str
97
slug: str
98
live: bool
99
def get_url(self, request=None, current_site=None): ...
100
def serve(self, request): ...
101
def get_context(self, request): ...
102
```
103
104
[Page Models](./page-models.md)
105
106
### Content Fields and Blocks
107
108
Flexible content field types including RichTextField and StreamField with structured content blocks for building dynamic page layouts.
109
110
```python { .api }
111
class RichTextField(models.TextField):
112
def __init__(self, editor='default', features=None, **kwargs): ...
113
114
class StreamField(models.Field):
115
def __init__(self, block_types, **kwargs): ...
116
```
117
118
[Content Fields](./content-fields.md)
119
120
### Admin Interface and Panels
121
122
Customizable admin interface with panel system for organizing edit forms, menu configuration, and admin UI extensions.
123
124
```python { .api }
125
class FieldPanel:
126
def __init__(self, field_name, widget=None, **kwargs): ...
127
128
class MultiFieldPanel:
129
def __init__(self, children, heading='', **kwargs): ...
130
```
131
132
[Admin Interface](./admin-interface.md)
133
134
### Search and Indexing
135
136
Full-text search capabilities with configurable backends, search field configuration, and query interfaces.
137
138
```python { .api }
139
class SearchField:
140
def __init__(self, field_name, partial_match=True, boost=1): ...
141
142
class Indexed:
143
search_fields: list
144
```
145
146
[Search](./search.md)
147
148
### Images and Documents
149
150
Media management with image processing, renditions, document handling, and collection-based organization.
151
152
```python { .api }
153
class Image(AbstractImage):
154
def get_rendition(self, filter): ...
155
156
class Document(AbstractDocument):
157
title: str
158
file: FileField
159
```
160
161
[Media Management](./media.md)
162
163
### API Framework
164
165
REST API endpoints for headless CMS functionality with serializers for pages, images, and documents.
166
167
```python { .api }
168
class PagesAPIViewSet(BaseAPIViewSet):
169
def get_queryset(self): ...
170
171
class APIField:
172
def __init__(self, name, serializer=None): ...
173
```
174
175
[API Framework](./api.md)
176
177
### Workflows and Publishing
178
179
Content approval workflows with task-based moderation, publishing controls, and revision management.
180
181
```python { .api }
182
class Workflow(models.Model):
183
def start(self, page, user): ...
184
185
class Task(models.Model):
186
def start(self, workflow_state, user): ...
187
```
188
189
[Workflows](./workflows.md)
190
191
### Template Tags and Utilities
192
193
Template tags for page URLs, content rendering, and template utilities for building Wagtail-powered front-ends.
194
195
```python { .api }
196
def pageurl(page, request=None): ...
197
def include_block(block_value): ...
198
```
199
200
[Template System](./templates.md)
201
202
### Contrib Modules and Extensions
203
204
Additional functionality modules that extend Wagtail's core capabilities with forms, redirects, settings management, and specialized content types.
205
206
```python { .api }
207
@register_snippet
208
class Category(models.Model):
209
name: str
210
211
class AbstractForm(Page):
212
def get_form(self): ...
213
def process_form_submission(self, form): ...
214
```
215
216
[Contrib Modules](./contrib.md)
217
218
### System Integration
219
220
Signals, hooks, and utilities for customizing Wagtail behavior, integrating with external systems, and extending functionality.
221
222
```python { .api }
223
@hooks.register('construct_main_menu')
224
def add_menu_items(request, menu_items): ...
225
226
page_published.connect(my_handler)
227
```
228
229
[System Integration](./system-integration.md)