Signals¶
Wagtail’s Revision and Page implement Signals from django.dispatch
.
Signals are useful for creating side-effects from page publish/unpublish events.
For example, you could use signals to send publish notifications to a messaging service, or POST
messages to another app that’s consuming the API, such as a static site generator.
page_published
¶
This signal is emitted from a Revision
when a page revision is set to published
.
sender
- The pageclass
.instance
- The specificPage
instance.revision
- TheRevision
that was published.kwargs
- Any other arguments passed topage_published.send()
.
To listen to a signal, implement page_published.connect(receiver, sender, **kwargs)
. Here’s a simple
example showing how you might notify your team when something is published:
from wagtail.signals import page_published
import requests
# Let everyone know when a new page is published
def send_to_slack(sender, **kwargs):
instance = kwargs['instance']
url = 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'
values = {
"text" : "%s was published by %s " % (instance.title, instance.owner.username),
"channel": "#publish-notifications",
"username": "the squid of content",
"icon_emoji": ":octopus:"
}
response = requests.post(url, values)
# Register a receiver
page_published.connect(send_to_slack)
Receiving specific model events¶
Sometimes you’re not interested in receiving signals for every model, or you want to handle signals for specific models in different ways. For instance, you may wish to do something when a new blog post is published:
from wagtail.signals import page_published
from mysite.models import BlogPostPage
# Do something clever for each model type
def receiver(sender, **kwargs):
# Do something with blog posts
pass
# Register listeners for each page model class
page_published.connect(receiver, sender=BlogPostPage)
Wagtail provides access to a list of registered page types through the get_page_models()
function in wagtail.models
.
Read the Django documentation for more information about specifying senders.
page_unpublished
¶
This signal is emitted from a Page
when the page is unpublished.
sender
- The pageclass
.instance
- The specificPage
instance.kwargs
- Any other arguments passed topage_unpublished.send()
pre_page_move
and post_page_move
¶
These signals are emitted from a Page
immediately before and after it is moved.
Subscribe to pre_page_move
if you need to know values BEFORE any database changes are applied. For example: Getting the page’s previous URL, or that of its descendants.
Subscribe to post_page_move
if you need to know values AFTER database changes have been applied. For example: Getting the page’s new URL, or that of its descendants.
The following arguments are emitted for both signals:
sender
- The pageclass
.instance
- The specificPage
instance.parent_page_before
- The parent page ofinstance
before moving.parent_page_after
- The parent page ofinstance
after moving.url_path_before
- The value ofinstance.url_path
before moving.url_path_after
- The value ofinstance.url_path
after moving.kwargs
- Any other arguments passed topre_page_move.send()
orpost_page_move.send()
.
Distinguishing between a ‘move’ and a ‘reorder’¶
The signal can be emitted as a result of a page being moved to a different section (a ‘move’), or as a result of a page being moved to a different position within the same section (a ‘reorder’). Knowing the difference between the two can be particularly useful, because only a ‘move’ affects a page’s URL (and that of its descendants), whereas a ‘reorder’ only affects the natural page order; which is probably less impactful.
The best way to distinguish between a ‘move’ and ‘reorder’ is to compare the url_path_before
and url_path_after
values. For example:
from wagtail.signals import pre_page_move
from wagtail.contrib.frontend_cache.utils import purge_page_from_cache
# Clear a page's old URLs from the cache when it moves to a different section
def clear_page_url_from_cache_on_move(sender, **kwargs):
if kwargs['url_path_before'] == kwargs['url_path_after']:
# No URLs are changing :) nothing to do here!
return
# The page is moving to a new section (possibly even a new site)
# so clear old URL(s) from the cache
purge_page_from_cache(kwargs['instance'])
# Register a receiver
pre_page_move.connect(clear_old_page_urls_from_cache)
page_slug_changed
¶
This signal is emitted from a Page
when a change to its slug is published.
The following arguments are emitted by this signal:
sender
- The pageclass
.instance
- The updated (and saved), specificPage
instance.instance_before
- A copy of the specificPage
instance from before the changes were saved.
workflow_submitted¶
This signal is emitted from a WorkflowState
when a page is submitted to a workflow.
sender
-WorkflowState
instance
- The specificWorkflowState
instance.user
- The user who submitted the workflowkwargs
- Any other arguments passed toworkflow_submitted.send()
workflow_rejected¶
This signal is emitted from a WorkflowState
when a page is rejected from a workflow.
sender
-WorkflowState
instance
- The specificWorkflowState
instance.user
- The user who rejected the workflowkwargs
- Any other arguments passed toworkflow_rejected.send()
workflow_approved¶
This signal is emitted from a WorkflowState
when a page’s workflow completes successfully
sender
-WorkflowState
instance
- The specificWorkflowState
instance.user
- The user who last approved the workflowkwargs
- Any other arguments passed toworkflow_approved.send()
workflow_cancelled¶
This signal is emitted from a WorkflowState
when a page’s workflow is cancelled
sender
-WorkflowState
instance
- The specificWorkflowState
instance.user
- The user who cancelled the workflowkwargs
- Any other arguments passed toworkflow_cancelled.send()
task_submitted¶
This signal is emitted from a TaskState
when a page is submitted to a task.
sender
-TaskState
instance
- The specificTaskState
instance.user
- The user who submitted the page to the taskkwargs
- Any other arguments passed totask_submitted.send()
task_rejected¶
This signal is emitted from a TaskState
when a page is rejected from a task.
sender
-TaskState
instance
- The specificTaskState
instance.user
- The user who rejected the taskkwargs
- Any other arguments passed totask_rejected.send()
task_approved¶
This signal is emitted from a TaskState
when a page’s task is approved
sender
-TaskState
instance
- The specificTaskState
instance.user
- The user who approved the taskkwargs
- Any other arguments passed totask_approved.send()
task_cancelled¶
This signal is emitted from a TaskState
when a page’s task is cancelled.
sender
-TaskState
instance
- The specificTaskState
instance.user
- The user who cancelled the taskkwargs
- Any other arguments passed totask_cancelled.send()