iamnatch / wagtail-graphql

App to automatically add GraphQL support to a Wagtail website

    

---

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

• Page models
• Snippets
• Images
• Documents
• StreamFields with Basic Blocks and StructBlocks

Contributing

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

Links

• Repository: https://github.com/tr11/wagtail-graphql
• Issue tracker: https://github.com/tr11/wagtail-graphql/issues

Licensing

The code in this project is licensed under MIT license.