Wagtail as a Headless CMS

Speaker 1: Okay, hello everyone. My name is uh Michael Harrison. I'm going to be talking about using Wagtail as a headless CMS, and I'll talk about what that is in just a moment. There you go. So I've been working in the education market for pretty much my whole career, and I'm a very big advocate of open source technology in the education market. I've been working with Rice since 2012. When I got there, they were all Ectron, Microsoft, and I slowly got most of the core campus services moved over to Django, so like our search appliance and uh graduate applications and a few other things are on Django, which is pretty cool.

Speaker 1: Uh I now work with Uh OpenStax, which is a department that's within Rice, but we're very separated from it. We actually so we publish open open source textbooks uh under the Creative Commons Attribution License. And mostly other schools use our books, not really Newman at Rice. So our I'm going to talk about our website today. Our main website. We have a few different little websites, but our main website is the one that's on Wagtail. And um let's see. So here's our website. Uh so a headless website works just like a regular website

Speaker 1: Um if anything it's probably a little bit faster because you don't have uh template rendering that's going on. Uh I think someone, Ryan, was talking about having to debug queries uh that were happening using template tags. Yeah, I don't really have to worry about that. Um I just have to worry about the API being fast and then our front-end developers take care of the the caching and speed that's involved in that. So this is kind of the makeup of a headless CMS and kind of like the benefits of it. Uh so it makes it very scalable. We don't have to worry about um who is using our content for what purpose. So like We have an Android app that

Speaker 1: someone uses to show some books, and he can do that using the API server just as easily as our JavaScript developer does with the content for our main website. So I wanted to talk a little bit about why we ended up going with Wagtail. So the main one was that I was spearheading the Search for the CMS we were gonna use, and I was very familiar with Django already. So uh Wagtail happened to pop up as I was looking through the things that had changed in the Django CMS world and looked really good, so I gave it a try. Um the editing interface was probably the One of the number one things that stuck out to me.

Speaker 1: Um it definitely puts content first. Um All of our editors are internal marketing people, so they're not very technical, but they are very happy with the way the editor works, so definitely a good decision. Uh it's also very developer-friendly, as we all know, because it's based on Django, and Django is very developer-friendly. Next was our ability to decouple the front end and the back end. This was a large requirement from everyone on our team. In doing this, it makes our upgrading release cycle much easier. We can release our front end currently during the day with no downtime.

Speaker 1: And I'm hoping that someone here can help me figure that out for our back-end Wagtail instance. That's definitely in the pipeline. And having these things decoupled allows us to To figure this out separately. We don't have to worry about what else might break as we're trying to figure out how to release the back end without having uh downtime. And then of course Wagtail already had a content API, which was extremely nice. And uh when I was doing the initial search for what we were gonna use , I was able to have a website up and running with an API in like 15 minutes. So of course that was impressive to everyone. Oh, I meant to mention all the slides are uh

Speaker 1: here and this link is on every slide. So if there's a bunch of links and code And uh so if you want to look at any of that stuff, you're welcome to go there. I think my speaker notes are there too, which are not following really well, but Uh so this is the ecosystem of our code, our backend. Uh there are two separate repositories and It was actually kind of interesting because when Tom asked me to talk about this, it was very difficult for me to come up with topics because actually it was really easy to make Wagtail a headless CMS. So the backend is really just Wagtail. There are some things that we had to deal with that I'm about to go over, but it was actually really easy to make this headline.

Speaker 1: And then the back end is a custom JavaScript framework. It was written by someone who knows who is no longer with us. And just a word of advice if you go down this path, use a framework that is not custom. It's very nice to have documentation when you need it and when new people are onboarding. So that was probably a mistake, um, but it's very fast. So he did a good job with that Okay, so now I'm going to show some of the things we had issues with, and I'm probably just as new to Wagtail as many of you, so I'm sure there's a more Pythonic way to do some of this stuff. uh general disclaimer that pretty much everyone has given today. So

Speaker 1: the first thing was that we had a um A UX team that was working very closely with all the pages that we were making for our site, and they wanted every pixel accounted for And so the only way that we could do that was to define each page very rigidly, especially at the beginning. I knew about stream fields, but I didn't know enough about them to Make some kind of a general page and allow people to kind of lay this out using a stream field. So instead we have um different bunch of different classes for pages, and it's it's a little confusing to our editors because you can Technically create more than one contact us page, but normally a site doesn't have more than one. So I'm sure there's a better way to do this, and it's uh

Speaker 1: in the pipeline for a way to figure this out But right now this is what we did. Um Yeah. So this was another so uh we have a bunch of data books in particular that we have data that needs to be displayed like on different pages. In particular, like an index page or subjects page in our case. And if you visit this link, you can see the API for our books, which uses this method to Display the data that our front end needs to to make the subjects page work. Yeah, so this was this was a little chance.

Speaker 1: Oh, and then the uh UX team wanted to be able to reorder books on this page. So I thought this was a pretty neat little thing that we did and this actually maintained the order in the API so our front end could display the books in the same order that was um Set by the content administrators in the back end. Um okay, and then this was uh issue that our JavaScript developers had. They, well, in general, you want to make as few requests as possible. And kind of with the way that Wagtail currently works This is the only way that I know of that you can get a page by a slug is to visit the pages

