Modern editing experience for your Django models with Wagtail

Hello everyone. Thank you all for coming and thanks to all the organizers for making such a great event happen. I'm so grateful to be here. So yeah, today I'm going to take you through uh how you can utilize White Tail to improve your editing experience for your Django models. and your content editors for your website as well. And just a note, um, I've put out the slides at slides. laymanage. com slash modern dash white tail. So if you want to follow at your own pace, feel free to do that. And yeah, so I'm Sage. You can find me online at Layman Age.

I'm a White Helde developer at TorchBox. Um so I'm based in the UK but I'm originally from Jakarta, Indonesia. So I moved to the UK a year ago And I previously did Google Summer of Code back in 2019 with Django, where uh when I did my uh project, which is to implement the cross database JSON field which you might have used. It's been around for a while since Django 3. 1, so it's been quite some time. And these days I'm also a Google Hummer of Code mentor and also for Outreachy, a similar program for Whitel, where we help new contributors to contribute to open source projects such as White Tail.

So I'm going to talk to you, talk through what Whiteel CMS is, its features, and how you can use it in your project. So Wiktail CMS is an open source software uh content management system. It's built on Django. And it mainly works with a base page model that combines the concepts of model and view in Django into one. So the page model is structured into like a tree structure. So if you look at the red crumbs, At the top right here, not sure if I can zoom in.

I cannot zoom in, but if you not sure if you can see it, um so the page structure uh is A three structure so it can have children. For example, the Everot page has a child for the home page, and then the home page can have another child for the block index page And then the blog index page can have like multiple children 's uh children like the uh specific blog posts. And these um tree structures will be reflected in your website URL structure. So, Wagel gives you the power to see a live preview as you edit.

In this screenshot, you can see that on the left you can edit the page, and on the right, you can edit the You can see the rendered page as you edit. And you can also have revisions for your model so that you can revert to a previous revision. Or so if you made a mistake, it's easy to revert. And you can also manage between live and draft versions of your page. So if you have content that you would like to work on but not published yet, that's possible with Vitel. And you can also moderate your content. So imagine if you have a team of editors, you can make it so that the changes to those pages

Will not go live until uh the changes have been approved by, for example, a team of moderators. And there's a lot of other features. Um Before I continue, uh I'd just like to say previously all of these features have been specific to Wagtail's page model. So we had a page model that looks a bit like this where you have like many, many fields with many, many methods. But in the past two years we've been refactoring this page model into separate classes. We call them the model mixins. Which separates each feature, like the fields and the methods required for those features, into separate classes

that are then applied to the page model Which can also be used with other models. So if you already have your own Django models, you can also apply those mix-ins without having to use the page model. So before I go into details for each of those mix-ins, I'll uh just show you how you can integrate Magetel into an existing Django project It's quite uh straightforward. You install the package with with bit install white tail, and then you add white tail to installed apps, and then you add the middleware. And then the URLs, and then you

run the migrations, and you continue uh programming So I'm going to take you to the WhiteTel docs just to show you a little bit more detail. After you install Whiteel, you will have to add quite a few apps into your installed apps setting, but not all of these are required. Some of these are optional, but for the complete Wiretel experience, I recommend that you put all of them into your installed apps. But if you would like to have a more minimal installation, you can Take some of those apps off the installed apps list. And also the middleware, which lets you manage redirects for your website through the CMS interface.

That's also optional. And settings like the static root and the media. That's if you if you already have a Django project, you'll likely already have those set up And settings like Whitale site name is just to show the website name in the CMS dashboard. And after that, you add these the URL configuration for Whitel so that you can access the Yitel admin. In this example, I'm adding the wiretel admin URLs under the CMS path, but you can absolutely name it anything else. You can also use admin if you want. But uh some of you may already use admin for the built-in Django admin, which is totally fine.

You can use both of them side by side, it's no problem Um so in this case um the YTL CMS admin is put into the um CMS path. And for the documents and pages, those are optional. Those are only required if you want to use the documents features of Wagtail to serve document files. And for pages, that is if you use the page model. If you don't, you can leave those out. So I'm going to show you what exactly will happen after you do these things. So I have a an example project where I have added the

apps and the URLs. So let me just so I have a very very simple website built with Django where I have an index view and a detail view for these Product objects which I've created with some toys from Toy Story. And I also have the Django admin to manage these models. And after I installed WhiteTail, I will now be able to access the WhiteTail admin through slash CMS. And I can sign into WhiteTail using my Django user.

Although at this point it's still very empty and I will have no access to the product model that I already have because I haven't registered it with the VicL admin. So the next thing that I want to do is to register the model with Whitetail In Wagel for non-page models, we register them as snippets. The term comes from the fact that Other Django models tend to be used for including including smaller pieces of content as part of your pages. Hence the name snippets, although it doesn't have to be something that you put in your page model. It can be it can literally be any model that you have

So the very simple method to register a model, a Django model to Wagtail is to add the register snippet decorator to your model. And once you do that , let me just switch to the code. Once you have registered the snippet, and you would also want to Specify which fields you want to be editable in the whiteL admin. This is optional. If you don't do this, then all of the fields will be will be editable in the admin And after you do that, if I reload the page, now I have the option for

snippets. And if I go there, I have the products. Model and I have all my objects in here. So out of the box, this is what Wikel gives you with your existing Django model. If I try to edit one of these , And you can see that the fields are rendered in this very nice interface, and I can collapse and expand each field. So if I don't care about all the other fields, for example, if I just want to edit the description, I can collapse all the fields and just edit the description, which in this case might not feel very different, but if

