Reusable UI components – Thibaud Colas & Ben Dickinson

Speaker 1: Hi, I'm Ben. I'm a background developer at TorchBox. I've been here for about three years working with Whiteel. I've been doing Django for about five years now. My interests lie in DevOps and tooling and developer experience and process and all of those things. So today we're going to be talking to you about how we've taken uh components and best practices from the React world and brought them into Django projects. Over to you Tiba

Speaker 2: And I'm Thibault. I'm a front-end developer at Torchbox as well and also part of the Wagtail Core team. We thought it would be very cool for this to be kind of a joint talk with the two perspectives. And yeah, as Ben said, we talk about smart part libraries. and how we've made that work for us with Wagtail, which should hopefully give people interesting perspective into how Touchbox does things because we do lots of Wagtail projects, turns out. Welcome to my office in Cambridge. This is very sunny and this is also my kitchen. Welcome to my life. The slides are available online. The links is on there if you want to follow along with the slides. And let's get going. So a quick word about this. We'll first talk about this as a methodology, how button libraries are meant to work, and how we use them at Torchbox

Speaker 2: before Ben dives in into how we make this work with Django and give you a demo. And just for context What we mean by pattern libraries is essentially artifacts of the project's development for UI components. So this is a famous famous example of that. from uh lonely planet this is a patinary called rizzle uh which is quite quite well known so you can see i have i have here a list of all of the components that rizzle contains For the component I'm looking at right now, I have some documentation, I have examples of what it looks like, and also code snippets I can just copy and paste as needed. So this is kind of what we're talking about here today And yeah, let's dive right in. So for us at Touchbox, I think this really all started with the atomic design from

Speaker 2: Bright Frost. which has been around for quite a few years now, I think maybe nearly 10 years now. So atomic design is this kind of approach to how you build um web pages or UIs generally where you first start from quite fundamental components that are quite small and then use these to build bigger building blocks and bigger into page templates and so on. So kind of components-driven developments with a more granular uh level. And uh this is still quite popular in the design world. Uh we we used to do lots of touchbox Here's an example of it in practice. Building this Instagram screen. So the atoms, the most fundamental level are really small things on the page. then they are combined into bigger molecules like component level stuff and

Speaker 2: organisms, templates and pages. And this is really how Touchbox used to work with a tool called Pattern Lab. which goes quite well hand in hand with uh atomic design. Um this is a very bad screenshot potentially this is just showing you the same as as Rizzo before which is there is some navigation to see all of the components in the binary. There isn't a demo of the component I'm looking at right now, which is this alert box. There is documentation for it and then there is the code to copy paste if needed. So we used to do lots of pattern lab, which worked really well, but had the one flour that you this was PHP-based, so you'd still need to have this in isolation from your Django and Whitehall stack, which meant lots of copy-pasting uh paints and lots of patterns not being in sync, which

Speaker 2: for UI consistency isn't the best uh best thing. Then comes along React. So React actually has been around for quite a while now as well and has definitely brought exciting developments to how we do front-end work, UI development work. To me, I really like to point out that really it's not a library, it's a whole paradigm shift to how we build UIs. The fact that it's really easier for UIs to be component driven and then for those components to be combined into strings. than the previous way of working where everything tended to be all in the same like page level templates and uh yeah it wasn't that much reuse happening except with copy paste So React is component driven. React is also functional programming for UIs.

Speaker 2: So this idea that each component is kind of a pure function where if you give the component the same data as input it will always give you the same UI as output, which makes it very easy to reason about those components, makes it very easy to write UI declaratively. and also makes it very easy to make automated tests or just any any kind of unit test for those components. And yeah finally The fact that this definitely isn't a template language, uh JSX might might be misleading people at times, but it's definitely JavaScript behind the scenes, which uh has a lot of advantages compared to the limitations of templates. And yeah, so bringing this back to Earth, what makes it good in practice? The developer experience for UI development is completely stellar.

