Skip to content

Latest commit

 

History

History
132 lines (95 loc) · 4.16 KB

README.md

File metadata and controls

132 lines (95 loc) · 4.16 KB
Raw

    

wagtail-graphql

An app to automatically add GraphQL support to a Wagtail website

This Wagtail app adds GraphQL types to other Wagtail apps. The objective is for this library to interact with an existing website in a generic way and with minimal effort. In particular, it makes minimal assumptions about the structure of the website to allow for a generic API.

Installing / Getting started

To install as a general app:

pip install wagtail-graphql

Add it together with graphene_django to the Django INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'wagtail_graphql',
    'graphene_django',
    ...
]

Initial Configuration

Add the required graphene schema GRAPHENE and a GRAPHQL_API dictionary. Include all the Wagtail apps the library should generate bindings to in the APPS list and optionally specify the prefix for each app in PREFIX. To remove a leading part of all the urls for a specific site, specify the URL_PREFIX parameter for each needed host.

GRAPHENE = {
    'SCHEMA': 'wagtail_graphql.schema.schema',
}

GRAPHQL_API = {
    'APPS': [
        'home'
    ],
    'PREFIX': {
        'home': ''        # optional, prefix for all the app classes generated by the wrapper
    },
    'URL_PREFIX': {
        'localhost': '/home'   # optional, read from the site information if not specified 
    }
}

The example above generates bindings for the home app, . Every url in this example will be stripped of the initial /home substring.

Finally, set up the GraphQL views in the project urls.py. For example, to add two endpoints for GraphQL and the GraphiQL IDE:

from django.views.decorators.csrf import csrf_exempt
from graphene_django.views import GraphQLView

urlpatterns = [
    ...
    url(r'^api/graphql', csrf_exempt(GraphQLView.as_view())),
    url(r'^api/graphiql', csrf_exempt(GraphQLView.as_view(graphiql=True, pretty=True)),
    ...
]

Note that the urls above need to appear before the wagtail_urls catchall entry.

Images

To be able to generate urls for images the following also needs to be included in the project's urls.py:

from wagtail.images.views.serve import ServeView

urlpatterns = [
    ...
    url(r'^images/([^/]*)/(\d*)/([^/]*)/[^/]*$', ServeView.as_view(), name='wagtailimages_serve'),
    ...
]

Multi-site configuration

This library works transparently with a multi-site Wagtail install without any extra configuration required. To strip a custom leading prefix for each site, specify each host in the URL_PREFIX. For exaple, for two hosts host1.example.com and host2.example.com:

GRAPHQL_API = {
    ...
    'URL_PREFIX': {
        'host1.example.com': '/prefix1',
        'host2.example.com': '/prefix2'
    }
    ...
}

Note that the prefix for a site is taken from the root page url if a host is not included in the URL_PREFIX dictionary.

Developing

To develop this library, download the source code and install a local version in your Wagtail website.

Features

This project is intended to require minimal configuration and interaction. It currently supports

Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are welcome.

Links

Licensing

The code in this project is licensed under MIT license.