Atomic Wagtail by Kurt Wall

Speaker 1: Come on, no.

Speaker 2: Thanks for coming to listen to me talk and you know stake stick here for the you know the end of the all the talks and Uh thanks to you know Torchbox for making Wagtail. It's a wonderful piece of technology and it's the reason why I'm standing here. So show of hands, who knows what Wagtail is? Other than what? Vincent just said, okay, that's great, great. That's actually a lot more than I thought it would be. So for those of you that don't know, Wagtail is a pretty new open source Django CMS created by Torgebox. And it basically provides this sort of groundwork to build your own CMS, and that's in quotes because it it gives you a lot of things that a CMS that you would expect from a regular CMS, things like

Speaker 2: a like a a great admin or the ability to uh have a publishing system, uh really anything like a a way to manage documents, images, things like that. But I like to think of Wagtail as something that's made for the developer, the designer, and the content enter. There's a lot of CNSs out there that really only focus on the either like the development side or on like the editing side, but I I I find that Wagsail does a really good job of combining all these great components that really should be relevant in a CMS So why should you use it? It's really customizable. Uh I've extended the framework, well, the the CMS on numerous occasions doing weird things and it's really like Hell

Speaker 2: fast, it's really not a big deal to really extend even some of the most crucial uh components. In fact my last projects uh I had extended the uh publishing workflow uh to add a staging site. So normally you'd have a draft state and then it's on and then it's published. I've added a staging site to that entire workflow. And that didn't interrupt anything about the other components of Wagtail. There wasn't any weird things I needed to take care of. It was really easy in that way. And it's got some really great features. Unfortunately, I can't talk about all of them, or even most of them. Actually, there was another Kurt at this conference that talked about Django Forms. in which you kind of think form think about forms as data and in which you can build them dynamically instead of static way as we would normally.

Speaker 2: And Wagtail does kind of use some of this and that's just kind of part of what they what Wagtail offers So uh and you know I could go into it but there's a lot of great things that that uh Waxwell offers. And it gets out of your way. Uh everybody always likes to talk about how like developers are lazy, right? Like we Like we want everything done for us. We don't want to be we don't want to do anything. We just want to like write import essay, right? Like we don't want to write the thing. We just want to be able to use it And I think that Wagtail has this like I think I added a caveat, right? I think Wagtail does this well, where it gets out of your way, but then it provides all these features that you'd like. So yeah, we're lazy that we we'll we want to be lazy, we don't want to like do anything. But we also like We also want it to like provide us with the things that we want to do. So

Speaker 2: sorry, we want it to get out of our we want it to get out of our way and and just you know, let us do what we want to do but also provide the features that we want. It's also got you know Jinja 2 compatible templating as as well as Django. Normally you'd probably use Django unless you had some sort of reason It's got built-in Lastiarch integration. So there's a bit of setup that you have to do to achieve like a really good workflow or really good search uh capabilities with this but it's really not much and it and if you've never heard of or used elastic surge I definitely recommend it it's a really great uh uh really great surge engine well it's more than that but It's easy to integrate in existing projects.

Speaker 2: It's not really something that works on top of Django and more about on like beside it. So you put it in your installed apps and you're able to create a, it's you create your own sort of CMS, and I'll explain how you can create ways to create content types. later. And it's not going to interfere with any of your other Django apps. And you could really only have a blog that's powered by Wag, so you don't have to have a one project that has to be powered by Wagtail. It's not like that at all. And it lets Django be Django. And this is like a really important thing. And I think in the mezzanine talk uh he had mentioned this too. And I think uh I I haven't had so much uh uh experience with mezzanine, but I found that Wagtail does this uh

Speaker 2: does this very well Uh so some caveats to how great this, you know, how great Waxville is. It's not exactly your name your normal Django flow in terms of how you, which is a bit contradictory, I realize. in the way that you think about how uh things get served, right? So you think of the way that a request comes in, it goes through The normal path and you end up this views. py where you're where you're returning this result. And in a and I don't know if this is a bad thing or a good thing. I I think it's pretty good where they have this this generic view function in which it calls the uh the class in which you've created to render to the uh uh uh to to render uh as the web page

Speaker 2: and it gets the context and packages all up and then through that generic serve function, that view function, it will give you that uh it'll it'll give you that web page. So you don't have to do anything. You could have an entire Django or you could have an entire Wagtail project, entire site without ever touching these dot pile And also the documentation documentation is pretty good, but it could be a lot better. I found myself like coming across things, or at least when I started it. That were fairly easy to understand, but I didn't know and it took a long time to actually get to that understanding just because it wasn't in the documentation And then there are a couple admin quirks, but I hear really good things about them being uh that being updated. So let's just talk about some features real quick. So the page

