Wagtail CMS/Django 4.x deprecation, adding featured events to the HomePage

Hello and welcome to this recap of today's open source live code hangout. Today we've been working on the Western Friend website on a couple of issues. Go ahead and review these issues and the code involved in resolving them. The first one is uh we recently upgraded Wagtail and Django to their re uh 4. x uh series. These are new releases from both projects. Wagtail I think is mirroring the Django release in that sense. And after upgrading, we uh there were several deprecation warnings in the uh terminal saying that in Django 5 or Wagtail 5. We're removing these features, so here's some time

you have to resolve them. They looked like that, not very entertaining, but what we did today is just kind of go through each of these and and um figure out what it was needed to fix it. They're pretty straightforward. Take a quick look at the code here. Most of these are just the same thing over and over, so I'll try to skip over the things that are the same. Basically, we altered a bunch of fields and in order in order to do those alterations in the database, we needed it to generate some migrations. So All these migrations are relating to a Wagtail field type data type called stream field, which is essentially a JSON. field that

lets you store semi-structured content. These can be various types of blocks and you can assemble a page with these blocks like headers and uh headings and target uh like with uh various attributes like a target and so this migration is basically altering this um stream field to add some um behaviors. We'll look at the actual field definition. Typically we don't have to worry about the migration code that's automatically generated So we basically went through all of our models and in the case where we had a stream field, we have to explicitly tell it whether or not to store the stream field data as JSON. previously

was storing it as kind of a text a big text blob that would get um s uh deserialized or somehow parsed into python list and now uh the json um gives uh the ability to have some improved uh ergonomics when you're querying within a stream field. So I opted in to use the JSON representation However, on the local development, we're using SQLite, which doesn't have this JSON field. But fortunately, Django gives us the abstraction or Wagtail somewhere in there that it just worked. um so I'm glad for that. Didn't have to um start up a Postgres container in my local development environment. And uh the other big change, these are just gonna be repeated, is

Wagtail is auto-generating editing forms. It's a content management system. You define your content types Typically they are defined as Wagtail pages. Pages are a hierarchical data model where you have a root page and that page can have children and those children can have children. Although you can also define Django content types, which are just any arbitrary database table and fields And Wagtail handles the magic of generating an editing interface that the content managers can use. It looks something like this. where you have fields and those fields have representations. We'll get into this particular content type in just a moment. But in any case, for some of these more complicated fields, prior to Wagtail 4, you there are some specific field types.

uh such as the stream field um type because of the nature of stream field being an like a nested list of of JSON essentially now They wanted special handling, but Wagtail 4 now has rolled these features into the regular field panel, which means our code base is simpler, developer experience is simpler, everything is basically a field, Wagtail figures out uh how that field should be rendered without really the developer having to think much about that. So that's a nice improvement. So this is one model that we made those changes to. Django 5 will be deprecating this use LtN or localization setting and Django 4 is defaulting this value to true.

So since the default is currently true, meaning that Django will automatically localize any content that's rendered into the template. um we can just remove this setting and set ourselves up for Django 5 which is uh I don't know when that'll be released but any case we're ready for it at least at this stage of um deprecation And the other Wagtail sort of notification or note in our terminal was that we needed to define this variable, which is basically where you access the Wagtail admin screen. It's a bit bright there. I'll just do it half half size. So we did that

and that will help for some other features. Such as uh email notifications. Great, that was done. Again, that's a migration. I'm gonna go try to go through these a little bit fast. This is just switching stream field to field panel, cleaning up imports, switching stream field to field panel. That was good. Another migration. Gonna kind of skim through these, setting the JSON field, switching the uh stream field to field panel Migration. I should have minimized the migrations before we did the review. These are formatting changes from our Code formatter, migration, image chooser. So this is another example of a complex block type for multimedia handling that typically need

that historically needed its own class and block now that's been rolled into the field panel so field panel is getting more re robust. We also have a stream field here so we're making the same changes relating to that. This is one of our more complicated models in the magazine section of the website. And this code, as you can see, is all open on GitHub. We are an online magazine publication and community platform. So with e-commerce and a bookstore. So if you have any of those type of features and soliciting donations, uh Feel free to check out our code and see if it suits your needs. Skip through these stream field field panel Uh then I did run an update on all our dependencies just because we're still in

um sort of a really Beta mode, so I'm just keeping everything up to date. I think that's it. So great. Um you know thousand lines change mainly because of the poetry lock. There were several updates that ran We got rid of all of the deprecation warnings from Wagtail and a couple that were in Django that I didn't originally capture in the related Issue. So since this didn't need any kind of peer review so much, I'm this I'm the only developer here. I just went ahead and merged this one. Now let's take a look at this latest feature. I'm gonna do this so it's not quite so blazingly bright. The website, as I mentioned, has several features. It's a community portal

and one of the features is to display events, uh community events, like meetings or celebrations. Um and not quite a calendar, but it's sort of like an events list and uh those events have some attributes. an event title which is everything in Wagtail as I mentioned is a page and whether or not that event is featured and I'll just show you what we ended up with. We Previously had to manually specify on the home page which events to feature. There's a little section there and you could display up to like three events. But now the editor, so the editor would in that case create an event, then visit the homepage, then edit the homepage, then remove an event that was featured if they were already full

like three previously selected events and then add a new one. So there's a bit of manual process there. Now the only step that's needed is the checkup box. So it's still a little bit manual. That means that the editor can choose which ones should be featured and they will automatically appear on the home page. So we'll look at the implementation here. In a moment, I'll just mention this is a plain text field. Wagtail chooses the right widget here. This is a stream field. It's a composite of multiple uh potentially complex um fields including multimedia I mean it's it's pretty powerful with like modal choosers and upload it's very nice all this is just done with WagTil I define like one line of code

