5 Things I Learned About Wagtail the Hard Way - Meagen Voss

Speaker 1: All right, everybody, thank you for uh tolerating that bit of uh little computer snafu we had there. So my name is Megan Voss and I am new to Torge Fox. Fun fact, Megan is an Irish name. It means I burn in the shade. So I'm going to talk to you today about five things I learned about Wagtail the hard way. So I just want to give a shout out to anybody who's new out there who's just starting out because I've only started with Wagtail probably about a year and a half ago. And here I am already giving a talk. Like your contributions to this project, they matter. So definitely your experiences as a newcomer are things that we want to hear about. So definitely uh

Speaker 1: Pay attention to what you're learning as you go on and write them down because these are things that are going to be invaluable to the people who come after you. So today I'm going to assume a couple things about who uh about like you as my audience. So This talk is for some folks who probably have some familiarity with models and views already. You've tried building a simple Wagtail project and you have some basic familiarity with cloud hosting already. If you don't have those things and you happen to be watching the recorded version of this talk, feel free to press pause now and head over to Wagtail. org. slash play that will open up a instance of Wagtail on Gitpod

Speaker 1: for you and you can play around with the code, get to know the documentation some, and then you can come right back. And we can dive into some things that'll help you successfully launch a new project in Wagtail. So the takeaways that I want you to have from this talk is I want you to have a better understanding of how Django and Wagtail work together. As well as I want to give you some practical high-level ideas for building and deploying your first real project, not a tutorial, but your first like real live on production project. And also to give you some ideas of what you might want to spend your learning time on, because like none of us has a ton of time. We're all very busy people, so I want to give you some ideas for how to focus.

Speaker 1: So if you're a more experienced developer, maybe you want to grab some coffee right now, or if you want to take a trip down memory lane and kind of relive some of the things you probably learned the hard way too. Let's go ahead and dive in. So first a bit about me. I have a background. I actually started out as a research scientist and kind of wound my way. uh through a writing and marketing background into tech. And through that I became a person who was very interested not just in the tools that I was using for writing, but what actually worked underneath them So WordPress was my gateway drug into programming and uh also open source. And it was definitely a great entry point. And I don't regret any of the time I

Speaker 1: And I still very much love that project. However, I wanted to have some more control over the project structure. I was getting a little tired of kind of hacking WordPress into doing things. That it really wasn't designed to do. And so some of the reasons I came over to Wagtail is that the tutorial that the Wagtail documentation presented was very practical. Right off the bat, it's telling me how to build a blog It's not showing me how to like build a polling app for ice cream flavors or something like that that I'm not going to reproduce in a real server somewhere. Also, the community was super helpful and the it like ultimately like when I looked at Django versus Wagtail, I'm like Uh, you know, there I don't really like the idea of having to build a back-end editor from scratch.

Speaker 1: Why do that when this is kind of saving me the trouble already? And so that's Some of the reasons why I came to Wagtail, these are some of the reasons that I hope you come to Wagtail. And even with all that. So whenever you start doing a new technology, there's always like some little tutorial that they give you that's kind of gets you pumped up. And it kind of like they teach you kind of how to pitch a tent. And you know, and you feel really great that you pitched a tent. But then when you start looking to build your first real project, it's suddenly it's like, oh my gosh, I have to figure out how to build the Death Star. You know, it's like it's going from pitching a tent to building the Death

Speaker 1: Star, like one's on Earth, one's in space. You know, it's it feels completely and totally different. Especially when you have a relatively new open source project like Wagtail, where there might not necessarily be a ton of blog posts out there yet. And it's definitely changing. But it feels like kind of a new frontier for somebody who's new being and trying to figure out how things work. So with that in mind, like because this is how I felt, I felt like C3PO dumped in the desert many times when I was learning Wagtail over the past year. And I definitely felt like there were there were times where I'm just like, why am I spending so much time figuring this out? Why do I keep going?

Speaker 1: And the, you know, the answer is ultimately because I want to make this better. at the end of the day. And also because the community was right there to help me with some of the toughest challenges I was facing. But also I wrote this talk so that you could probably learn from some of the things that I learned from pushing a website to production for the very first time. All right, so let's go ahead and kind of dive into the five things that the five major things that I learned over the past year. The first is kind of how Django and Wagtail work together. So when I first came to this project, I kind of had this idea in my head that Wagtail and Django were kind of like these nesting dolls, which I will call Ukrainian nesting dolls for reasons.

Speaker 1: And so I thought that Django kind of fit inside Wagtail and that I would never have to deal with Django. Not at all. Yeah, that was completely and absolutely wrong. You know, Django and Wagtail more exist kind of side by side and work together in like this kind of nice coexisting manner. And one of the examples I'll use to illustrate that is kind of this issue I ran into of the Phantomexample. com. So I was installing an authentication package called All Off. It's probably one that many people in here have used and many people online. It turns out when you turn on the multi-site function in Django in your Wagtail project that it introduces some interesting things.