Speaker 2: model, which is basically the bread and butter of how this is going to work. And like I said before, it's got this built-in publishing workflow. And I guess I should back up a little bit. Page model, it is a Django model. They add a bunch of really awesome functionality to it. And then when you want to create your content type It is something that you inherit from Page, which you can see in code. It handles all the relationships between different pages. So it is like a child page. uh of a parent page or you can like get the children of this page, you can get the ancestors or the descendants. It's a really useful feature. And that's actually something they achieved through a different package. uh called tree beard. I don't really know what the relation is with that, but you can look into that on uh on your own. So it handles other things like moving the relationship from one parent page to the other, copying the page, scheduling

Speaker 2: f publishing so you're not having your content editors wake up at midnight just to publish some press release. And uh and and it's got automatic Wagtail admin registration And I just want to underline Wagsel admin because it's not something that you're automatically registering in your Django admin. But anyway, so this is like an example of all you need to create a page type, a content type that you could add to your site and visit as a web page. So you go And you would in your models. py or wherever you're going to put this model, inherit from page, and then you can add even a Django model field, a date field, and then their own built-in rich text field which is really just a WYSIBYG editor and then in order to show these in the actual view that you're going to see

Speaker 2: you're just going to uh uh declare these content panels, which is just a list of these field panels, and it'll go in and detect what type of field that you're using and then render that appropriately. Uh so Streamfield is really the big win, in my opinion. I think this was one of the things that most attracted me to Wagtail And it's to me I uh just disclaimer, I don't work for Torchbox by the way. I just really love Street Feel, I really like I really really like Wagtail and I think it's creative, intuitive, everything I say up there. And Matt Matthew Westcott is written a really cool blog post that kind of harps on this or like comes off of this theme of uh of the Henry Ford saying I think I'm paraphrasing this exact quote, but he says something like

Speaker 2: If I asked them what they wanted, they'd say faster horses. And now we've got cars. So this is the type of thing that we're talking about when when I say rich field, rich text field or WYSIWYG replacement. Instead of this blob of HTML, we're working with JSON. And in order to create these JSON objects, we're going to be implementing these things called blocks, which is a class that that manages all this data that creates it in the uh And that just just creates like this nice structured block of content within this stream field And uh Streamfield, if if that if it's a little bit confusing and I'll dive more into it, uh it is really just a text field state in the database So instead of again this like

Speaker 2: completely like it could be completely unknown to what's in this blob of HTML, now we know exactly how to access all of these individual components because it's all formatted JSON. And so this would be an example of a block, which I referred to earlier, something that could manage that uh that JSON content. And really We're inheriting from a couple of things, but really to understand is that blocks. struct block, which is what we're inheriting from here, is just a way to combine different blocks, right? And a block you can think of as kind of like a field, like a model field, even though it's not something that's actually getting it directly saved to the database. The only thing that's saved to the database is that text field when you're declaring streams. field. And you can see that we've done other things here too, like in the meta class,

Speaker 2: we've done things like icon equals Wagtail. and sample and equals uh example block. html and that's how it's going to be used or that's how you're gonna see it in the admin and that's how it's gonna be rendered in the front end and and we'll we'll talk We'll explain more about that. So on the actual page, this is what stream field is going to look like. You've got your stream field, which again is just that text field, just formatted JSON, and you pass in an argument of a list. of tuples and each tuple has the string of which is the type of block that you're working with and then the actual block class in which is going to be manipulating that data. And so In order to really demonstrate it, and I know I might be harping on it too much, but I really, it took me a while to understand this.

Speaker 2: My password is food bar, so. So uh so here this is the Wagsail admin and you can already kind of tell that this is something that's derivative from other CMSs that you've seen, but to me it looks a lot better. It looks a lot more streamlined. And here's some other features that I couldn't talk about. The things like images, documents, this is where you you could go and look and search for these things. Here's a search for uh all the different pages or content types that you want. Um snippets are really just uh models that you can register in the admin. And then we've got settings, so we've got really good like controls for like adding users, adding groups of users, getting permissions on those groups. and uh and setting up uh redirects and different cool stuff like that.