Speaker 1: API and follow the detail URI uh URL. So To make our front-end developers happier and to make our website a little faster, uh, we wrote this little view that just redirects um Calls based on their slug. And so that was uh very handy, made lots of people happy Um and then we use AWS for serving all of our documents and images. And uh this was another thing where we had More than one call required to get the image or document URL from the API. So this was kind of a little thing that was written to make that faster.

Speaker 1: And you can see kind of what this spits out and if you want to look at the functions that that works on that's uh at the bottom of the page and Basically you create a which I should have put an example of, but you create a method on the or a property on the uh model called team member image, and then you just feed it the image Field and it returns the AWS URL instead of having to make that double call to the API for images. This was actually a recent problem that came up is that we wanted to have shared content blocks across different books in particular.

Speaker 1: So it was really easy to come up with a way to have some shared content. We just created a snippet with these little shared content blocks. But one thing which was in the documentation but was fairly difficult for me to figure out was how to override the API for snippets to display what I wanted. So I thought this was one of the in more interesting problems that we had in making our API work Nicely. And uh this is kind of the not really related to our API, but I thought it was an interesting um Thing that happened after we upgraded to 2. 0. So it's a great editor, and

Speaker 1: It's also very important to me that as we go through the upgrade process, all of our users have a very seamless experience. I don't want them to realize that things are are changing And so we have uh advanced placement courses and those require superscript tags. So I created this little um Well, I think it's now in the documentation on how to do this, but it it's it's basically adding things to DraftTale to make it uh in the editor there. And one of the things, so I want to talk about what we're trying to do next with our website, but one of the things that that new editor introduced And that we're going to have to figure out, which kind of ties back to the beginning, is

Speaker 1: the editor adds paragraph tags around all the content, which is making life hard for our JavaScript developers. Um but I also think that just having a bunch of rich rich text fields for everything is not the right way to go. And so We're gonna try to get stream fields put into a lot more of our content and hopefully that helps with all of these issues that we're having. There's also some spacing things that our marketing people are not enjoying with the new editor. And so another thing I think Streamfields will solve. We also intend to break out some more components of our website. We have errata, which is like errors in textbooks that people are reporting currently, and it's a

Speaker 1: it's It's just kind of vanilla Django models that store all this data. And we'd like to break that into another app. Whether that's right or wrong, that's kind of the path that I see a lot of organizations heading down, is to have this very decoupled system. It makes upgrading much easier. There's maybe a little bit more of a learning curve for some developers or cross-training, but it's definitely much easier on your DevOps experience. And then a a big thing that's come up recently is content migration between our environments. So this isn't really related to being headless, but it's definitely on our roadmap for the future. We want to be able to have our production data maybe backport

Speaker 1: to our QA instance and and maybe this is something that can be worked on during the sprint, I would I'd say. Okay, so that's pretty much all I have. Like I said, the slides are available online. GitHub profile, email if you have any questions. Um or I can take any now. Hopefully that was clear. I was very all over the place.

Speaker 2: Uncle, um sorry, this is a question for Daniel here. this um I wonder when you said you use Amazon web server is to serve the static files. I'm wondering on on Divio. Can you serve static files on Divio or do you have to use an external content Delivering it.

Speaker 3: Um we can talk about that afterwards, uh perhaps, but uh yeah, I'm sure that

Speaker 4: have there been any disadvantages Just to go with that as well.

Speaker 1: Um like I said, the the developers not having the same language, that's probably the biggest thing. Like you have to You have a lot more onboarding that you have to do if you want people to cross-train.

Speaker 3: On the same subject, so using the eight guys, when you say that you can use the eight guys or using go back to like uh sort of the ones that come out of Joris framework or are you using uh sort of the page view stuff or

Speaker 1: yeah so the page view was was just a redirect

Speaker 3: Okay. And did you customize that at all or did you choose what came out of the box from Wagtail?

Speaker 1: So we did customize it very heavily during version one, because that's when we started using Wagtail. Um when version two came out, I was able to strip out all of that and we were able to use it just out of the box. So it was very nice. Yes.

Speaker 4: I may be the only person in the room who doesn't know this. So aside from a fully connected neck, what makes a site hipless

Speaker 1: So headless means that you have your database serving content through an API, pretty much. And then usually that also implies that you have an admin interface of some sort to manage the content. So the the reason for that is to allow you to not have to depend on like Well you can reuse your content along among many different things. So like I had an example, you can make an iPhone app that uses the same content as your front end or your HTML

Speaker 4: So you could have multiple front ends all talking to the same content provider then?

Speaker 1: Yeah, that's one of the better and best, I guess, examples of a Of why you would go headless. The release process is also much easier. You don't have to worry about as many things breaking. Like We know that our Wagtail instance will not go down because our front end for some reason has a bug. We know the back end will be the same and be working.

Speaker 3: Were you able to get Wagtail's preview function to work with the front end?

Speaker 1: Hmm. I think I was just looking at that the other day because initially no. But I believe I was looking at that the other day and found a way to override the The URL. Um can't recall off the top of my head, but I can get back to you on that. Anything else?

Speaker 2: Sorry, so that's one more question. So are you saying that the admin in in white tail you you completely overwrote that and

Speaker 1: No, we're using the admin just like it's intended to be. The only thing that's different is we don't use the templates. So all of our template directories are non-existent. Thanks.