Speaker 1: in terms of where it pulls data from. And for this one, it was in the email authentication part where like a user was getting a confirmation email that they signed up. I could not for the life of me figure out where this example. com was coming from because I had in my Wagtail site settings no example. com. I had the real site. name in there. And it took me forever. And I finally put a question in on Stack Overflow, which Matt graciously answered. And it turns out that there are two admins. And I had no idea that there were two admins. This seemed kind of like lunacy to me, but the more I thought about it It actually does make some sense because you don't want to get rid of the benefits of Django

Speaker 1: to make way for or try and duplicate everything in Wagtail It was just one thing as a beginner that I didn't know that this was also here. And so now you know, and if you ever need to navigate to the Django portion of your installation, you should go to slash Django admin. And sure enough, when I went there, I found the offending example. com and made it go away. So that was one of the things I learned the hard way about how Django and Wagtail work together. So one of the big things that I definitely want to take you away, this is the one that almost made me run for the hills as a new developer, is the customization of models.

Speaker 1: So I kind of made this silly decision to learn Django and Wagtail at the same time and also to mostly dive into the Wagtail docs first. Turns out you miss a couple things when you don't read the Django docs, like custom user models. Which is something that for a new user is completely something I wish I knew about earlier. We'll get into the details about that in a minute. But so custom models are models that are custom. customized versions of existing Django or Wagtail models, they give you the option to add specific fields to your project and kind of the big three that I wish I had known about were the user model, the document model, and the image and rendition portions of the models.

Speaker 1: So Let's explore a bit. So why would you want to customize these models? And why would you want to customize them kind of first thing in your project? Because I wound up doing it in the middle of my project versus at the very beginning. And here are some of the reasons. First of all, in the Django docs, which I didn't read first because I read Wagtail's docs first. It says that it's highly recommended to set up a custom user model, even if the default model is sufficient for you. And the reason for that is if you don't need it now, you might need it later. Like you don't know in the lifetime of your project how far when when you're going to need it. And if you don't make it now, it's going to be a bigger pain in the butt to make it later.

Speaker 1: And so it's not impossible. Migrating to a custom model in the middle of a project involves a manual data migration, though. And that is not an easy process for somebody who is new. And I definitely was kind of tearing my hair out. Unfortunately, it was with a database I didn't particularly care about, but if you're working with a project with something you care about That's a whole different matter. And one of the reasons I discovered for why this is something that continues to be a bit of a struggle is Django Ticket 25313. This ticket has been open for years. years. Like this this this this is a problem. The the idea of switching to a custom user model in the middle of a project is something even some of the biggest minds in Django haven't figured out how to solve yet.

Speaker 1: So as a beginner, this is not something that you really want to tackle. You should definitely set a custom user model as soon as you can in your project. And I'll share a link later on for a tutorial that shows you how to do that. Also, similarly, you want to definitely consider customizing your image and your document models uh as soon as you can. Currently the alt text and captions aren't included as default fields and Wagtail. There are very good reasons for this. which I'm not going to go into because that's kind of outside the scope. We definitely like I appreciate the flexibility that Wagtail gives everybody, but this is definitely one of the more common things for newer people. uh that tends to throw them

Speaker 1: is the idea that these aren't included. And if you change your existing site to a custom image and document model, Like ever every image or document that you already have in your site isn't going to be copied to the new model if you switch it in the middle of a project. Again, you'd have to do a manual data migration for that. So save yourself that headache, you know, avoid that manual data migration, customize those models as soon as you can if you have a project that needs that very like I'm sure there are probably some projects out there that probably wouldn't need the full customization level, but it's definitely, I can't think of many that wouldn't, to be honest.

Speaker 1: So let's move on to kind of the third thing that I wish I'd known as a beginner, which is creating a base page model in your project. It saves you a lot of grief because it helps keep your project dry. It keeps you from repeating things. And so there will be mix-ins and other things that will apply to all of your pages on your site and having a base page model that you can kind of add those things to makes it easier for you to keep things organized. One common example and one that I've used is for the metadata or SEO packages that are out there for Wagtail. Usually use a mix-in. And so that's a good use of a base

Speaker 1: page model. And I and one thing that I did catch with doing that is that there are sometimes some template tag conflicts with certain packages like all auth. So this is definitely something you want to test pretty thoroughly, but it's a very useful trick. And so just to show you a quick little code example of how that works. On the left here is a base page model right here where you would have class base page and then you'd add in all the things that your pages have in common, such as the metadata page mix in that I have here. And then you can go ahead and call that base page page into all of your other page models. So this example here on the right of a news index

Speaker 1: page I have for one of my projects just goes ahead and calls that base page. And every every page that uses News Insex page will pull that metadata page mix in with no problem. Well, I mean there might be problems, but that's a whole different thing. So when I came into uh Wagtail and Python, I kind of got away with this kind of uh My process used to be kind of, you know, code, local test, deploy. It was very linear. So one thing as a newcomer to both kind of cloud the cloud spaces and also Wagtail and Django is that. I thought, oh, I'll just build the whole thing and deploy it all at once.

