search

torchbox / wagtail-grapple

A Wagtail app that makes building GraphQL endpoints a breeze!
https://wagtail-grapple.readthedocs.io/en/latest/
Other
155 stars 59 forks source link

Update for Preview documentation #81

Open tbrlpld opened 4 years ago

tbrlpld commented 4 years ago

I am currently working on setting up my first project with Wagtail as the CMS and a Gatsby frontend and got quite confused when I was trying to the preview to work.

In my setup I closely followed the instructions in the docs and added all the settings for the subscriptions with channels. This unfortunately did not quite work out for me (as is documented in another issue).

Because of the phrasing in the docs I assumed that I definitely need the subscriptions to work to enable the preview functionality.

Grapple’s Headless Preview is built-on GraphQL Subscriptions which means that your client subscribes to the preview page and any changes in the Admin will be pushed to your client via WebSockets. This allows you to add preview support to any client whether that be a SPA or Native App.

Luckily, in my debugging attempts I discovered the example Grapple project in the repo. I checked if the subscriptions would work with that project, hoping that something about my own projects Wagtail setup caused the subscription to fail. Unfortunately I got the same error message. So my own projects setup seems to reflect that of the Grapple example project.

I don't know why exactly, but I thought to still try out the preview button in the admin of the Grapple example project. At first it was only showing the browsers 404 page. Which is not surprising at this point there was no frontend that would handle the preview. Even though I had already checked that the subscriptions did not work, I went ahead and created an extremely simple Gatsby frontend for the Grapple example project. This turns out was a great decision, because I discovered that the preview was working! I did not update on every keystroke in the Wagtail admin, but the preview tab would reflect changes in the admin after the preview button was pressed again.

This was huge to me. Until this point I thought I would have to find a different (most certainly hacky) solution for the preview.

I went back to the docs to see if I had missed something and focusing on the subscriptions was a wrong turn I took at some point, but the documentation (to me at least) seems to suggest that working subscriptions a definitely necessary to make the preview work. This does not seem to be the case.

Especially when working with the gatsby-source-wagtail package for the frontend the preview works basically out of the box with no extra settings for channels required.

My proposal here would be to update the preview documentation and split basic setup (in which the clicking of the preview button is still required) and the setup for the "live" preview (which requires the channels package settings).

Also, in either case, a crucial bit of documentation that is currently not mentioned at all is the settings for the django-cors-headers. These settings are necessary to make even the basic preview working. I luckily discovered these settings in the Grapple example project and found them mentioned in the Wagtail Headless Preview README. I think it would be extremely helpful to directly reference these in the Grapple docs to streamline the setup for new users.

@NathHorrigan @zerolab If you in general agree with this proposal, I am happy to implement the changes and create a PR. Any feedback obviously welcome!

zerolab commented 4 years ago

@tbrlpld thank you for the detailed write-up. I agree the docs can be improved, so yes please to your offer for the PR.

NathHorrigan commented 4 years ago

Thanks @tbrlpld , I'll be happy to review anything once the PR is ready :)