Speaker 2: There's lots of starting analysis. lots more opportunities for uh introspection of the code and just more more productibility uh in in how you how you build those components They are much easier to make reusable and to maintain and test over time within the test. And it kind of brought this new field of tooling, which is component-driven development tools, like Storybook as an example, if you've heard of that which makes it very nice to work on those things in practice. You make your components in isolation from the app and then bring them in as needed. Yeah, so this is all React and I guess we're interested into how we bring this back to the Django world and how this is relevant for us at Touchbox and for you for your own websites. So at touchbox,

Speaker 2: what those pattern libraries really are is the kind of uh codified uh interface between different uh different concerns. So front-end and back-end people tend to be different developers on on working on the same team together at Torchbox. We don't have that many full-stack people or at least we do try and make sure that people know whether they are doing front and work or back and work at any one time And this pattern library workflow kind of makes this work well. So it separates concerns both in the code, what's the UI component, what's on the Django side and models. and also practically for people working on the projects as members of the same team. And what's really cool about this as well, Ben will probably talk about this more a bit in the future. Which is that it makes it possible for front-end

Speaker 2: developers to work on on templates and make UI components before back-end devs make the models for pages. Which would be quite hard to do if you if you if you were wanting to make that work otherwise you'd have maybe to have some static templates on the side that you'd have to manually copy paste and keep in sync. This is all automated And yeah, finally, just the fact that it encourages code reuse, just like the React components, there's a very clear way for you to structure your code into different components and a very clear way to document those separate components. uh into button libraries and style guides that people can look at. Oops. And one more thing I want to mention when it comes to context

Speaker 2: is uh a current trend I see happening, uh which is the design systems trend. So this idea that people are no longer just aiming for a one-off artifact like a stag or a button library, but really this is this is completely changing the workflow of how we uh deliver products not just uh websites, but really products, how we see those going, those happening, and not just a single product, but really at an organization's scale, how they keep their visual identity consistent. and how they make their whole web presence accessible. So examples of design systems, there is one from the US federal government, there is one from the UK central government My the the supermarket I go to also has a design system which I think is interesting to point out.

Speaker 2: It really isn't just the governments And yeah, Sanford Uni as well in the US has one that is worth knowing about and checking out. And this is all public, which is also really cool. And on that note, I'll hand over to Ben who will talk about how we make this happen for our project with Butter and Django.

Speaker 1: Thanks, Thibaut. Uh yeah, so as Tebo mentioned, this approach has worked well for us at Torchbox. And there are existing tools, like TBA's showing you Patent Library and he'll show you Storybook, which is a React tool a bit later on. But there was no library here for Django. So we decided to develop our own. So let me just run you through the decision making as to why we would go to the effort of building our own patent library. So React is great, the tooling is great, Storybook's great, as you'll see later. But most of our projects are just vanilla server-rendered Django wagtail projects, Django templates. So

Speaker 1: we need an approach that allows us to take this componentized approach and apply it to that. Then Django's templating language is proprietary. And we couldn't find any tools that did this for us. off the shelf so we had to build our own. If you're using an existing tool like Pattern Up which understands template languages like Twig or Mustache or various other common templating languages, translating those from Twig or whatever into Django is a manual process. It's quite error-prone. These two things tend to look very similar So you can get lazy and make mistakes. And as soon as you have duplicated templates that you have to keep in sync

Speaker 1: manually, over time there is there's potential for drift And the pattern library doesn't stay up to date and its use diminishes over time and it becomes a bit of a maintenance burn. So other problems like Django's template tags are great, but if you're using a pattern library that doesn't understand Django templates, then you can't use them. Django template tags are great, but they often imply a dependency on model data from the database, like include block. So having a static pattern library that you can easily display and can be worked on in isolation from site content becomes very tricky.

Speaker 1: If you need to visually test a component across lots of different browsers and lots of different screen sizes, et cetera, that becomes quite difficult to do. if you're having to spend lots of time setting up database state. And Django's built-in testing tools don't really cater for this use case. There's no like visual testing. So we've got our own. So you can hip install Django Pattern Library. And it's basically Pattern LabGo's Django. So this is a component playground for Django Tempo Partials. We use YAML files so that you can provide mock context

