PlantUML in Servoy – Joachim Hilgers

So welcome to the next session. It’s about plant UML. Has any one of you ever worked with plant UML? Who has never heard of plant UML? Okay, interesting. So that’s a little bit about my background. So I’m a Foxport developer for the 30 years. And I started to be a professional developer in the cowboy in 2019. So I’m a pretty new to the cowboy. If I compare myself to others here, so please forgive me if I do something wrong in the cowboy. I’m mainly interested in writing better code. This is about an interest that didn’t have robust code. And to have maintainability, more maintainability in code. That’s… that interest came through my long experience in developing, developing crappy code. So I’m trying to get better. I’m still trying. And I’m interested in tools which helped me to do this. So every tool which keeps the data work away from me and helps me to avoid errors is good for me. So this is about documentation. The whole session is about documentation. Who of you loves to do documentation? Really? I knew this would be a hard session. But who of you really needs documentation sometimes? And it’s missing something. No one. I can go. Okay. Okay. So that there seems to be some demand for having some kind of documentation. So what we will not do here is do anything in coding in inside of our job or script or what else. So if anyone is expecting this, take a branch. What I find very interesting is to be able to create graphics out of code. So just have a text representation which then is represented as a graphic. I feel that some parts of our application cannot be described really in text. If I look into a git commit or a git history commit, I don’t have a feeling about what a text actually is. It’s a text that is changed. I think most of you have the same feeling about it. So we had a little field here and some methods there. But what’s the effect of the architecture of that application? And sometimes we need just some documentation just because the customer wanted to have it. And I’ve never heard of that. And if it’s missing from your documentation, you have a problem because then you need to write it yourself. If you don’t use a design tool for your database, how will you create that one? Reverse your database. Who are viewers doing that? Reverse it? What about the relations in our voice? They are not in the database. It’s a partial documentation. So what about my main reasons to use a JOK? If I have a graphic which describes something in my code, which is complicated, then it helps me to understand what’s happening there. If I have complicated stuff here, this one here, how do you communicate with a new B which enters the team? Hey, here’s happening this. Look at the code. If you don’t have a graphic which describes dependencies, for example, it’s really hard to communicate with a teammate. This works like this. If you change here, you have to take care of this and this part of the application. Yeah? I think all of you who are in working teams might have had this problem yet. So, and as I already said, contractual terms, the customer just wants to have it. At least he wants to have a database diagram. You don’t have a database diagram. Well, I pay you. So, UML, that’s the name of plant UML, or if you have, let’s ever work with UML. Was it nice to do? I have to confess, I’m not really a fan of UML. But in the 90s it came up and it was advertised as this is the solution for designing applications. So, there were a lot of UML tools. Most of them were pricey. You draw some diagrams, press a button and get your code. Did that work? No. It didn’t work. It wasn’t worth the effort. The only thing you had, you had a nice description of your architecture. But your code was something totally different. You needed to write your code and this code then differed from the diagrams. And from my perspective, it was a waste of time. So, why does a UML suck? Let me show you this next time. That’s my personal point about UML. You do not need to agree, obviously. So, this is a part from the plant UML website. Here you can see you can define a couple of different types to connect objects. It’s not that important there. Okay, it’s just about 15 types of different arrows, arrow dots and lines to describe the associations between objects. And I myself can only remember these two or three. And I always choose the wrong type. That’s why a UML really sucks to me. But I never could think of or just remember all the specifications which are in there. No, I got lost. But I’m a pragmatic programmer. So, and it helps a little bit because most of the people know some types of these diagrams. So, then at least see, okay, this is a class diagram. And I do not need to invent a new notation for describing something. So, if I use the right type of arrow, I don’t care. So, how do we normally create UML diagram? So, we have to use suspects. It’s PowerPoint, visual, or you draw, draw, I will. Even though some guys using Paint or Excel to create something graphical, I think it currently PowerPoint is the thing which is mostly used for that. But only because everyone has it up on this machine. And it’s so simple, you know. You just put something there and it’s easy to use. You don’t need a training session like this to do it differently. So, but my problem with these things is they just create binary files. Each platform has this application as a binary file which is created. Okay, the .x and . or however they are called as zip files, but it’s a melody in it. I hate it, it’s still a binary file. You cannot put it to get and compare. And there are others which are in cloud. I have no way to use them, reuse them, yeah. The only thing to reuse them is take a screenshot, put it somewhere, put it in a Word document or something. But you sure everyone of you already has seen something like this or done it. Because that’s the only way to share it. It’s far away from Git repo. So, we are using most of you. We start using Git or something like that, everyone. So, the history of your application is in Git. You can see I changed that line of code. But you cannot see how this graphics which belong to your code change. So, it’s away from your Git. You cannot go to .x and see what are the differences between two models. Okay, there are tools which can compare graphics like beyond compare something. They say, oh, there is something changed in the diagram. Okay, but that’s far away from context, really. And the great problem with that is if it’s not in your repo, it gets outdated really early. So, the worst part of the worst possible documentation for me is I have a look into the documentation. And let’s see in the easily it’s not matching my current code. So, I close it and then I look at it. I’m pretty sure most of you had the same similar experience. Yeah? So, why plant you a mill? The plant you an L gives you a way to define text. You find your graphics in text. And this text can be in your code. It can be embedded in your code. It can be separate files. And then plant you on the toolkit which generates graphics out of this code. It’s pretty, it’s used pretty everywhere. There are plugins for most platforms. Even Visual Studio code, anti-clips. And I found out even this Google Sheets thingy have plugins for plant you. So you can put your plant your record in there and it generates the diagram. Nice. So, you can’t define easily objects, but a really astonishing part in plant your melodies that it defines, that it creates or draws the relations between the objects. If you think of using Visual or something like that, you can connect things, stick lines to the toolkit to our objects. And you move them around. You have a problem because the links are, you need to draw the links somewhere so that they do not cross or interfere or whatever. And that’s what plant your melodies. It optimizes the links between the objects. The diagrams not only look that perfect, but they are readable. Another point is plant your melodies can create different types of diagrams. It’s not only UML. You can visualize JSON, anti-tirrelationship diagrams, Gantt, Mite maps, anti-yummel. So you can visualize these documents. And that’s pretty easy. As I said, diagrams can be embedded in your code. It just needs to install the clips plug-in. I’m using this now for one and a half years. And I never had problems with a stability or with their way updates. It worked. It’s just worked. In comparison, Patrick Talgo had a thing out there which was there to design your database in a graphical way. It was a really cool thing, but it was a nightmare to install because there were so many dependencies. This is the way around. And now let’s show something else. So what I did is I just, let’s try to answer one. So here you can see I just launched a browser and there was a large URL. So what plant UML can do is to embed a whole diagram as a URL. This is the online website from a plant UML org. You can go to a to a to this site and just have the diagram, the diagram text, which you can see here, as the URL. This form just can convert this. And this here is the diagram which is created out of this text code here. So every plant thingy starts with a start, UML and ends with a end UML. That’s always the case. And everything which happens between them is just your diagram. So here you have some if, and if, and if, and if, and if, and if, and if, and if, and then, and yes, and a no. So, and this is a diagram which we created out of this. That’s sometimes it’s not pretty obvious how to create this diagram. What I do is just do Google search. This is the start page. It’s in German, sorry for that. I want to create a activity diagram. By the way, I’m using two types of diagrams mostly. One is activity diagram and the other one is class diagrams. That really helped me to define something. So let’s have a look at the activity. So if the thing I want to define is something like this one here, I want to have this diagram then I just copy this code and then start to work on that one. I add another if, play around how this is rendered. And I pretty early get to get to something, but it’s really nice to work with. That’s what, so these diagrams are always generated out of this, what is on the left side here, show now. So take just the code. Okay, take it from here and put it into your favorite application which can render that one. So in Eclipse, you can do that. Partially you can use Visual Studio Code. Let’s see that. Visual Studio Code. Create a new diagram. Select the language. This is plant. UNL. Paste in the code on the left side. Okay, it’s not a little part. Just step one. Paste it in here. Press auto-date D for the diagram. Okay, we are. So that’s an easy way to define your diagrams. The Visual Studio Code has a plug-in which is helpful because it has code completion, partially at least, and can show some, can show colors of the, if you have to do any problem. So that’s my favorite to design a new diagram. So now that wants it about how this diagram looks. How you define them, that you can send them as a URL to something. Potentially you can create a, or you have a browser, a, you have an ng-clined application. That’s a button show me. You know how the diagram should look. It’s part of the URL and points to that page which then renders it. You can host this as a, as a service in your, in your, in your in-house. Or you can use plant URL as a Java library to render this diagram and show it. So that’s all possible. Let’s go back to that one. Forgive me. Come on. What’s happening? So, so this, this all was about text defining, defining diagrams. But you also can use a logo. Sometimes you want to have a graphic inside of a diagram that’s possible as well. So this diagram here just renders the Zalboi logo. So we have to start URL. We have to sprite thingy. We have this one here. So easy to do. How do we do that? Oh, it’s easy. Let’s see. If you play installed plant URL on your, on your machine, then you have a Java thingy. You can launch. And I’ll try to show it if I find it. Just a second. So. That’s not the one. Let’s take this one. So that, that’s the, the, the really cool UX of plant URL. It, it’s really a toolkit. So let’s say we want to have a screenshot of, let’s say that one here, just this, but no, I copy it to my clipboard. And go here to open sprite window. It now sees that something is in my clipboard. And this is the reference representation of that graphic. Yeah. So, okay. So you just copy and paste that into your diagram. And here we go. Believe me, it works. So this is useful to have logos in your, you know, thingy. Or if you want to have video screenshot, which makes clear what’s happening in that diagram. Okay. So, so that’s point. No, no, no. Not the last point, but this point here is why does it make sense in bad diagrams in your background. So the question you are question, question yourself. Honestly. Okay. So let’s have a look at Zal boy. Let’s see this one. So, simple code. On the right side, there is a window, a view from plant URL. You can activate this. If you go to show view after you install the plugin, then you have others. And then you have plant URL and then you can open just one of these views. So this thingy is a JavaScript file. And there’s just some command. And you will see here again, this is my diagram. And if I click here, I can see it on the right side. You can see that as well. Yeah. You can hear export it to several formats. You can just if you want to copy it to PNG file or whatever or SVG file. But you also can make the URL a thingy as part of your code. So if you have some kind of documentation for a method, then you can put it in the head of your method. Here again, you have start, URL and URL. So if you write it there, it will be unguit. And if you do a git compared, you can see how this will change. That’s much easier to see than to follow something in your code. You see some lines change. But you will not see how the logic changed. So let’s make a teaser first so that you get away. Who of you is using JSON? Most of you. JSON is easy to read. It’s readable, but it’s not easy to read. What about this one yet? So only thing I needed to do for this diagram. That looks nice, yeah? So this is a hierarchical JSON. We have some highlighted columns. Okay, not too bad. So the only thing I needed to do is, again, that’s not start URL. It’s start JSON and at the bottom it’s end JSON. And then I put in this highlight commands because these are the ones I want to highlight. That’s all. Easy way to add something to your documentation or use it somewhere. Easy, easy. I’ll give you a fan of plant URL, aren’t you? Okay. Let’s see, this one. This is something I used to understand an application I was working on. Yeah, I’m really using different kinds of associations. This means it’s part of it. It might be that you and Meloniz are filled with things or whatever. I don’t care, but I know this form is part of that form. Here we have two sprites. And I see the inheritance of all this stuff. And it’s much easier for me to understand how is this one really put together. And the code for that is not that much. It’s not really that much. I can show that. Think. Don’t think about the sprites. These are the screenshots. Okay, a little bit pinned by my header. So this is just I’m defining a class, AMS based. That’s the top most most form here. That’s simple. If you use this, let’s say I want to have another class. AMS based one. Then some somewhere. Second form would appear. Not sure where. It will refresh problem. Here, here is yeah. So sometimes you need to click in and out. So now yeah, but I have a new form here. You can see it. So it’s pretty easy to extend this diagram now. New form is with relevant in the context. Edit here. And if you want to add some methods to a form, then it’s this one. You just have this parameter, you know what I mean. And right here, just your method name here. So that’s the method which is interesting for me. Easy. So where is it in the diagram? So it’s here. So then there are a lot of arrows. How do they come from? So here we have it. So this is just the section which defines which connections do we have. So that’s mainly it’s inheritance. Or for the other parts, for these guys here, we just use a different type of arrow. So here you can define the arrow. Let’s see. Here we have the other. I always hit the right type only when I get a second try. So you immediately see it. I think that’s pretty helpful to document complicated part of your application. That can even be a little bit more advanced. So this one here is an example of something I worked on. So you all know we can have code in scopes, in forms, in tables. Because we have entity methods and calculations. So that’s totally different than other environments. So in a plant, you are male. This one here is it’s a class. But instead of putting class in front of it, you just put entity in front of it. That gets rendered a little bit different than the class. And here you have tables and methods. And what I did is I just put some colors into this diagram. So the red ones are new methods. I easily can see where the methods are. The green ones are the ones which changed. I changed some code. And the turkeys, what’s the color turkeys? The purple ones, this are methods I moved somewhere. This I elaborated this one through how the period of a couple of weeks. I worked on the feature and I need to close this down. And I need to do something else. Come back. Hey, that’s pretty complicated. Where am I coming from? Where do I need to continue? And then I just elaborated that one. Okay, I need a new method there. I cannot keep it there. I need to move it there. And that helped me really to keep track on what I was doing. I don’t think that this is the right way to document everything. But sometimes this might help. And it’s again, this is part of your kitful repository. You can easily see what changed in that commit if you do it. Anything else on that one? No. So what do else do we have? Let’s see that one here. Come on. Sometimes as I said, it doesn’t want to refresh. Okay, if that doesn’t want to refresh, I take the code, go to a region studio code. I didn’t hear a try. Come on. Okay, what’s that? Don’t mind too much about that one. That’s a part of inheritance hierarchy of forms. So we are at least five levels deep. Really broad. What form is inheriting from what form? If you believe me or not, this was not made by hand. Might be something which is interesting for you. Because we only have the small window which shows the inheritance tree up from the current form. If you press F4 again, it shows the tree down. But sometimes that’s not enough. Sometimes I, at least me, I need something. Aside from what you’re developer to see, okay, I’m here. I have to look there. If I change the message somewhere, that’s much more of information I can see. And if it gets complex, not complicated, that helps. I said I did not write that by hand. I could show you what I did. So it goes all. So here we have a media folder called PlantUML. And I have a workspace called PlantUML’s forms. I do this one, debug this message, which is called demo. Go back here. Generated forms. This was not available before that. Come on, please show it. Now, it doesn’t want to ever refresh. Okay, go back to code. So that just forms from some forms from the example solution. You can use this to, on your own application. So, another 50 lines of code. Currently it has all the methods in there. I can think of just showing the, if it’s protected, if it’s private, that’s not that much of work you can do that. I can think of if this isn’t an abstract form or not. It would be helpful. It shouldn’t be easy. So what I have is what, that one is called an NVEP. In the Foxbox world, this is the most valuable professional. But here in the Zavro world, it’s a most valuable, the minimal valuable product. So it’s easy to use. You can have it. So if, okay, forgot to mention. So what I wrote is something where you can just say, start with this form and then it goes up to tree and shows everything which is below that. So not the full model gets gets computed. I think that’s pretty similar to what we have in this, in this hierarchy thingy. It might be helpful. So how do I use this in real projects? Here we have a larger project. And as I said, sometimes it’s, one problem is if your documentation gets out of sync with your code. So how do you know how that you have some kind of plant your metal documentation for your code? Either you embedded in your code itself. That’s possible, but it tends to get nasty. So I think the best way is to have separate files. I put them in a folder called plant humor in the media folder. That in my code, I have something like this, just markers. So in this one, in this case, it’s a hash i2 hash. So let’s see. This is a marker for me. I have documentation for that one. Search for that. Okay. So here is something in the plant humor folder. So that might be the documentation or the graphics for that code part. And why did I create that one? So let’s see that one. I’ll open that one. And let’s go back here. So that’s some kind of typical code I’m confronted with. So we are somewhere in a div. Okay. So that’s not that way coded because it’s someone had a bad day or something like that. It’s really needed like that. Okay. You could refract or something like that. But it really makes sense to have this kind of code there. So really, that’s a complicated code I would say. And my diagram shows something like this. So that’s the storage bar. So what is, I have a few things which are positive about that. So if I, I’m in a discussion with the customer, he says, we need to change the logic somewhere. Then I’m talking about then, are we talking about this one here? H, A1, A hash. Yeah. That’s the point where we need to change the logic. Oh, then it’s easy for me to see this in my diagram and to find it a code. So that’s the point where I need to change my code. Otherwise, if I change the code, I know where I have a look, I need to have a look at the diagram. So that’s a pretty simple way to keep this all in sync. Another thing, if you put all these things in a folder, that is called Plant Your Mel, and you look for the subway resources, then you have an overview of what’s available as documentation in that application. If they are named correctly, okay. Nice. How much time do I have? Three minutes. Three minutes. Perfect read. Okay. So the last one I want to show. Let’s go back. So there is another one, another scope file, which is called Plant Your Mel Database. I have a demo method in there. I debug this method. I go back to the media folder. Now I have a generated VRD thingy. Come on, refresh, please. Okay. That’s a demo. Hey. This is your database. So this is the example database, which I just walked through and created this diagram. So for each of the related relations in there, you have the names of the relations, you have the keys of the relations. Okay. Screen shot, put it in a world document, 1,000 euro, fine. Any questions? Good. Thank you for visiting me. Thank you.

Close