More or less in the stream field body. Uh we get date choosers with I mean it's just such a great um Content manager. I I can't recommend it more. Really, if you're starting out a new uh project that has a need for a content management system, uh Check out Wagtail, you know, compare it with the established WordPress and other content management systems, but I believe not only is the user experience in it's exceeding, I believe, even WordPress now. Uh and the developer experience is top notch, especially being built on Django. So let's just take a quick look at the home page as I've created several events as you can see here in the events listing created three events

one in the past Today is October 5th, 2022. One in the future. And one in the future. Ish. It's not so far away, but still. So I can say you can see that WagTiel actually admin interface also generates all of this. I just tell it what content to render and then how you know which fields to generate filters on. All of this is done by Wagtail. Really cool. But I don't want to go too far into the details of Wagtail during this. live stream summary. So when we go to and this is the admin homepage from earlier, when we go to the front page, now we see

the Front page looks like this. I can edit the title and add some rich text. And you can see it's really taking notes from the Gutenberg text editor, WordPress Gutenberg. You can add rich multimedia, upload things all within uh this uh block-based editing interface. When I view the live homepage you'll notice there are no events here. It's just a welcome and an intro So the page title and intro text. When I view it live, we have the page title, the intro text, and a current issue, which is not really doing it justice. This will have a an uh issue cover photo and some other information, but Below that is the featured event section that's displaying a number of featured events. Notice that these are in the future

and they were both when I added them I toggled that featured event. um checkbox. Let's quickly look at the code for this. It's pretty straightforward though. So after some discussion we decided to make the featured events more user friendly from the editor, the content management perspective. by sort of automating most of the wiring to the front page and just adding a checkbox. So didn't take many lines of code, about 20 minutes of coding I think. So again we've got a migration here where I've altered the I've added a field to the event model and that looks like this. Here's the model for the event. I've added this is featured field, which is a Boolean.

It defaults to false, so it's true or false with a default value. That means you have to opt in to the um Events being featured. Added a little bit of help text here. I believe that help text is on the events Add event, it's yeah, gonna just give you an indication what this means. And we're using our famous field panel To and it just knows that it's a Boolean field, so it needs to render a checkbox. Well that's handled by Wagtail for us. Uh then we migrated the home page model, which is a instance in a row in a table in our database. This was a little bit more uh complex it would change but basically we've got to remove a bunch of um

things That were no longer needed. First thing I had this join table where anytime you have a many to many relationship in a relational database system, you'll typically define those relationships by adding an intermediary table that takes the ID of each of the related entities and stores them to make that connection. as opposed to just having a foreign key field on one one entity or the other. Which would be like a one to one. Or many to one. And in the case, uh homepage featured event used to be an orderable where when you were editing the homepage, you would be able to Manually select those events and then change the order of them. It's a pretty nice feature of Wagtail when you need it.

We are using it elsewhere in the project, but we no longer needed it here, so I removed that table. And um an inline panel means that you can tell Wagtail when you're editing a particular entity or page in this case to a lot to display related entities. as if they were kind of part of this entity. So when we're editing a home page, you would see inline this featured events orderable, which could be up to a um I think just any arbitrary number of events we didn't have a limit it looks like. So it's like a chooser, you add zero or more. We removed that though because we're making the user editing experience simpler. And the import here I had imported the date time

and the event model. And apparently the page model, I'm not sure why. But um so this is going into the Django territory when you're um Wagtail pages are essentially Django uh um content. So in the and this is actually pretty scattered In the homepage model, we have this git context function that gets called when the homepage is rendering. What that does is prepares data to be rendered into the template. And we'll get the default context from the based on the request in the super class, which is the page model, and we're going to add a couple of variables to that.

Previously we had this variable here to add the current issue, which just grabs the one of the magazine issues that's been published, most recently published, grabs the first one of those. For the f featured events, we basically did a very similar thing. Event objects, I should probably make sure that they've been published. The editor may want to draft them. I just realized that That's what this live does. It makes sure that it's it is published. Wagtail adds this publication workflow that isn't bail um built into Django by default So I'll probably change this to objects live and I'll want to filter those that this to where the start date is greater than or equal to now, basically they're

today or later. And then order those by the start date. I think that probably is the default. They're probably already automatically ordered by that, so this is probably unnecessary. And then select only three of those. and return the context so that it can be rendered into the template. And all we do in the template basically is had to do a little bit of rewiring. The featured events was previously a member or property of the page, the home page, but now I've moved it into the template context so it's it can be referenced just by name here sort of and if that um if there are some featured events if that query returns some results we're gonna render those

in a section, featured events section. We're gonna loop over each one of those and and display it in a card. So that's more or less it. I didn't actually write this during this session today, but it displays the event title, start date, formatted way and the time zone and the teaser texts so that there can be a brief um description if that's available to give more information but not display the full uh event description. So that's it in a nutshell This feature is uh this pull request is still marked as draft. Even in this review, I've noticed at least one change that I would like to make, and I'm gonna get some feedback from the editor, the magazine editor, Mary Klein

to see what her thoughts are. One improvement that comes to mind is that we might want this number to be configurable up to five, say you could display up to three or five. So that would be a feature or a property I could add on the homepage. And again, I probably only want to display live events just to make sure that the editor can draft future events. And you know, take advantage of the Wagtail publication flow. Alright, well this has been another uh open source live code hangout. If you'd like to get involved with this project, you can stop by github. com slash westernfriend or stay tuned on our stream here and I'm also working with a couple of other open source projects.

one of which is CiviWiki and we are trying to line up a bunch of good first issues uh for new contributors to take as part of the Hacktoberfest initiative where you can win or you get some kind of rewards for contributing to open source projects. Alright, thanks a lot for your time and I hope you're doing well.