Speaker 2: And then what's really nice and something that people use all the time really is this Explorer. Where it actually has a page, I don't have anything in this. And by the way, this is a Wagtail demo from their their this is their demo. I haven't made any of this code at all. This nothing is actually mapping to anything that I'm showing you in code on the presentation So because I kind of wanted to show everybody that that does exist. So we can go to this root page and then we can go to this atomic lagtail page that I've created and we can see uh that I I already have content in here, but this is the stream field and this is what's gonna look like in the admin. And so you can tell that we've got uh how these icons like how that icon made up like attribute comes in, that's the I think it's like heading icon.

Speaker 2: And we've got all these different blocks that we can, block types that we can select. right and and this is great right like this is exactly something that we want you know we want to be able to have a heading here and then just say heading why do I Heading and and then we can have like even rich text field and you know sometimes that's uh sometimes that's appropriate because sometimes we want to put in a link or something like that. I'm not going to put in the link, sorry. And then we can also do things like preview the page and then this content shows up. And you might be wondering, and I'll explain a little later why why it didn't just show up as just text, right? Because and it's really because of that template, but I'll explain a little bit more.

Speaker 2: Right here actually. So Streamfield, uh, you can think about this and and if we if we kind of know that Streamfield exists on that page model. as a as a um as a just a JSON formatted text. We can think of each one of these blocks as different types and C is before B is before A. So every time you're going to be rendering each JSON object It's in an order, right? And these things are orderable too, so you can actually move the different blocks if you want. So let's just say C is a person block that has a name, a date of birth, and a biography. Biography could just be something like a rich text block, but instead maybe we want to do something else too. We want to put in a heading and then the body is the rich text block and then we add an image for that person's headshot or something like that.

Speaker 2: And really this is just a really simplified page, but what what is really important here is just this. You're just accessing each block as a collection. uh on this page. body which is a stream field and then just rendering that block, right? And what's what it and really that's that's all you really need. And sure you can do really custom things like accessing the block. block type which will give you that string that you gave as an argument in the beginning in that tuple so you can render it in it in a certain way given certain conditions or whatever you want to do. And so what's really happening here is that this person block made up of all these different other blocks is calling this render method, and this is somewhat of an oversimplification here, and this isn't exactly

Speaker 2: uh code um that you might use but then you have this person. html uh uh template that you're declaring in that block class. So So once it gets to value. biography, it will then call biography's render value, right? Or a render function, which will do the same exact thing So what's really great here is that you're able to actually modularize all like the entirety of your content instead of just having this big blob of HTML. So just to step back, do something else for a little bit, what's what uh does anybody actually ever combined documentation or have some sort of workflow with their designers

Speaker 2: in which they're actually mapping their designs on the website that you're building for them with back-end code Nobody nobody does that? Okay, cool. So atomic design was uh uh thought of by uh Brad Frost uh and this link I'm pretty sure is to the uh uh article that he wrote on this. Um it's a whole book, it's an e-book you can download it, you can buy it, you can just read it online. But essentially it's just a philosophy or just a way of thinking about how we can combine different modules and design on your site into really consumable pieces. And so I'm going to go over this really quickly. I'm not a designer. I'm just trying to you know explain how we can integrate this. So really five levels, atoms, molecules, organisms.

Speaker 2: Templates and pages. I realized that this isn't exactly a great analogy with, you know, biology and then templates and pages But this is kind of how they they've uh they've created that. And so an atom would be something simple. something like a a uh a uh uh like a button or maybe even just a heading. And then molecules are a uh uh uh like a combination of atoms Organisms are a combination of maybe molecules, maybe multiple molecules, maybe maybe molecules and then atoms. However you want to define that within your own reasoning, uh sort of like guideline by uh Brad Frost's uh atomic design. And then templates would be just everything together. You can think of it as just your Django

Speaker 2: template or something. And then page is something that you have all the content. So that's just a really brief overview, a really oversimplification, or really oversimplified version of what of atomic design is. So when you're using wax hill with atomic design, which is something that I've been working with for the past like year, is uh is you're gonna map all of these blocks, these stream field blocks that I've told you about to your atoms, your molecules, your organisms. And then you're gonna combine them in your page type to be able to render all of your different uh components consistently so your design is continuously pervasive through everything that you're going to be developing with So this is like an example of Adams. py where you have your heading and it just inherits from chart

Speaker 2: block. It uses the title icon and then it uses the template Adams. heading. html and it could be something as simple as just using that you know H1 tag or it could have extra classes that you want to put on there. It just all depends on your use case. And then we have the same thing for hyperlink, that may be a little bit more complicated because you got could have different markup for external links or whatnot. And then we just do the same thing with m molecules, but again, since all atoms can be inside molecules and so on and so forth, we're gonna just reuse these components. So every time you use a heading, you're gonna, or every time you want to put a heading somewhere, you're gonna reuse that in your molecules. And so like you don't have to worry it, like you don't have to worry about multiple changes or like anything like that. Like in random here in this page we have this blob of HTML where we have to change this H1 and oh wait, we have to go over here and change this