imagine if you have a very, very long form , this will help you quickly navigate through the form. And we also have the minimap, which again lets you jump quickly through the fields that you have in your model. And for example, if you have errors in your form, like for example, I'm trying to input a negative discount. And I try to save, there's an error, and the minimap tells you exactly where the error is, which again for very long forms this can be very, very useful. And there's the state of site panel, which tells you when's the last time it was edited.

And Also, if the model has been referenced in other places, you will also have access to a list of those references. But I don't have that at the moment, so I'm just going to continue. So the next thing I want to show you is the live preview feature. So this feature comes from the previewable mixin class. And to use it, you can add the class as one of the superclasses for your model, and then override the get preview template and get preview context methods To point to the template file and any context variables that you want to add. And you can also have multiple preview modes, for example, you

Okay, uh you might want to preview the object if it's rendered in an index view or if it's rendered in a detailed view, for example. And you can customize the context and templates accordingly. So I'm gonna show you how it looks like So in here my model has the previewable mixin applied with the preview template and preview context configured And now if I go back to the CMS , I just reload the page. Now I have this pre-view option And if I click on that, it will give you the preview panel.

And as I edit the content on the left side , for example It updates on the right side automatically. And so on. So I can imagine that this is very useful if you have If you have a team of content editors and the data will be reflected on a live page, this is very easy to preview what those changes will look like. um without having to actually do the changes and making it live on your website. And yeah, you can have multiple preview modes.

And you can also see that the preview panel has this different screen sizes Although I didn't have time to put up with a better HTML template, so you couldn't really see it. But yeah. You can also access the preview in a separate tab. So that's also an option if you want. But yeah We find this me personally to be very useful, especially when you're working with a model that Would be rendered you can think of it as some kind of a storybook for your Django models. And I'll continue to revisions. So with refusations

, you can import the refusion mix-in and then just add it to your model, run the migrations. And once you do that, if I go to Branch. I just apply the revision mix in and I've already run the migrations before. So now if I try to edit this And for example, change the discount value. And I access the history page. I can compare with previous version And it will tell me the exact changes that have been applied to the model. And I can also refer to a previous version

For example, I'm looking at the previous version where the discount is the original version and I can replace the current version with that previous one. And the next one is draft changes This lets you have changes that are not immediately reflected on your model , on your model instance. So if I apply To do this, I just import draft state mix in, apply it to my model, run the migrations, and There's also an option for you to have scheduled publishing so that the changes can be scheduled to be published at a specified date or time

And to do that, I'll just add the publishing panel to one of the panels that I have defined for the editable fields of my model. And once I do that, if I reload the page again , now the save option changes to save draft. And I have other options such as publish and unpublish. So if I make changes here, like If I change here and I click save , the next time I access the same instance in the admin , It shows the updated version, but on the website itself.

Sorry. It still shows you the previously published version So this is useful if you have changes that you are still working on and you want to save but you don't want to immediately publish th those changes. And as soon as I hit publish here and I reload the page It's updated. So it's very useful if you want to have such draft changes. And I can also unpublish this instance, for example. And as soon as I go back to the listing, it's gone

because I also have added in my views to filter my products to only those that are live. So that's for draft state mixing. And the next thing is locking, which lets you lock an instance to prevent multiple users from editing the same instance at the same time. You can do this by inheriting from lockable mixin '. So if I just switch to So I added lockable mixin to one of the mixins for the product model and random migrations. And after I do that, if I

try to edit one of this, I now have the option to lock this model. And if I lock this, I can still edit this because I'm the one who locked it. But if I switch to a different user and I try to edit the same instance I'm and I I am uh well I cannot do that because um it's currently locked. And if I unlock the instance I can now edit again. And you can customize the permissions. In this case, this user has no access to lock the instance. That 's lockable mix in. And next

the workflows. This is quite a complex feature, so I'll probably won't go into details, but In WhiteL, you can have moderation for your content so that the changes will go through different set of steps that you can customize depending on your use cases. Uh before the changes go live. So to do this, uh you inherit from the workflow mix in. Uh I'll just switch to workflows. Okay, now I I've added the workflow mix in. And the next thing that I will have to do is to go to settings workflows.

So by default, WhiteTal gives you one type of workflow, which is the moderator's approval. Which takes your model through one step, which is to be approved by the moderators group But again, you can have separate uh you can have multiple tasks if you want. And in this case, for example, you might want to uh have uh a different group to approve the changes before it goes live. But you can also have custom completely custom tasks such as having a specific user to approve the changes before they go live and it can also be completely different

Tasks. It's entirely customizable. And the thing that you want to do is to assign the workflow to the model. And once you've done that, if I try to edit one of these. Oh, actually, I'll use the other user. I now have the option to submit to moderators' approval. And I cannot edit the instance while it's in moderation, but as a super

user or a moderator, I can See that it's currently in moderation and I can approve this. And before I do that, just make sure that Um the model instance has not changed, but if I approve this and publish, it will be updated. So that's an example of workflows. And finally , you can also customize other parts of the admin, for example, the listings view. You can see that this is a very, very simple listing view, but you can kind of customize it similar to Django's model admin.

So using something that we call ViewSets. You can create a snippet viewset subclass, specify the model and like things like search fields. uh the displayed columns and you can also export the instances to a spreadsheet and you can also specify the filters and After you register the snippet model with this view set, you will get a more complex listing view that you can, for example, download the spreadsheet. Or search or have filters like yeah, um

That's an example of customizing the admin view, but you can also customize specific like the edit views or its templates to add much more complex use cases. So yeah, that is it for me. Thank you. If you would like to learn more about Wagtail, go to wagtail. org. Slides are available at slides. laminage. com slash modernwagtail There's also the code example on my GitHub. If you would like to have any questions, feel free to reach out to me at laymanage. com. And that's it for me. Thank you.