Sessions is temporarily moving to YouTube, check out all our new videos here.

How to Structure Great Packages

Jon Uhlmann speaking at Neos CMS and Flow in November, 2017
Great talks, fired to your inbox 👌
No junk, no spam, just great talks. Unsubscribe any time.

About this talk

Jon has created many packages for Neos, and he'll share some insights and best practises.


Yes, my name is Jon Uhlmann. I'm frontend developer and a clean code enthusiast, and I'm a Neos fanboy since 2012 so, it's quite a time. I'm working as Gestalgt Getan in Salzburg so, that's why I say we have to start now because we have to take the train back. After all these years I make some big and small projects. I felt as the standard package how to write is not always quite that good like we hear before. so, I have some personal opinions how to create some stuff in Neos. I want to talk about some packages. I created a few packages, perhaps you know it. Like, Jonitto player or the PrettyEmbedYoutube or as we hear, the Carbon.Link and all these kind of packages. so, in the beginning I created the package. I couldn't name it the SwissArmy.Knife. It was a package who can do anything, all in one package. But, with all the time I felt that this was too much because it was hard to maintain, it had no clear API, if you want to reference to that package and use some parts of it, and if I start to refactor a single feature it was a really nightmare. And, if someone tried to help me, he couldn't help because he didn't know the package that good as me. So, that was the beginning, it was called some kind of base or basic, I don't know, but I should name it SwissArmy.Knife because it has done way too much. Then I turned to another kind of packages and I called them One.Job and this package says, I can do one thing, but this one thing I do very very well. It looked as that to maintain it, it's much easier. It isn't easy to maintain a package if you write one. It isn't easy all the time to create open source but it is great, but isn't easy all the time because you get issues and you have to solve them or you want to solve them because you don't want to write code that is buggy. And sometimes you have to fix some bugs that has the system. But this One.Job, you have a clear and a simple API. The dependencies between different packages are much easier to handle if you have these kind of small package. But, you say, perhaps say it, I don't want to get in the hell of dependency here. Perhaps it is your sort, I hear sometimes. But, I have to say that Neos is built this way. If you try composer update, that's wrong. You have to try composer info, not update. Info, it's the wrong slide. Composer info is your nice, nails installation. I can show it to you. I've prepared something. I turned everything from black to white that you can read it. - [Audience Member] That's good. If you put here composer info, can you read it? Ah, you can read it. It's good. You see, oh, that's quite a lot. You see here, we have just some Neos. I don't know this one, some Symphony stuff. Doctrine. It's quite a lot of packages. So, this is quite normal to have some dependency and you're not on frontend development stuff where you have about 30 thousand dependency. If I, I can show it to you if I, that's quite funny. If you press here, now. Info. Oh, I have to turn on my net. - [Audience Member] You need wiFi on. There is one, we have ethernet. No, I'll do it like that. So, let's do it again. Okay, that's the wrong thing, but knows somebody the command for show all dependencies? I don't know. It's quite a lot, you can try to. I can try like that, that's just an all models. - [Audience Member] This is bad. This is right before you started to write the first line of code. We are in the world where you have these kind of dependencies and why these all in small packages? Because it's easier to maintain. And easier to bug fix. And we had already demo but I wanna show you something more. Where we can use these kind of packages. So, I just have to start my server with the build task. So, for example, many times you work with many images and you have some special needs if you have some galleries with special kind to how you show it to the people, to your client. As you see here, I've chose the content type called tiles and these are the content collection, yes I know I could write it here, but I will try it later, and I have some fixed child notes who have some tiles. See more tiles. And this one is just, has the content and then you have also, the carbon image, the backend label, a caption, and the link. And that's the whole content type. And if you have a look at it in the backend, it's in development, so... So, you see, you have here description and lightbox, you can add a link, you can add the picture. And you have this kind of interesting layout for this picture but if you look at this closely, you have three times or four times the same node type who change dependent if he's first, or if he's second, or if he's third he change the layout so, slightly that it just match nicely. And this is, you can do it quite nice in Neos. For example here, if you look at it, we talked earlier about the contents. See if you have your fusion, it's a bit small I think. Nevermind, you have here a fusion folder, content elements, and there have the tiles, and then I have here the content fusion. I work here with atomic-fusion and afx. We talked some guys, I actually talked about this earlier but, you see it's just like easiest if you use this kind of packages, you just can say like that carbon image background, it's generated if where we have the image as background image with some tricks to have it already in high resolution and low resolution with a new kind of syntax and some ratio preserving automatically because on Firefox and ES don't like it just to have a padding top on the element. You have to put it inside so, everything's fixed. And like that, you have really fast, you can create some really nice galleries. If you want, you can show it like in this case. Here I'm just asking, are you the first of this kind of element? What is your position? Is it first, it's zero? And if not, I just count how many of this elements I have before, and then I ask are you odd or are you even, and are you the last? Then I just give this to the attributes and at the end, I've just some TSS where I just write the stuff and you see here the first of this kind of setting, the even have this kind of setting, and odd have this kind of setting, and the last has some setting here, just about the padding bottom, that's it. And with that, you create a null-type who flow together, you don't see directly the line, you just can break up the lines, the straight lines, you have a element who flows nicely into another. This is one of the big advantages of Neos. We really can create some nice content elements depending on where the content element is, you know? Every CMS can just create content elements. I made some really nice content elements also, in Type3 and in Wordpress and in Drupal, and in, DeWitt I think. The really nice thing is, it's really easy to create great content elements where you can change the syntax depending on where it is. So, the content element is aware of where I am. In that case, if you have, I can show it in a different example if you want. So, advanced, it's here. This is a mix-in, I call it CreateCol, column. If I have an image and after that same image or a video and again a video or an image and a video it's not full-size, it gets two rows, so, it's not that big. This is what I'm doing here and at this point the cache entry is like that. I set mode cached, I give the identifier and a set, there is a helper, it can say Neos.Caching.nodeTag and that's it. You can just give me all the siblings and like that if one point a content element change the other one from this who has this CreateCol is gonna change so, you are safe. This one is a little bit tacky because I wrap a content element, on the first I just open and the other one I just close it so, on the backend it's not always that seamless from the editing here but in the new UI it's working better, not perfect, but it's working better. But that is also, some kind of stuff you can say image is aware of where I am. So, I already said, the video is aware of the brother of me is also image or a video so, I just change my layout, I change my syntax. Some other thing I wanna show you, and it's really really nice. Just wanna get you to try the new backend out. You can access this if you try with Neos. Exclamenshion mark, what's that? - [Audience Member] Exclamation mark. Exclamation mark, yes. What you can do. For example, you can do fancy stuff like that, it's just very easy. Let us say, oh I wanna create this node and you just don't give the node title. Here it's duration in days and you say, this is the first day, and this is the second day, the end of the season, this is the start price, and this is another kind of code and you can react in this kind of input. In other part, in other project you have enter a year and then it generates all the weeks but, if the year have, not always have 52, sometimes 53 weeks and in that you can say, okay this year have 53 weeks so, I create one week more. And inside the weeks, there's also, more node types automatically generated and it's really really fast. I mean, I generated about five, six hundred nodes with one click. A few seconds, one two seconds and it's done and it's perfect. And just user can do it. I mean, it was possible in the old interface too but it was much harder because you have to write the signal, and react on that, and blah-blah-blah. And here, you just can write it in .yaml and it looks like that, you have here a creation dialogue and set the elements, you can say startDate, endDate for example, year, or startPricePerPerson. And then, here you can react on this kind of stuff. You see here, you can say, okay if this to a set then please subtract this date and the duration and set to hidden after date time field. All this kind of stuff you can do it. Or even some more advanced example, like I told you in the weeks. - [Audience Member] I just had a question. Is that part of the Neos UI package or is this a Dmitri template? This is just Flowpack, no template. - [Audience Member] Okay. It's not written from Dmitri, as I have to say it's written from other guys but he has stark influence it's all-- - [Audience Member] Yes, okay so, it's extra package you're using? Yes, but it's from Flowpack and you can say that some package from Flowpack are from the core developers and they're not done that bad. They're really good. I mean, the most of them. - [Audience Member] And they stay maintained. And they're good maintained, yeah. Especially if someone, like, Kim Treiss or something behind it, it isn't tanked. And it's open source because all he do is open source. There are some features who are coming this way and this, for example, that you can have arrays and then create this kind of arrays. And here have to write the array manually but with the time they're working on it that it just can create a Eel-helper where it can create the array automatically that's getting automatically done. But this is also, a very very nice way to ensure that the editor have a nice feeling about how to edit the content because before we have to say, if you are at this kind of node type you have to put this in and this and this and this and you have to put the start date in and the start price and you know, he doesn't forget it for bad. He don't wanna break it but he break it all the time because he forget it all the time. And don't be mad about him because he have some other things to care. Perhaps he has a annoying secretary or not-annoying secretary, he looks at all the time. Or perhaps he has some other problems in his business. Our goal is to make it much easier for him that he has a good experience in this how he build up his website. And this kind of tools helps him a lot to create that. Yes, one thing I have to talk about because, yes I may have to. Now let's look at settings If you have a package created, or if you want to have a package you use all the time, over and over again, sometimes it's good to have some settings just to make sure that you don't have to change all the fusion all the time, very deeply and if you change something in the code everywhere it breaks. So, it's sometimes easier to just create these settings and then you can work much easier in your code you can much easier refactor the code because you're not depending on how is something called and how something's nested. So, for example, that link package. I have here a setting, external target. Default is blank, you can also call it external so, it's always the same window. When you give a name you can say, if it's an image, video, or a pdf open in external. If it's zip, xml, whatever, don't put the target instance of document where you can say this is a document. Perhaps, if you want to have some links with sections for one picture and all this kind of stuff. And in your code for example, if you go here you just can call it like that. You say Configuration.settingand then you give the link and the path, Carbon.Link.defaultPhoneCountryCode. Click here, and then you can work with this kind of stuff. Don't ask what it's doing, just normalise some telephone numbers because it's getting annoying to do it all the time, same job again. For nice links. And if you have quite some complicated code like that, if you're dependent on the code just, for example, this part and you wanna change that and you have fixed it like that and you have extended just this part of this code and you change it, you're plugging breaks. But if you want to go and work with settings, like here, it just worked because you create like that, you can really create package who are not 100% update safe, but safer. And it's not only for, you know if you create your package and you make it open source and if you make it safer you save a lot of time for yourself because if you don't make it safe you're gonna get questions from people use it. And if you don't make it safe, the people don't gonna use it. And I think if you create a package, you like it if people use it. I mean, I have a lot of joy if I see that over a thousand or over two thousand people used the Plyr package, I like it. And for me, it's a personal motivation to create or to extend this package or to maintain this package to put the new plugins in, to update the JavaScript, and that package you can download right on Github. You can look how I create the MPM scripts to fetch the new Plyr source code and put it into Neos in the right folder and create the TSS file and JavaScript file automatically. So, I don't have it do all the time manually. In the beginning I done it manually but if the updates are coming you start to automate this kind of task. And I wanna encourage you to write clean code. Sometimes you need some more time, sometimes you need some free time, but it makes a lot of fun because you learn how great Neos is. I mean, in every CMS you can write shitty code and you don't gonna learn how great Neos is. Because it is great. And trust me, I tried all kind of CMS. I know, I now know a lot. And I was, some I was really good, and some I was not quite bad, and on some I just stop very early because I felt it's just awful how it's written. Because you can't extend it, you can't create a feeling for the editor to have easy content. And the best example was my father, I showed him how to manage his website and he has a lot of joy in it. He just creates nodes, and he creates download links, and asset lists. He was a teacher and if my dad could do it, everyone can do it, you know? And I wouldn't give him a Type3 installation, or a Wordpress, or a Drupal because it's always hard to maintain for him. And that's one thing I wanna give to you, always think about the editor that he have it easy to create this kind of nodes. Yes, sometimes you have to maintain the content, but if you write it clean you have also, more fun to create the nodes when it's clean and not when it's messy and you have always to think, ah I don't have to forget this kind of stuff and this kind of stuff. Or, for example, the year. Oh now I have to create 52 nodes, and oh this year has for 53 weeks so, I have to create one node more and name it correctly. You can automate this kind of stuff and it's really fun. - [Audience Member] In other words, you could wrap it up in a way to say make small Neos packages and write them in a way that you would like to use them yourself? Yes, it's like the toilet. At the beginning, you're gonna make a mess. Clean it up at the end, so, it's okay. Really it, you know, my first package if I look at, and it really was a mess. And there were bugs in it and when I look at them I say, oh my gosh, did I write this? Yes, I wrote this kind of stuff. I wrote this kind of shitty code, but then learned and did that way. And you're getting better and better and my opinion is to write small packages, as I said before. It's much easier to maintain, also, for yourself. For example, the Carbon.Link and I can show it to you. There was a quite annoying bug in Neos if you have content collections and we have some special sites so, I always have to check, is this link valid? Has it the same parents that the link is generated or not? And, at the time I wrote this, I forgot about one special case and he found it out. I'll show it to you. And that's really good, even like that you help, you know? If you don't write the package and you found a bug, right? An issue, even it's on a package or if it's on Neos, please write issues and do it like him, like Roland, steps to reproduce. Then he wrote it out like that and he gave me this really nice error log. I mean, I didn't read it, but it was nice. And then I ask him, yeah can you paste me also your content dimensions settings into these issues because I want to know how this happens and I need some more information and then he wrote me and asked. And then some days later, - [Audience Member] Like two minutes later. No, no no! - [Audience Member] Fixed! No no, it was not like that some days because my daughter was born and I have not had time. But, in the nights I slaved on it. And when you write issues it's very cool because you see if the maintain of the package is active. And if it's not active anymore, if you don't react about, give him two or three weeks because if he's on holiday it's not fair. But, if he don't react in good time just leave the package because it might be not safe to use it anymore. You can forget and fix the bug for yourself and, or create a pull request. So, and after that there's some more releases and I always put it like that because I'm this guy I've said. You see here, I have three commits mastered since release, two commits, one commit. I mean, I'm this guy who say, release often and if you fumble back and make a new release it's not a problem. I mean, you get higher numbers. That's also, not that bad. I mean, where are we, Firefox 63? So, it's not a problem to have high numbers and releases. No, release often. If you have a bug fix, please release it because some other people depend, perhaps, on your package and it's important for them that you have a release. Or for example, the PLYR package, there was a bug. Here, in the PLYR that because on iOS 11 there was really annoying bug about the full screen mode. This guy, this Sam, fixed it. He wrote me a message and after few seconds later have released because that bug fix. If you write package release often. If someone create an issue, please answer. Be kind, not, you're fucking asshole, why you found this pack, fuck! It's better to write, oh thank you for your tape or for your issue. If someone create a pull request, that really makes no sense stay kind, perhaps. Okay, we have to go. So, stay kind and stay calm, that's quite important. - [Audience Member] And stay small. And stay small in the kind of package, yes. I mean, I have some package that are really really big and have many many functions but they're just, I don't use them anymore. And every issue, I'm gonna fix it of course. But you can look at it how I wrote on this time, this kind of things, it's okay so, I'll leave it, often. - [Audience Member] so, what's the story behind Jonnitto? And then the Carbon.Link? Okay, that's my last one. Jonnitto, that's my short for all these kind of online name. I mean, Twitter's @Jonnitto as you see here. And Github is Jonnitto and some other, I think. Almost every service has a email, Jonnitto. It's reserved by me. So, I don't know, it was on the bike I rode it the first time. I have nothing to be computer, but with the time it grows. And Carbon is the idea about, carbon is lightweight, it's durable, and it's a really nice material, you can do anything with it. And that was my idea, just to create small packages who do one thing and do this one thing very good. That's why Carbon. Yes. - [Audience Member] Awesome, thank you!