Speaker 1: to mock out what would normally be like page model data or just other Django model data. It supports documenting your templates, so you can describe how they should be used and how they should work in Markdown, which can be stored and rendered alongside. And this is the kind of killer feature here is it uh supports uh mocking out template tags so that you can use these uh like you know, things that are really good for reuse like inclusion tags are now possible in your patent library. So now you can create your pattern library with Django templates, which means that you no longer have two sets of templates. You don't have the pattern library templates and the application templates, you just have the application templates and the pattern library can display this

Speaker 1: You've got a catalogue of all of your templates in one place so that you can see how they look, what's available to you, which is great for us. We're an agency with lots of clients. You work on a lot of different projects, it's really good to be able to come into a project and just see the kind of shopping list of things that you already have. If you've got a like a single URL, you can spin up a particular component in a particular state, you can open that in loads of different browsers, loads of different screen sizes, check uh, you know, that This is performing visually exactly as you want, much faster. Um, you don't need to depend on content in the database. So You're not reliant on manual setup or database fixtures or

Speaker 1: if you've got sensitive data in a production database, you don't have to sanitize that before you can pull it down. It makes but like that life a lot simpler. And as Kibo alluded to before, it frees up front-end developers to work on your Django templates before your models are ready. It's worth saying that this does not free up your front end developers to work on the templates at the same time as the back end developer. They're still uh This provides a really nice place for them to meet in the middle. But generally you'll still want to have front end first, then back end, or back end first and prime end. So we're really proud of this, but there are a few things that we know we can do better. It's a new project, so the documentation is a good start that needs improving. We'd love to get some more people using this and get some feedback.

Speaker 1: We know we have some issues with merging context And there are some bugs. The way that we mock out template tags is great because it's the only thing that we know that is capable of doing this, but it's not flexible enough yet. We don't have support for mocking out filters yet. And richer Django objects like forms and query sets that you can iterate and have methods that render them like as p for forms uh are a little bit difficult to represent neatly in YAML files. Okay, so now we'll show you a quick demo So

Speaker 1: here's a quick demo of the pattern library. We have a simple demo project here. So settings bar. You can see that we add the pattern library to our installed apps here. We add the load tags from the pattern library to the built-ins so that they're loaded in every template. And then here we set a few settings to tell the pattern library where to look for our pattern templates. Got the development server started here. And we've added the pattern library's URLs to our project slash pattern library So here we can see the pattern library. Quickly just run you through the UI. So we have the list of

Speaker 1: patterns that we have available to us on the left. We're going to be looking at this quote block today. And here we have the template source, the YAML context which we'll get to, and the markdown documentation for this template. So let's open up the template file As you can see, this is just a simple Django template, standard stream block. We're looking at the stream values, quote, and attribution.

Speaker 1: The next file we want to look at is the YAML context file. As you can see this is a simple file here we define the context and then this is a mapping that gets put into that context. So you can see here we look at value. quote, value. attribution, value. quote, value. attribution, and these get rendered in the template. So just to prove that this is all working And refresh. Lovely. So this is great, but we haven't really gained anything here. We're not using anything that's particularly Django specific.

Speaker 1: So why don't we go and add a new template tag Right, so let's add a new template tag that we're gonna use So here we're just going to add a simple tag and we will call that tag get stuff. And it will take no arguments. And all it's going to do is raise an exception saying stuff would require some expenses. So

Speaker 1: now we go to our template file. We can load our tag module. And call our new tag. Go and restart our server As you would expect, when we refresh here, we get an error saying that we would depend on hitting the database at this point. So we need to make sure the pattern library is aware of our tag.

Speaker 1: So from the pattern library We'll use this monkey utils module which defines an overwrite tag function and we overwrite our tag Like so. Great, let's refresh Ah, still an error. So now we need to tell the pattern library what we want to insert in place of our tag. So we open up YAML file and we add this new tag section

Speaker 1: Tell it how we wanna override get stuff. We need to tell it what arguments we're calling the tag with, which in this case is an empty string because it takes no arguments. Uh and then we can use this raw key to insert raw context. Like so. Now you'll notice that we're no longer seeing an error because our tag has been completely mocked out. This is great because it means that if you have her template tags in your project, you can still use them in your templates but you don't need a fully populated database for your front-end developers to work on the project. And now I will hand over to Tivo to show you how this integrates with Storybook.

