Database-based routing (default)

The default routing strategy uses sharing sites stored in the database, using a new wagtailsharing.SharingSite model. This approach allows for configuration of different sharing domains for different Wagtail sites.

WAGTAILSHARING_ROUTER = "wagtailsharing.routers.db.DatabaseHostRouter"

With database-based routing, Wagtail adds a new admin section under Settings -> Sharing Sites that allows users to define how they would like to expose latest page revisions.

No sharing sites exist by default. A sharing site must be manually created for each Wagtail Site to make its latest revisions shareable. Each sharing site is defined by a unique hostname and port number.

In the above configuration, drafts will be viewable at http://sharing.mysite.com:8000/.

Settings-based routing

Sharing can also be configured via Django settings. This approach avoids the need to configure sharing via the database, but only works for the default Wagtail site.

WAGTAILSHARING_ROUTER = "wagtailsharing.routers.settings.SettingsHostRouter"
WAGTAILSHARING_HOST = "http://sharing.mysite.com:8000"

With this configuration, draft pages will also be viewable at http://sharing.mysite.com:8000/.

Specify multiple hosts as a list or comma-delimited string to share the default Wagtail site on multiple domains:

WAGTAILSHARING_ROUTER = "wagtailsharing.routers.settings.SettingsHostRouter"
WAGTAILSHARING_HOST = [
    "http://sharing.mysite.com:8000",
    "http://sharing2.mysite.com:8000",
]

Custom routing

A custom router can be used for alternative routing strategies. For example, you might want to route based on authentication tokens, query parameters, or other criteria beyond hostname matching.

To create a custom router, inherit from wagtailsharing.routers.base.RouterBase and implement the required methods:

from wagtailsharing.routers.base import RouterBase

class CustomRouter(RouterBase):
    def route(self, request, path):
        # Returns (Site, path) tuple or (None, path) if no match.
        ...

    def get_sharing_url(self, page):
        # Returns the sharing URL for a given page.
        ...

Then configure it in your settings:

WAGTAILSHARING_ROUTER = "myapp.routers.CustomRouter"

Database-based routing

If you’re using the default database-based routing, you’ll also need to add wagtail.snippets to your installed apps:

# in settings.py
INSTALLED_APPS = (
    ...
    "wagtail.snippets",
    "wagtailsharing",
    ...
)

You’ll also need to run migrations to create the required database tables:

$ python manage.py migrate wagtailsharing

Settings-based routing

If you’re using settings-based routing, you only need to add the router configuration to your settings:

WAGTAILSHARING_ROUTER = "wagtailsharing.routers.settings.SettingsHostRouter"
WAGTAILSHARING_HOST = "http://sharing.mysite.com:8000"

before_route_page

Called when routing, before a page’s route() method is called. This hook is passed the request and the page that will have route() called on it. If the callable returns an HttpResponse, that response will be returned immediately to the user.

This hook allows for any necessary customization of Wagtail’s built-in routing behavior, for example to support ShareableRoutablePageMixin.

before_serve_shared_page

Called before the latest revision of the page is about to be served, just before its serve() method is called. Like before_serve_page this hook is passed the page object, the request object, and the args and kwargs that will be passed to the page’s serve() method. If the callable returns an HttpResponse, that response will be returned immediately to the user.

This hook could be useful for limiting sharing to only certain page types or for modifying a page’s contents when it is shared.

from wagtail import hooks

@hooks.register("before_serve_shared_page")
def modify_shared_title(page, request, args, kwargs):
    page.title += " (Shared)"

after_serve_shared_page

Called after the page’s serve() method is called but before the response is returned to the user. This hook is passed the page object and the response object returned by serve(). If the callable returns an HttpResponse, that response will be returned immediately to the user.

This hook could be useful for directly modifying the response content, for example by adding custom headers or altering the generated HTML. This hook is used to implement the notification banner described above.

from wagtail import hooks

@hooks.register("after_serve_shared_page")
def add_custom_header(page, response):
    response["Wagtail-Is-Shared"] = "1"

ShareableRoutablePageMixin

Wagtail’s RoutablePageMixin is not compatible with Wagtail Sharing, instead you need to use ShareableRoutablePageMixin in order to view shared draft content fields on routable pages.

ShareableRoutablePageMixin is used exactly the same way as RoutablePageMixin:

from wagtail.fields import RichTextField
from wagtail.models import Page
from wagtail.contrib.routable_page.models import route
from wagtailsharing.models import ShareableRoutablePageMixin


class EventIndexPage(ShareableRoutablePageMixin, Page):
    intro = RichTextField()

    @route(r"^$")
    def current_events(self, request):
        # …

    @route(r"^past/$")
    def past_events(self, request):
        # …