Wagtail Roadrunner Beep Beep

Speaker 1: All right, um well I'm Lars, I'm back, and uh this time I want to talk about Roadrunner. Roadrunner is a new type of page editor for Wagtail and actually it's not really new. So we've been using it it in a different form for a while but um because this code is all custom it's really hard to update and uh so we We made a rewrite and in this rewrite we decided to use all the Wagtail fields as they are. So use the actual code.

Speaker 1: This uh talk uh is um in three um sections. The first section is The zen of Roadrunner. And it explains the motivation behind Roadrunner. But um I think this kind of talk would be a little bit boring right now. You've been sitting here for a couple of hours. So I think I'll skip this. And we'll just go right to the demo so I can show you how it works and after that we can go into the technical details. Now the giving a demo will be a bit difficult Because um yeah it's not my computer. So uh I hope that the screenshots that I took are enough

Speaker 1: to give you an idea. If not, yeah please Please hook me up after the talk and I can show you the demo on my computer. So let's have a look. The first thing that I'd like to mention is that Roadrunner is just een nieuw streamfield type is. So it's not really een entire UI of templates or whatever. It's just a new stream field type if you use it. You can use it just like any other stream field. But it's also possible to have a global registry of blocks. And all the blocks that you register globally, they will be available if you use the field without any arguments.

Speaker 1: If you do use arguments, well only those fields become available. Um let's um make a website In this website we have two columns. The left one carries the page title, some text, and a call to action button. The right column has a complex widget of what looks like like a display of the effectiveness of some social media campaign. Now let's have a look at the page editor. So this is it. What's going on here? There are a couple of a couple of things going on. The first thing that stands out is that

Speaker 1: Our blocks are not laid out vertically in a linear fashion, but in columns just like we are seeing in the front end. The second thing that stands out is something that looks like a bootstrap grid selector. You can see the little display and the green squares. That's the grid selector. So the third thing that stands out is that we are not seeing any form controls. In fact, we are seeing only a preview. of the blocks. Because we are laying out the blocks in columns it would be very cumbersome to render the editing controls directly and it would become cluttered really quick.

Speaker 1: So we choose to uh render just previews for a more compact representation of a block and it can be easily recognized it can be easily recognized by the user where they should click to go to the editing interface. This social media widget would actually be a couple of form fields where you might have to enter some account info to pull the data data from some external service and it's not really easy to recognize. So in this form with the preview it's actually much simpler to find what you want to change on your page. And it can also be much more compact.

Speaker 1: Tactile pages can easily become complex. It depends, there's a limit to what you can do with stream fields. If you push it and you nest things too deep yeah the the amount of scrolling you have to do and the amount of pluses you are seeing on the screen can easily be overwhelming So let's have a look at how this preview thing works. I'm not sure if anyone is aware, but Wagtail allows you to customize The admin interface by specializing by specifying the form template in the meta options. If you do that, this template Template will be used instead of the

Speaker 1: default wagtail controls. And that's nice to have because even though the page editor is all JavaScript You can simply write some Django templates to modify the JavaScript front end. That's a really good idea because it lowers the bar for a lot of uh People. So we decided the same should be true for Roadrunner Preview to make this as accessible as possible. So here in the meta options you can see we specified preview template and this is what will be rendered in the Roadrunner admin page editor.

Speaker 1: Here is an example of an actual preview template voor een blok built into Roadrunner. Stefan heeft hard this week to previews, so we could do this demo properly and here we can see that he has just written a bootstrap modal window and he is using exactly the same variables as you would use in the form uh template. So here we render the value of the uh fields with using render form which might be a little strange but um yeah it's it's not different from uh using form template so this is uh what it looks like

Speaker 1: previewed in the ad admin so um yeah you can just uh it looks just like it would if you opened the pop-up so it's it's really clear For this purpose we include a scoped version of bootstrap 5. So Wagtail uses an old version of Bootstrap. I'm not sure if this has changed in Wagtail 3 uh but um we're still on Wagtail 1. 6 so we're making this first working with uh with that version but for the front end we use a lot of bootstrap 5 so we also want to use it in the previews. So here we scope it in the dot preview class. So everywhere where you have a class dot preview you can use bootstrap

Speaker 1: strap five and it will be styled correctly without conflicting with the built-in bootstrap. Yes. Okay. Suppose you are really lazy. Um you can also um not write a template and um specify which fields you just want to see and it will render them below each other in the page editor So um we wrote some widgets in JavaScript for some uh difficult um base uh

Speaker 1: um fields in wagtail so uh inputs, images and um rich text so these can if it it's one of those fields you can use this approach and it will render as a preview so not as an input or an editable field. Now let's talk about those columns When using the Roadrunner field, all the machinery to lay out your blocks in columns is added. So everything you're seeing here with the the bootstrap selector and columns it is added to the existing Wagtail code. The grid selector can be used to change the width of a column for

Speaker 1: a certain breakpoint. We currently support three breakpoints: mobile, tablet, and full screen. Now I'd like to give a demo, but I can't because this is not my computer. So I have to explain how it works. In the top right you can see that there are three icons These are floating and they can actually be used to switch the display. So if I click on the mobile phone there, everything switches to the mobile breakpoint which are usually set to twelve columns, and everything is below each other. So we can quickly um see how this page would render on mobile or on a tablet or on full screen. If I click one of the um

Speaker 1: grid chooser blocks, the column will become wider And the columns will be rearranged following the bootstrap grid. To edit some of these Blocks, you just click them and the model will open, showing you the editing interface. So it looks like this. Right here we have actually also changed the form field. That's why we have two columns here with on the left the stuff that has to do with the buttons and on the right the stuff that has to do with the content of the pop-up. You can click apply or save as draft to save and