Speaker 2: Really exciting. Thank you, Ben. I I work hard with this on a on a weekly basis, but I still feel like it's really one of the coolest things about our workflow at Toshbox. Yeah, I do recommend everyone check it out. On that note , those demos, demo sites are available on online if you want to play them, trade them, they are all public, so do have a look And yeah, as Ben mentioned, we do have another demo, which is storybook-based. Storybook, mentioned earlier, is the tool that works really well with React components. And we've essentially been working on a version of Storybook that also integrates with our Pattern Library project on the Django side. So Essentially show you the same components men

Speaker 2: has been working on but in Storybook. This is the Storybook UI you can see right now. Navigation on the left. I have my React components at the top here, so I can have both my React and Django stuff all side by side, which is really convenient as a as a person just looking for what's available. I don't want to know which thing a component is built with. I just want to see what they look like. Then on the right I have this kind of canvas mode where my component displays. I have those panels at the bottom, the storybook. has available as as third-party extensions that can just be installed allow me to try out uh different content for for my components, see how it wraps, if it's very long, can maybe even make use of the mobile version of this just to see what happens. So yeah I can just kind of see different versions of this without having to actually define them as a developer.

Speaker 2: I can just interact with it as a user. You could see this being useful for stakeholders, for example, or designers who just want to play along. The attribution attribute, for example, I can just see what happens if I had to remove it for some reason. Well, the component supports that. So I can just try it out. It's really that easy. I also have this panel for accessibility checks, which it does again come with this or something you have to install extra and configure. It's really easy. I can see some violations, some tests that passed. Yeah, again, like right next to my components. And um Just a second. And uh now if I open my code editor, I can also edit this, of course.

Speaker 2: Uh and it supports live reloading. So if I was, for example, to Um to try and change the color of the code block in CSS. I can switch the variable, don't have to interact with my browser at all, it just refreshes with a new color. And if I want to change the HTML, it's the same story. I can just uh update the components templates. hit save and automatically reloads the new content from Django watching all of the files, which does make development even faster. And now coming back to the storybook UI, so you can see there is those two tabs. The docs one is something that's that is quite recent in the storybook world which

Speaker 2: allows you to kind of publish those uh pattern libraries for third-party consumption. So the Canvas one would be as a developer working on the project, the docs one would be when this is published for others to reuse. So here again I can see the name of the components, some documentation, some experimental code snippets to copy paste, like in the Resort example I showed earlier, what data the component expects based on its templates. what it looks like, the actual HTML for it, which is really useful. And again the same type of interact with the component and change its data live So yeah, this this does feel super promising and I'll leave it there for now because I have more to say with the slides. Takeaways from this presentation

Speaker 2: uh why we recommend this as an approach, well, it speeds ourselves up quite a lot, makes it much easier for people to walk, as Ben mentioned either back end first or front end first, depending on the needs of the project. I feel like ideally it should it's always a bit easier if it's back end first, but it's good to have the option for it not to be. It makes it very easy for us to reuse components across parts of a project or even between projects since the components are so well contained. So as an agency, it's of course very important for us to be able to keep what works and make use of it on other websites. And yeah, one last thing I want to mention is that it does open many opportunities for testing, having unit tests for components and having ways to do automated tests based on the mod

Speaker 2: data of each component. And uh this is all available on GitHub and NPM, uh DjingoPat Library, the Storybook version of it, and Storybook itself, of course, for your React or View or Angular work. And this is already for contributions as well. We open sourced it a few months ago. The storybook version of it is still experimental, but definitely available for people to use. And we would definitely welcome the feedback and the help if some people would want to take this home for their projects. And yeah, we do have a backlog of it, which is already quite well defined. But yeah, definitely room for more. And on that note, well thank you for going through this with us. Thank you for the people to all the people who helped us make putting this together. And yeah, styles are available online

Speaker 2: and have time for questions now.