Speaker 2: H1. um it's all gonna be changed right there. It's all just rendered exactly the way you want it. And and it's also only gonna be rendered on uh whenever that on runtime. So that even that even if it's the same heading content You're still gonna get that change whenever you want to make that. And so we do the same thing with organisms. We have seen this before, and then we have a stream field where we have we've combined all of this together. And so again, we've got this really continuous pervasive design. specification in our code and not only just that uh that that consistency but we also have a mapping between our designs where they have tons of documentation because designers love documenting and they love

Speaker 2: like understanding exactly how these components interact with each other or just have in these different actions. And then we can say like, oh that's the exact component in the back end that does that. And that's something I've never seen before. So this is like a really cool way to actually organize all these things. And it makes ramp up time for like new fellows or like new whoever to be able to understand like which maps to what And so this would is just some sort of you know project file structure setup that I did. And essentially what my project is like is I put these in this elements folder I put all of my atoms, molecules, organisms. And then in my models down here, I'm going to be putting all my page types. And I in and actually in my project, I have a models folder. and in which I have all the different page pages that I've created

Speaker 2: in that folder. So a couple more thoughts. You know, Waxville's like Really cool. It has that awesome stream feel feature amongst many other features. And it's something that I've always heard from other people like content editors. really anybody that it's just such a joy to use. It's a great replacement for something that is really unusable, like kind of not really intuitive. Uh we replaced it with work or we replaced WordPress with Wagtail and our content editors were just you know, jumping with joy almost. I mean they were really, really excited about it. And that if you go to madewithwagtail. org, you can see all the different websites that Wagtails like that's why it's also powering. There's I think there's parts of like NASA, there's consumerfinance. gov, which is the CFPB site. There's Peace Corps.

Speaker 2: So it's not just some you know brand new, no one's ever used the technology. This is actually pretty proven. So I definitely encourage you to go and at least try it out, see what these features are like, and see if maybe you know you can incorporate some design in your in your workflow. So that's it. Thanks.

Speaker 3: Oh, thank you, Good. Uh we've got a few minutes for questions. So my question concerns image versioning and multimedia asset versioning. Is there any facility to uh version uh images and assets so that they can be sort of identified as unique elements and then updated on their own, affecting all pages.

Speaker 2: Uh that's actually an interesting question. I don't think I know enough about exactly how these images are being You know, like essentially each image itself or document or whatever has its own ID in the database. So if you update that ID, it's going to be changed throughout the whole thing. I don't know about versioning. That's there is such a thing in Wagso, which is actually one of the greatest things about it that I'm sorry I didn't even mention is really just the versioning of the pages. So every time you save data on that or every time you save a page that gets saved as a revision object so you can reference that object. That isn't something that images have. I don't know if that entirely answers your question.

Speaker 3: It does actually

Speaker 2: Cool.

Speaker 3: Uh and I have another question, but I'm gonna defer and ask it later.

Speaker 2: Okay.

Speaker 3: Thank you.

Speaker 4: I think we've got time for one more time. Yeah. Posing is at five ten. Um

Speaker 2: yeah, so my my question is is basically concerning like say you have an existing site that has user profile, you know like a root user profile user profile page or something like that. And uh uh so I guess this is around integration.

Speaker 5: So and you want to integrate Wagtail into the that the site. Is it possible? And if so, how hard is it? Would it be to basically make it so the wagtail articles say you're one of them's an author or something, you would show that user profile information from an existing site. You know, does it integrate well with models that exist already?

Speaker 2: Yeah, it already uses that whole models table and everything. So that's going to automatically get there. When you go into the ad Wagsel admin, you go to the users and it's just going to be there.

Speaker 5: Okay.

Speaker 2: That's my experience. You know, they're uh yeah.

Speaker 5: Okay. And how does the how does the code actually like hook up? You know, so like say you've got, you know, does it just use the get absolute URL for instance if it links to their profile or is that is that something you customize yourself when you set up or

Speaker 2: you know in terms of I'm sorry and I don't think my answer is entirely correct about user profile. I don't know about that. Okay. Um I think the users themselves are going to be connected. I'm not I haven't had experience with connecting the user profiles Okay. Sorry about that.

Speaker 5: Oh no problem. Thank you.

Speaker 4: Just one last quick point to make. First of all, thank you, Kurt, for your amazing talk. Thank you so much.