Speaker 1: continue editing. Yeah, technical details. It's too bad that I can't demo anything. But uh that's all the screenshot I've got, unfortunately So, Telepath. Telepath is a library in Wagdale, uh which um Is the bridge between the stuff that is in Python and the stuff that is in the page editor JavaScript. And we use it to uh change the the workings of the javascript and also the python for some blocks. So here's um

Speaker 1: something called an adapter and the adapter is used to specify um how which JavaScript should be used in the page editor To handle a certain type of field. So, right here in this screenshot you can see that the image chooser block adapter will be used for For the image chooser block, which is a built-in existing block. In fact, this image chooser block adapter will now be used for anything that Subclasses image chooser block. So telepath works based on an inheritance. So if you want to change everything, you just take the upper base class, register a new adapter and

Speaker 1: It will work. So right here we say that we want to use our own code to handle the image chooser blocks. And we have also to register register our JavaScript code on the JavaScript side. So the class that's mentioned here is roadrunner. fields. image chooser block definition. And in JavaScript we have to also Register with with telepath R class. Roadrunner. fields. image chooser block definition. So now telepath Knows about this class and it can use it to render image chooser blocks. So let's look at how the preview is

Speaker 1: um handled. So um the only thing that we are actually changing is that we render the the original Wag deal form in a model and render a preview which is is something extra that is also um something you have to make when you make a block. So here's the preview for the image chooser block definition. This looks like React, but really if you want to reuse the Wagtail JavaScript, you can't use React. Because they have to render in a placeholder right here you see the first first argument to render preview is a placeholder and that's a div and it will get review met de code

Speaker 1: that the widget should renderen. So if you use React you don't have control over this rendering phase and you would have to do all kinds of crazy tricks with refs to uh have the widgets render in uh in javascript so we are using jsx here but without react there's a little library called JSX render and um it it lets you use JSX and immediately um create uh DOM element So to me that looks a lot nicer and you can also create components in JSX instead of writing strings or um making dumb elements uh using jQuery.

Speaker 1: So in this case um we render a fragment with an image tag and we use the preview image. url the width and the height. So it's not really complex. And it also renders a new placeholder for if another field needs to render below. This uh block. Um yeah, so how do we uh add preview to stream block Because stream block is uh the the field that we are changing and subclassing we have to enhance its functionality with with uh um With preview, so in this case we need to override stream block with a different class that adds this functionality.

Speaker 1: So this is the code. We um change the render uh method of the stream block um we um uh we render a modal in jsx And we we call on the line uh let's see where is it below the JSX it says oh I can just read the comments that's better So first we render the wrapper template with placeholders for the preview and the child element. So now we render something with two placeholders. Then we will render the the original WagTilt field in one of the placeholders that is inside the model

Speaker 1: and the next thing we do is we render the preview in the other placeholder. That's it. So uh we keep everything Wagtail does, we just change the context. It is rendered. it in. So the other thing that we are doing is if you read the telepath documentation there's a small mention of that it's possible to have a local registry of adapter and uh we actually use that for road runner field. So uh in road runner field we want to modify a couple of things in Wagtail so for example this stream field block. But not all pages are Roadrunner pages. So we don't want to modify it for the entirety

Speaker 1: of the application. So we actually have have an uh our own uh js context in which we uh can override certain stuff from wagtail the couple of blocks we need to alter. So, Roadrunner is open source. You can find it on our GitHub of our company It's still in development. I was actually planning to have it completely finished right now, but hey, that didn't work. But we uh have enough so we could demo it now, which I cannot do so if you are interested you can put a star on the github and uh I will notify you of you will get notified when uh the dot

Speaker 1: one release is done and the the demo project that I cannot demo is also on GitHub so if you want to check it out if you're interested you can also do that if there's something it doesn't work while you try that or you are interested or have questions you can send me an email at larce at hybiza. nl and then That's it, unfortunately.

Speaker 2: Thank you, Lars. Do we have any questions for Lars? Here you go.

Speaker 1: Yes.

Speaker 3: How did you come up with the name Roadrunner?

Speaker 1: Yeah, that so this project already existed. So somebody chose this name and the the reasoning behind it. No, but it's a bird, right? So

Speaker 4: uh have you feedback from users? Have people been w working with this?

Speaker 1: No, because this is the new version, so the old version with have a lot of feedback and that is all fixed in this version. So the previews that you're seeing now they actually didn't exist in the old version. You only saw the name, the type of the block and then also in columns organized which is very compact but you don't have a clue which element you should click to edit. But this is not in production yet because I still have a couple of uh user stories Yeah. So have you managed to make this work with commenting? Uh I don't know because uh I think commenting actually still works because I still see the the symbols uh there and because the original code it it there's

Speaker 1: nothing has changed so it should still have that connection but um I didn't test it lately I tested it at the beginning of development I was I found it strange that it it did anything so it looks like it actually s uh s it it used to still work.

Speaker 2: Yeah that's interesting. I I was just um yeah I was curious about the rich text editor and the module

Speaker 5: particularly whether that um still interactive but yeah

Speaker 1: Yeah because it's still there. So we rendered a preview, but we render it using JavaScript. It just transforms the draft. js um uh bear uh JSON but all the origin the original stream is still there. It's just

Speaker 5: But the commenting uses a oh I won't go into assuming it's detailed, but it uses a content path system to ID identify where where the comment applies.

Speaker 1: Oh right.

Speaker 5: And if your module is in a different part of the page, if you don't pass that in, I'm interested in whether the comment will be will look like it's in the right place to start with, but when you save it

Speaker 1: Yeah, all right.

Speaker 5: I didn't know what's possible.