Speaker 1: It turns out that is not the most efficient way to manage these types of projects. I uh definitely learned and highly recommend that folks who are new to these types of projects consider deploying early and often like as soon as you get your project like get it onto a test server like there's some very great Uh you like going you do not want to like get all the way to the end and deploy the whole thing at once because it becomes like too much to troubleshoot at once. It's better to troubleshoot in smaller chunks. And so adopting a circular mode of deployment is something that I definitely learned from this and something you should consider especially if you're going to wrangle a digital ocean droplet

Speaker 1: so that is uh something to consider All right. So the last thing that I highly recommend is surrender to the idea of learning Django forms. That is one of the things that I wish I had known ahead of time. For most projects, the Wagtails Form module will provide like some very useful features, but it's most likely not going to be enough for every single project you do. Many will need some more complex forms. And so especially if you want to take advantage of the permissions, groups, other features that Wagtail Forms doesn't currently support. And it's a pretty huge learning curve for Django forms, but it's definitely one that is worth investing in. All right.

Speaker 1: So just to give you a quick recap here and give you folks who are at home time to screen cap this, this is kind of a summary of everything I've gone over here. Definitely like remember Django and Wagtail, they exist side by side. Plan and troubleshoot accordingly. Make your custom models first thing. If there is one thing that I want you to take away from this talk, costume models, number one, do that first if you can. Consider creating a base page, deploy early and often, and definitely invest some time in learning Django forms. I'm also going to go ahead and share kind of my recommended learning resources for people who are new to Wagtail. I am infinitely grateful to these folks for helping me get through a lot of my troubleshooting.

Speaker 1: uh learn Wagtail by Caleb, uh Python Eats Tale by Smalls Paul Smith, the Wagtail Tutorial Series by Michael Yin. He's a Chinese developer and I did some DevOps learning with him. Highly recommend his stuff. And also a great course on Django Forms on LinkedIn learning by Nick Walter. You should definitely consider that as well. And for the screen cappers here at home, here are some tutorial lists that might be useful for you, including that mid -project custom user model switch from Cactus. That one was a lifesaver. I could kiss them for it. They actually are down the street from me, so I probably could go do that. Anyway, so those those are kind of the things that I learned as a new person.

Speaker 1: I hope that what you get out of this talk is that you feel, you know A little less like you're going from pitching a tent to building a Death Star with your first drill project. Maybe now you feel more like you're building it going from building a tent to building the Millennium Falcon and hopefully it's a bit more manageable. All right. So I am fortunate to have joined Torchbox as the new partnership and community manager. So I'm going to be taking some of my learnings. uh from my Wagtail experience and applying that to future community work. I also invite anybody out there who has had similar experiences. Please send me your ideas. You can reach me at meginvoss.

Speaker 1: com on Twitter at Meganvoss, and I am also on the Wagtail Slack MeganVoss. All right. Thank you so much, everybody. Really appreciate your time.

Speaker 2: One question so far. How do you make it clear that Wagtail is built on top of Django and that Django always applies. Should Wagtail docs duplicate concepts from Django Docs?

Speaker 1: So there's a question here about uh how do we make it clearer that Wagtail is built on top of Django. And is there, should we duplicate some of the concepts from Django Docs? So fortunately over the year and a half, so when I started, this was before there was a sprint to focus on documentation And so a lot of the issues that I faced over my initial beginning have actually already been solved with some of the improvements that have been made to the documentation. I think we probably could do a better job maybe with some warning labels around the custom user model and also the custom model documentation. Those are kind of the like kind of those those big teeth grinding issues maybe are worth duplicating.

Speaker 1: But I definitely don't want to get into a situation where we're maintaining things that Django is already investing time in. Question from Vince.

Speaker 3: Yeah, similar to the question. Usually for newcomers, I would recommend uh go through the Django tutorial for content. the website tutorial. Um haven't gone through this recently recommend that or if the web tail docs is not good enough.

Speaker 1: So the question is should pe newcomers go through the Django tutorial and then go through the Wagtail tutorial? afterwards. So kind of what's the order of operations. I don't think I would have caught most of the issues that I experienced in the Django tutorial. I think what I found With the Django tutorial, the way it's written, it didn't just it like it didn't appeal to me as somebody who really wanted to build a site right away It just kind of felt like kind of what I call a cute tutorial that is great for showing you some basic concepts, but it doesn't really apply to a real world thing. So I think it really depends on the type of learner that you're looking at.

Speaker 1: If it's somebody who has the patience, uh definitely recommend doing the Django thing first. But if it's somebody who really wants to get in and just like build a real thing right away. I feel like the Wagtail tutorial has gotten solid enough that it it 's it it's definitely like going to be the choice that I would make first. So Any other questions