
Looking to learn more about handlebars and front-end engineering using Brightspot? Start with this training, led by our world-class team of experts.
Click here to download a copy of the front-end training deck.
Transcript
0:06
Everyone, we will get started here in a couple of minutes just giving a few more minutes for, for people getting logged in here, I think I'll just give everybody one more minute, Go ahead and start after that.
1:53
Alright, Liz I'm assuming that you can hear me and see everything, yep.
1:59
All good, awesome.
2:02
Well, hi everyone, my name is tom happy, I'm a friend and architect here at bright spot and today we're just gonna be going over some, you know, basic kind of cliff notes around front end development over a bright spot.
2:16
we've got a number of things that discuss, we're gonna be going kind of over our whole front, front end stack, like really what front and front end development here entails going over each of kind of the portions of that stock, talking about what this style guide thing that we have is talking about how we kind of bundle our code and then getting a little bit in slightly in depth into handlebars, which we use for template ng.
2:46
Going over a little bit how we do javascript and styling and talk about kind of how we can figure not only the style guide application, but how we can figure out how the theme works with our CMS.
3:00
And then lastly just go through a quick code example, showing showing exactly kind of, you know, the inner workings of everything.
3:11
so to kind of start off with like what does front end here mean?
3:16
So for us, front and development is basically everything you kind of think of as front end of html, you know, dealing with templates and CSS javascript but in addition we've also built a number of ways and controls for the front end developers to create views and most importantly incorporate publishing features into the right spot.
3:40
So we can not only write the front end of the site but also if you create editorial, you know, controls for editors to kind of change the front end around a bit.
3:56
so our front end stack you know, these are kind of our technologies we use Jason mostly for configuration files as well as setting up the views, which is, you know, the what kind of data we need on the front end, we use handlebars to deal with html template.
4:12
Ng we use less as a CSS pre processor will get into that a little bit as well.
4:19
We mostly right, vanilla javascript with es six syntax and then we use a number of tools to compile that into for browsers.
4:29
web pack is our module bundler.
4:31
We use yarn to deal with our workflow and to to, you know for packages and then node we use node to run the style guide application.
4:42
It runs on node and does all the processing that way.
4:49
So now I like getting into each of the pieces.
4:51
We've got this what we refer to as the Root style guide.
4:55
you know, we kind of call this sort of the glue between the front and the back end.
4:59
but the Root style guide it originally lived in the project Root, which is why it's called the Root style Guide.
5:06
but now it's like we've moved everything into this front end folder, so like all the front end things left there.
5:13
so it's located in the front and style guide folder, and it specifies the views which are a collection of fields.
5:21
Each view requires a Jason file and then the handlebar file which is its renderers and it's the hook to be the renderers.
5:31
and then each view results that we create results in the java interface and then that is what the back end has to implement.
5:41
That's what we're going to get into tomorrow in the back end training, talking about how to do that.
5:46
But essentially, the route, the view is Jason, Jason schema and all of the fields that we as friend and developers need to display that particular piece of content on the site.
6:02
so the what we do is for example, create a view that says, hey we need, you know, the article title to show an article, so we will put the article title in the Jason.
6:13
Once we do that, the back end of, do the data modeling, they create the modules inside this CMS and they create view models that place that actually place that data into the view.
6:26
so the contract and sort of the glue between the front and the back end is that Jason view that we create.
6:32
That's the data that we as friend.
6:35
And developers need to show that and then the back end of snow that that's the data they need to provide us to show that piece of data on the, I'm sorry to show that view on the front end how the back end of get that data to us.
6:52
It's that's the business logic, that's what the view model is.
6:56
some of the time, like most of the time the data comes from the CMS because something like an article title could be put in through the CMS by an editor.
7:06
but it could come from kind of a back end api can be ingested.
7:09
It could come from whatever it could be hard coded in the model.
7:12
It that's the kind of stuff that you're going to get into to tomorrow.
7:15
But what's important for the front end of is that we're the ones that create that view that say, hey this is the data that we need to actually show that.
7:26
And then the root style guide again, that's the place where we create these Jason files that are the views for each of those content types.
7:37
so now we'll talk a little bit about the style guide application and by the way, if anybody has questions during this the go ahead and place them into the chat and then I can answer them sort of at the end or I can kind of chime in in the, in in the middle if they're super relevant like the to the slide we're on but go ahead and throw any questions that you have directly into that webinar questions panel.
8:09
So the style that got application, that's what I was talking about is the no Js app and that's an application that runs locally on on local host and it processes the example Jason view files that we create via our actual handlebar renderers.
8:28
and it essentially simulates what is happening in with the CMS data entry and rendering on the actual website.
8:38
So essentially it's, we can create example Jason files that are sort of an analog to an editor filling out that filling out data in the CMS and we're simulating that locally.
8:53
And it uses a dev dev environment of web pack to compiled javascript and CSS and everything is run on local host and it's using the exact same code in terms of handlebars, javascript CSS and templates and everything and the same build systems that the real site does and it's using example data that we create.
9:18
and it allows us to work locally and then see our work instantly and because it's using the exact same code as the life site, you've got trust that the same code is going to work correctly once deployed.
9:32
So again, this is our this is our way of being able to work without a front end developer having to run an instance of the CMS and then having to write a whole bunch of code and then compile that into a bundle, deploy that out into a CMS, just to see what they're doing, just like, you know, verify some CSS or something like that instead here, what we can do is work locally.
9:59
every nothing gets auto built, so when you compile some, so when you write some CSS and it's safe, it automatically gets compiled with the same thing with your javascript.
10:10
and the same thing with the handlebar files, so you can directly make some changes and instantly see them.
10:15
And we'll see an example of that at the end, When I go through the code example of me, like just like editing some stuff and see it working that way, You can kind of see how quickly we can develop locally.
10:28
So now talking about the front end bundle, the front end bundle is we originally called it the theme but the word theme is a little bit weird in the sense that like people just kind of what they think of when they think theme, so we just renamed it sort of to the bundle and that's really the whole front end of the site.
10:50
It's what we basically, all that we work with is front end developers because it has everything to show the front end of the site.
10:58
It includes and contains all the handlebar files to deal with all the rendering, all the javascript for interactivity, all the actual CSS that's been compiled from the less files that you know, our source code, it includes any static assets, so, you know, obviously most at assets are going to come from the CMS such as, you know, like an image or something like that for an article but if you have any, like S V G s or icon files are kind of hard coded assets that we don't actually want in the CMS, they're also coming in with a bundle so that the CSS and html can refer to those directly and that includes all that, Jason that are the configuration files and all the the view examples as well.
11:43
and so you know, we'll go through each of these and kind of talk a little bit more in depth about them, so handlebars for rendering html.
11:53
So bright spot uses handlebars as our temporary language.
11:58
we like that because it does have in its logic list.
12:03
So it provides a strong separation between you know, your template styling and javascript.
12:09
And even though it is logic lists and and it's supposed to you know by the base and it's supposed to be period logic list.
12:16
We realize that by providing a set of helpers we can really make composition of templates quite a bit easier and a little bit more straightforward.
12:29
and then with those helpers we use comparison helpers, logical helpers and some math helpers and you also have the option to create your own.
12:39
and there's a link in the presentation to actually if you just google bright spot helpers.
12:45
It leads you this is the first result out in google and that's where we not have the collection of helpers that we have, I'll go over some of the most common ones that we use here and talk about them and but one of the things to to note again is this these helpers are meant to assist in the comp position of templates so you really shouldn't be using these things.
13:10
And you know, you still still still should be using handlebars as a lot as logical as possible and just use these these helpers and creating templates going through some arrays, checking against some math numbers and not doing things like dealing with strings or inserting data or or things like that because that's really what what should be done in the CMS and in the few models And then there's a couple of questions here that the by the way, I forgot to mention this at the beginning of this whole presentation.
13:44
Yes, the recording of this is going to be sent out and then as far as in the slide earlier we're talking about the theme versus bundle.
13:58
and then yeah, that theme we've got the it's the front and bundle is in the application and the directories as well, it's it's called the bundle now, instead of thinking the old like some some of the older bright spot versions, we had themes everywhere and now we're calling we do have it's called the front and bundle everywhere.
14:19
so some of the front and helpers like I said we've got some equal greater than less than just kind of very standard comparison helpers, they're not in handlebars by default, but they're great for moving through item arrays with some logic or some conditional renderings.
14:38
And when I get into the code example, I'll show an example of that.
14:42
but for example, if you want to, you know, maybe make the first item in a an array be different or something similar to that.
14:51
This these are great helpers but again, we shouldn't be using something like this for string comparison because that's where like stuff can get pretty nasty and then you're kind of building lodge like super big and logic into your templates.
15:05
We really want to use these more to help you move through item arrays.
15:10
Another really good one that we've sort of used all over the place, our setters and getters because we do a lot of delegated rendering where for example a list has a set of items that that renders each of those items.
15:28
Those Children items don't actually have scoped to the parent list or some settings or some things that the parent list might want to push down into its Children.
15:39
So now we've created some setters and getters that allow us to set and get variables or values.
15:47
and then that's really helpful in reuse of templates so that you can have a Children template that can get reused across a number of parent templates and the parent can just set some values throughout those.
16:00
We use this a lot in image sizing which I'll get into an example of that a little bit later.
16:08
We use an include helper and that really sort of works well with with the setters and getters from from four because it literally includes another template within a template and passes it the current data context.
16:23
So this really supports template reuse and this is sort of the main tool we have for template reuse because for example we can have a template that renders an image or a template that renders a link and as long as we pass it, the data that it needs, it can render that.
16:42
So that way we don't have to literally render a tags in every single place where we need a link.
16:48
We can just include literally the link template and pass it the data that that particular parent template is trying, it has to do with a link and then that way link is rendered.
17:00
So we do a lot of our template reuse using the include helper and then we've got this render helper, that is this contextual rendering concept and that allows us to render a specific style of the template as the default one.
17:18
So this one is great.
17:20
For example, if you have a whole bunch of different styles of an existing content type, so if you have a lot of different looks of a list, then the editor, when they start, when they create a list in the CMS, they can chew choose the style of rendering of that list, whether it's a grid or it's a list or whatever.
17:42
However many different styles we might create for that particular content type.
17:47
The contextual rendering concept allows us to basically specify a default style if the editor does not or allowing the editor to maybe not have to even make that choice, but it's just like hey on this particular section page we always want to render a list as a grid style and then the editor can go in and override it to be a carousel if they wanted to.
18:11
But by default it would render it a certain style, so we use that in selective places where it does make sense for that.
18:21
And then we've got a resize helper that we've created that deals with image sizing.
18:26
The resize helper is a directive to get a specifically resized image from dims which is our image sizing system that lives in the back end.
18:38
And then this can be used along with the set and get helpers to allow for code reuse and to do contextual image sizing so that you can have you know the template that is reused a whole bunch and a parent can just set some image size so let me get through and show actually this kind of in the code, I think it's a little bit helpful so you'll see that we've got this image tag that is a template that we have that uses the resize helper to resize an image to a particular size which we specify in a configuration file.
19:19
There's also a a fallback helper and a get helper and it's all used kind of together here that says it re sizes the image.
19:30
and it tries to use the image size getter if it's been set and if it hasn't it will resize you to a large 16 by nine, which happens to be our default image size that we have here in this particular bundle.
19:45
And then you can see where in page promo module a which is a style of page promo module.
19:53
we set the image size to be a certain value that you get extra large 16 by nine instead of the default regular 16 by nine.
20:02
And then we use the include helper to then include the page promo media which then that the file also includes the image.
20:14
And then that way we do a lot of template reuse by being able to use something like set being able to use include, which eventually comes all the way down to this, renders that actual image tag which actually happens to be inside of a picture tag as well.
20:31
And once we get all the way there get helper gets that image size that you originally set and specify as a custom image size for this particular module, whereas a different style of page from a module could use a big square image or something like that and then the rest of the code gets reused all the way down using these includes and eventually uses this resize helper to make sure to get the proper image size from from dims.
21:02
And those image sizes are specified in a configuration file which I'll show a little bit later and then that's where you tell dims, you know what the width, what the heights, what the etcetera is for this particular image name.
21:17
So getting back into the So sorry, so that's about what we all that I have in terms of going through the individual helpers.
21:25
Like I said if you either google bright spot helpers or go into the link that's at the top of this section of the presentation that's got the rest of the helpers and how to use them with documentation and whatnot.
21:43
So now getting a little bit into javascript and making the site interactive.
21:47
We use basic vanilla javascript.
21:51
That is E.
21:51
S.
21:52
Six.
21:52
That's a mixture of classes and custom elements.
21:56
We use Babel to transpire it into browsers that we're actually gonna support.
22:02
We use the browser list to to deal with that depending on what browser support you need.
22:07
And then we use web pack to combine our javascript into a combined javascript that's like an all java all day.
22:17
Yes, that's kind of included in every page as well as chunks for whether it's you know, it can be manual javascript loading.
22:26
That's you know, you could include as you could compile a certain file that maybe only a proportion of the pages, proportion of the site's gonna use.
22:34
So for example, if you have a specific big application that's maybe on a you know, a leaderboard page or a module that is very complicated, that you don't want to compile it into the rest of your javascript, you can do it there or you can use dynamic dynamic loading where for example, when we do a carousel we use a dynamic dynamic loading to chunk out, for example.
23:01
Arf lickety javascript out into a dynamic chunk that is only loaded when a carousel get substantiated a page that way it's not compiled into the into all the javascript that is loaded at the beginning of every page I guess so we use custom elements to bind javascript to the dom.
23:24
and then for most content driven sort of, I use static and quote here websites, but content driven websites that are primarily to do with, you know, putting out content there's no really need or we feel that there's no need for a full javascript framework like react as there is to to drive the main site as there is no state or kind of used to handle on most pages.
23:52
This allows us to use javascript to make the site more interactive and enhance the html versus using it for actual rendering.
24:01
So that way we're using handlebars to deal with all of the rendering you're getting static html.
24:07
The that is then heavily cached, it's got all the S.
24:10
E.
24:10
O.
24:10
Benefits and everything else.
24:12
Rather than creating a Javascript application to deal with that sort of basic rendering than having to go through hydration and then having to go through dealing with how we're going to serve that.
24:24
We're using javascript to sort of again enhance these sort of static sites with interactivity and that's not to say that we can't not only use react or a framework like that four sections of a site that are that are necessary and that are very dynamic or you know applications that might be part of the site and then that's where we can use that web packed again sort of chunk those out as either dynamic or fully static different files that can then be included on certain pages.
24:58
So for example if we had something like a very complicated leaderboard application on an otherwise content, you know driven site you could make that leaderboard application a react app that uses graph QL to pull its data does all of its rendering and it's an actual big old application and that thing can be in stance created via a custom element and that whole application can come that way to where the page is still in the CMS but then the rendering of that data might come from some A P I and use react.
25:32
So we definitely support that and we definitely have done that and use that but again, for sort of the generic, you know, page that just has content, we feel that that's better to use html template ng.
25:45
And then use javascript to make the site more interactive.
25:49
and then for the what I was talking about loading javascript and web back chunks you can see for example.
25:58
This is a very straightforward little custom element.
26:02
that is a carousel, that is a custom element.
26:06
and then it has an asynchronous connected callback so that whenever a carousel is placed by an editor on a page, this little tiny bit of javascript gets compiled in an exit and pulled into the all dot Js.
26:21
This is on every page because there might be a carousel but whenever it is and whenever it does get detected in the html, then we do a dynamic import of Clickety, which is the heavy code that is driving the carousel.
26:33
So we really only have, you know, some options or something like that that that that live here.
26:38
whereas then web pack takes this chunks out, flick it to be a separate chunk that gets uploaded up and then whenever a carousel get substantiated it dynamically imports that javascript.
26:50
so that you know, because because you need it but you don't want it compiled into every single page and come with you for every single page.
27:01
So having said that now let's talk about some of the styling and how we do C.
27:08
S.
27:08
S.
27:10
so we use less as our CSS pre processor.
27:14
There is no really like this isn't like baked in and like we have to use less, we just chose it as our default bundle and you know, bright spot go and what sort of comes out of the box with the bundle that we create is using less.
27:31
And there's no reason that if you know for example you were doing a front end for a new bundle from scratch or something like that, you could buy by all means use sass the only really thing that's making this be less is the fact that in our web pack configuration we're using a less processor and we write our CSS with less less syntax, it would be pretty straightforward to convert that to SAs or use, you know, the vanilla CSS or however you wanted to write your CSS.
28:04
But having said that we use bem style syntax for class element and naming versus moving our CSS into like a fully object oriented CSS kind of boot style directive based html.
28:21
We feel that this sort of bend style and I use the words them style because it's not purely bam like by definition it's just kind of that style and it allows for sort of CSS changes, bug fixes and we feel that they're less likely to create regression issues because the bench style syntax when you're writing your code, you're actually making changes to elements or modifiers or even blocks that and you kind of know what you're doing, you know what you're changing and you're not really affecting huge other portions of the website where it's kind of an object or a CSS architecture really puts the control of the CSS into this like one major area and if you make changes there, you might be affecting lots of other places that have used your object oriented CSS classes and you might, you know, make some really wide changes when you meant to just fix a small bug on some particular module.
29:20
And also this allows, you know, we feel this allows multiple developers to work together more easily or for somebody to just like jump in and some somebody to do a little bug fix on a particular element of a particular page, that Again, without really messing up something else, without having like full knowledge of how the object oriented CSS framework works for that particular site.
29:46
So that's why we've gone with sort of again, the bench style class names.
29:51
So having said that, we use descriptive names for modules, components and then we use kind of that bend methodology to name their elements.
30:02
and then we use less abstract certain styles.
30:06
It allows us to use less extends or mix ins depending on the use case.
30:12
Same sort of concepts as with SAS.
30:15
But to show a couple, I mean show a couple of code examples on this.
30:23
So there so you'll see for for example when we create a page list you know, there are gonna be some classes that are that belong to that page list such as for example, a page list header can be You can use the page list class and it can have all of its styles combined and I'm sorry, all of its styles in page list and then pull them from their But a page list.
30:57
That is a page list standard a which is a style or a look of the page list module.
31:05
It can then Right, it's CSS in this in a way that it can edit the way the page list items look.
31:15
Or you can use the less patterns for example that if you want to use less extends, we create these title elements in our less and then they can be extended onto particular instances of episode.
31:33
Promo title has a number of sizes.
31:36
And this particular list wants to use this particular title instead of the default.
31:41
That's created on page promo and this sort of pattern gives us some pretty fine grained control over what you're doing in terms of styling, in the sense that we've got these blocks and these like, elemental codes, such as like a page list and the page list header and how page list items might be displayed on this level, but then you can override those kinds of styles on individual list styles or individual promo styles, which give you very fine grained control, but we feel that going about this method not allows us to sort of re use html templates all over the place because you're not putting those directives into html classes, you're putting these directives into the CSS.
32:30
and then it's easier for somebody to sort of jump into this CSS file and say and see what's happening.
32:36
The fact that, you know, page the standard a has, you know, this kind of font on page promo, trying to do that versus having to write that in the html promotes not only reuse, but then again, a developer can come in and be like, oh, I just need to change the font on this promo title for this list.
32:56
I know kind of where that is that's in the CSS instead of having to hunt that down somewhere where you might not know what's happening with that.
33:06
So, let's talk a little bit about there it is.
33:12
Let's talk a little bit about CSS variables and less variables now.
33:16
So we do use CSS bars through throughout a lot of our CSS whether that's in line, in the actual CSS or in line html And we do that to allow to create a pattern where editors can set CSS variables through CMS.
33:35
Editorial fields, like I said in the beginning, the front end team can create can create editorial fields in the CMS which we can then use we've we've done that with a number of with fields that allow editors to customize the CSS of the site using CSS variables and then we do use less variables for places where just using a reusable variable is helpful.
34:01
but those editorial overrides are not really necessary.
34:06
but I think the majority of our variables can be like I said, we can say that there are CSS virus and the show a few of these kind of show this pattern as well.
34:18
so we have you'll see here that there is a large number here of CSS variables that we set based on fields that we've created this front end developers and then put into the CMS.
34:34
So just to go with the first one, there is a primary color that a editor can choose when they when they set the theme on a particular put the bundle on a particular site, then they can go through and and customize a number of fields and they can set with the primary color is and then we set a CSS variable with that.
34:58
And then in our last file we go ahead and we set that color from the theme that they might have over it and create a little fallback for ourselves, let's say like if the editor doesn't it's gonna be red, that's our sort of default color but if the editor does set that it will set this color primary variable to that.
35:23
And then throughout our CSS we can then use these variables or override them again or do whatever we need to.
35:32
So for example, another one also is like you can set the color, the background of the header of the site and again that is here The editors have this header background color field where they have a color picker pops up and then if they don't choose the color it'll default to a white background for the header.
35:55
And then the page header code is what actually uses that CSS variable here and then that allows us to again have editors control over the background of the page header but create some fall backs for some colors if they don't do that.
36:10
And we use that pattern a lot for whether it's colors you can see there's colors, topography etcetera, anyplace where we want to provide that editor control over the CSS value.
36:29
and then here you can also see a pattern where we we are using CSS variables to reset our header height.
36:35
So while this is not a value that is being edited by editors this pattern works out really nicely for dealing with that like a header height where we just set it once in our header bar here.
36:52
and then we can we just change that variable around here with some media queries.
36:57
We use that pattern also quite a bit to deal with CSS bars.
37:00
Sometimes we do less variables for some things like for z indexing for example, something that might not be changed through media queries or otherwise.
37:10
So we've got a mix of CSS and less far as depending on the contextual sort of use case for that.
37:20
So now that we've got through styling we'll talk a little bit about Jason and how we use Jason for configuration files and to create this view examples that I was talking about in the beginning.
37:33
So to start off with I think the major use of Jason is creating these views and then also creating view examples.
37:43
So when you create the article page view and put that in that route style guide that tells the back end here are the fields that I need to render an article but then to use in the style guide application for ourselves, we create these Jason view examples that are used that are simulating how the CMS is actually going to fill out those views and that allows us to create examples of these content types or not even like in a content type or an entire page locally and view that in our style guide application, so I'll show you a couple examples here of that so for example, we've got a page view which has a number of fields that a page has, so we put that in our bundle style guide and then that is what fills out the view for what a page has that has all the values like it's got a logo, it's got foot or logo, it's got navigation, it's got etcetera.
38:50
We put examples of all of that here and then an article page is inherits off of the page, Jason, so it pulls a lot of those values from that but then it has fields and we're simulating what an editor is doing when they create an article page in the CMS where they, they're gonna drop in.
39:11
Some authors, they're gonna drop in some tags, they're gonna put a figure or an image into the lead of the article and then they're going to create an article body.
39:20
So here we create a bunch of Jason that simulates what an article would look like.
39:26
And then you can see there's a template here that this article pages rendered via article page dot handlebar file.
39:33
and then this allows us to process this article, Jason example that we created with this handlebar file and when we run the style guide application, it processes this Jason with this handlebar file, just as if you publish this bundle out to the site.
39:50
the back end is what's going to create this Jason out of the actual CMS editorial fields that have been created and they're gonna fulfill this view fulfill that view with all of this data and but it's going to process using this exact same handlebar file.
40:08
So whether you're viewing this in the local style guide or on the full site, it's being processed by the literal exact same handlebar files.
40:15
So when you simulate it locally, you're, you're, you've got pretty good confidence that when you get this out into the real real world, it's gonna show up the same exact way.
40:23
And so this is an example of an entire page, but much in the same way if we have just a small little a little module, if you will the page list module.
40:35
and then here again, here's some particular, here's some examples where we create a Jason file for this particular module, we give it a template.
40:46
We give it a style variation template also to simulate an editor picking a certain style of this particular module in the CMS and then we give it some data.
40:56
and then so then where we can display this module and and look at it in the style guide.
41:03
So we also use Jason to deal with all of our configuration files.
41:12
there the mechanism that we use to define how the bundle interact with bright spot, but we also use configuration file to configure that style guide application.
41:25
So for bright spot, actually, whether it's nostalgia application or bright spot itself, the configuration files are image size options where we might specify all the individual image sizes.
41:38
they specify all those additional fields that the front end can add into the CMS such as when I was talking about those color color pickers or things like that, that we use these.
41:49
Config files to specify those fields we use also.
41:53
We this is how we provide style variations of content types.
41:57
So for example, a page list content type is just a list of promotional modules.
42:05
So that is how that's kind of like a bread and butter content type.
42:10
Where it's just a list of, let's say, you know, list A promo module is a picture of a title and a description and a link and a list is a list of those items.
42:21
That's kind of like a standard module that's used all over the home page.
42:25
And the homepage is just a repeat of those modules, but then they have different style variations because one's a grid ones, a carousel ones.
42:32
It's by itself on the page.
42:34
So this is where we we create the configuration to show all these different style variations out to the editor.
42:42
And then we use configuration files also specify options for the style guide applications such as like the navigation that shows up in the style guide app.
42:53
All these config files get pulled in together at runtime and build and combined into this one large configuration.
43:03
But we kind of litter them throughout the the folder structure and the code base In subdirectories we do that in order to just make it easier to read.
43:17
So that way, if you're dealing with the page list module, you can put that in the page list folder.
43:24
If you're dealing with an R article module, you can put the configuration for that module in the article article page folder rather than just kind of having them all together and having this giant config file that will end up having a bunch of merge conflicts if you have a bunch of developers working on it, and then to go through a little bit and and dive into each one of those options.
43:47
So we use it.
43:49
Again, Jason can fix for image sizing that is in the root of the theme and then that's the directive to dims to give you a particular actual image that is requested via the resize helper that we talked about earlier.
44:03
So here you can see a link to the image sizes configuration file where we define some some small some medium some large images and we put you know we we put the aspect ratio in the name just so it's easier to see.
44:20
and then this is where you define the width and the height of the particular image in pixels.
44:25
There's also you can choose variables and not fixed images so for example, you can say something like this where the it's a 14 40 wide image but it's not a fixed aspect ratio so it will return of 14 40 wide image with whatever however many pixels.
44:46
The original source image was uploaded into the CM into the CMS.
44:50
So if you specify a portrait I'm sorry if you request and this crop name of a portrait image, it will return you a super duper tall image because it's going to be 14 40 wide but if you have a super landscape image, it's going to be super short.
45:08
If that was the original source that was uploaded into CMS.
45:12
This is where we can also provide some source set descriptors to deal with picture tags and where we can specify alternative formats for images such as web P.
45:21
So if we want to get make that have dims return your web p version also of this particular image.
45:29
This is where you can make this a designation and then we use that in the picture tag to create responsive and performant images.
45:42
So now we're talking about the front end field configuration we can specify additional fields that are added into the CMS for editors kind of talked about in the beginning and that all those allow editors control over styles of content types or particular you know, fields that like a color picker or something like that?
46:07
These fields one important thing about these fields is that they persist only for this front end bundle.
46:14
They're actually not part of that content types data and that's one of the most important thing about these front end fields is that you're not actually changing the data for that particular content type, You're just changing Are you that you're as a friend of developers allowing the editors to change or to add some additional data to that content type for this particular bundle.
46:41
So if you have two different sites with two different themes, they could take the same piece of data but display something visually very different depending on what has been chosen for, created for styles in that particular theme or bundle.
46:59
This is a very useful tool for adding additional styling options to modules such as background colors, image alignment etcetera etcetera but it shouldn't be used to supplement the content types data because if you do that, that data doesn't actually ever exist as part of that content types data.
47:23
It just exists for this particular display of the front end of this, of this bundle.
47:29
So, for example, if you had a feed that you were, you know, if you had an article and you added a subtitle of an article using this field that sub entitled to, that article wouldn't actually exist in the data and it wouldn't make it out to any feeds that have to do with that article because it would only be for that front end bundle, which is again why we sort of want to use these fields for things that have to do with display options because that's tied to this bundle or or theme depending on where you want to use.
48:02
So an example of that is that we we specify these fields and these fields, configuration file, we specify them here because a lot of these fields can be reused across different modules, so we don't want to specify them in each of the individual module, configuration files, but an example of this would be that, you know, page promo module is a single module.
48:28
That is a page promo content type that has, you know, an image of text, a link, and a description or something like that and in a category of byline.
48:37
And so certain styles of this might have some text alignment or an editor might be able to change the image aspect ratio of the image that goes in that Prima module.
48:50
or they might align, you know, put the image position that's horizontal is like this particular module style happens to have the image aligned next to the task sorry, next to the text horizontally.
49:05
So an editor might want to position the image the left or to the right.
49:10
So that's why we have this and this is where we say that when an editor select this style in the CMS, then they get all these additional fields that are shown to them for that particular style where they can choose to, you know, hide the category and that promo module.
49:29
If you want to make the display easier, you can show the byline on that which is kind of hidden by default and are in this particular bundle.
49:38
You can choose the aspect ratio, the position of that image.
49:41
That how wide that images, whether it's like 60 you know, 60 40 or 55 50 or they can change the background color of that entire module or they can inverse the text color.
49:52
So if they choose a black background, they can do in verse two colors to be white.
49:56
or we've got some options for like animations to where you know, as you scroll down the module might animate in or something like that.
50:04
And then the editors can make all of these choices editorially for this particular style or instance of a module.
50:10
and and we create these fields here in this configuration file, so we can create some bullying fields.
50:18
we can create, we can grab records, so we can choose like a background video of a particular style, we can choose images to do a background, image or image, color.
50:29
the color type will choose a color picker.
50:31
So as front end developers, we can influence what the editorial interfaces and we can give control of the editors for these visual to add these actual visual elements or control these the visual representation of these of these modules.
50:53
So that's basically, you know what I have for the general overview, this was definitely meant to be kind of like a cliff notes around how the front end is is done here.
51:07
If you guys have again, any sort of questions about over actually, you know what I just called down and I see a couple of questions, so I'm gonna go through and look at these questions and kind of answer them right now and after I do that, we'll go through a quick code example that will show making a new style of the list content type and on how some of these concepts are used.
51:34
So Danny mentioned that the link for the helpers is actually broken.
51:39
So I said if you google bright spot helpers the first that comes up and I'll fix that link in this presentation before the presentation goes out to you guys.
51:50
So the includes are different from handlebar.
51:55
There's a question about how includes are different from using just handlebar partials.
52:01
these handlebar partials have to be sort of defined as partials and before they can be used where this the include helpers allows us to basically essentially literally point to a different file to be included in that particular context.
52:23
So instead of it being kind of a helper that has to be created has to be defined etcetera etcetera.
52:29
You're just creating you know, you're creating a file and then you're literally including that file, so it's a little bit sort of easier us And then also so the big thing is it it allows you to include helper allows you to pass data and change data that you pass to that particular to that particular file.
52:53
So we felt like that pattern kind of allows for better code reuse.
52:59
So we kind of use we use that include helper instead of handlebar partials sort of by default.
53:09
Okay, and there's another question about update, Like updating?
53:15
No Js or detaching no Js for using different tools, like so the like node isn't really built like there's no like attachment or anything or is it like it's not built into here.
53:31
The style, that style guide application just happens to be built using node so that when you're running the Style guide app, and you want to preview, you want to work locally and you want to see all of these Jason examples and have your handlebar process.
53:47
That's a no Js app that runs as far as using that like it's not really however you want to use different tools or frameworks in your javascript, that's in the front and bundle, you can just do that and there's nothing preventing you from using different frameworks or using something like react or using a view framework or state framework or something like that to on the front of the site, you can just do that and and include that.
54:19
you're not like we're not actually using node to display the front end of the site.
54:25
We're just using node to run that application which allows you to sort of simulate the CMS locally for faster local development.
54:36
So that answers this guy's your guys questions if it doesn't let me know and I'll try and enter in a different way.
54:47
so now we'll go into the code example that I have.
54:51
so the example that I have is making a new list style so when you first run run the style guide you'll notice that there is a large number of list styles that we have.
55:07
And a a list a page list is a content type that has pull up the the repo here.
55:17
So a page list is a content type That has a look in the root style guide and show you a page list.
55:31
A page list Is a content type that we've defined this view here where there's a title, a description a set of items as well as like a C.
55:44
T.
55:45
A.
55:45
Button that can be displayed underneath it.
55:48
And then items are either page promo or you can have like some little html module so you can insert some weird stuff.
55:55
Or it can be like an ad that's inserted between the items editorially.
55:59
But for the for the kind of main use case a list as a a list of items which are promos.
56:07
So like I said, that's kind of the bread and butter of something like a homepage.
56:12
And so we as friend and developers and our default bundle have created a large number of styles of the page list and we've named them here sort of in these little categories just so they're sort of easier for editors to to see and to understand what they're picking but we've got some page lists that are carry cells.
56:32
We've got some that are standard that we called standard, we've got some page lists that really only belong visually and like a right rail or or a rail of the site.
56:43
and you can in the style guide, we create a navigation that that displays all of these on the left.
56:51
So when you run the style guide application, you can see all of these different styles.
56:54
So this is a all of these different visual representations are the list content type.
57:02
but they all look differently.
57:04
Like, for example, pages Standard A.
57:07
Has this like larger image here, you've got four other promos and some of the grid on the bottom B is a stand very standard grid where editors can specify whether they want maybe two column grid for column grid by default.
57:23
It's a three column grid and, you know, so on and so forth.
57:27
So that we create like, you know, list D.
57:29
Is kind of standard single column kind of thing.
57:32
And we created a large number of these things.
57:34
So a lot of like the asks of front of development teams are to either create more of these or create different styles, that's what we're gonna do, is we're gonna create a new style of a standard of a page list module.
57:51
So to kind of start with that, you know, you you're gonna be provided you know, a design because this is, hey, I need you to provide this new look and here, maybe it's like I'll just we'll create a new style and I'll just give it kind of a generic look just because I don't quite have a design.
58:08
But what we're gonna do to to kind of start this as as developer is that you're gonna we're gonna create another style.
58:17
We've got lists, page list, standard, A through L.
58:21
So we'll create a new style, will name it.
58:23
M we use this naming scheme because coming up with names for all of these list styles is actually really difficult because everybody has a different kind of opinion on how they want to name it.
58:36
So we just decided to go with sort of the alphabet naming scheme in at least a default bundle.
58:43
And then in the configuration file you can actually choose a display name.
58:47
So if a particular project for client or editor or whoever wants to is using this bundle or you're creating a new version of this bundle or creating a these are creating that.
58:59
You can give more descriptive display names.
59:03
But since everybody has an opinion, we just chose not to have our own here.
59:07
But just to make these alphabet names.
59:08
So we'll be creating a page list standard M which which will just have a different grid look from all the other ones.
59:17
So to do that.
59:19
we will create the handlebar file and the Jason example of this and you can see that here where we've created a handlebar file to go with paige with standard M we've given it a class name, which is that black standard?
59:36
Standard M which is what it is.
59:38
We use this include pattern too to include the list header which actually includes the title and description.
59:46
We'd use that to kind of give it this sort of pattern to create a standardized list header across all the different list styles.
59:55
And then what we'll do is create a couple dibs to house all of the items that that page list is gonna have.
1:00:03
And then you'll see here we're actually using the a helper that says if for the first item in the array, what we're gonna want to do is set a larger image size.
1:00:19
And then use that include helper to include the page promo module.
1:00:23
That's it's basically child.
1:00:24
We're going to delegate the rendering for those Children over to this page promo.
1:00:29
But again before that we're gonna set an image size to be a large 16 by nine image because we're gonna have a slightly different grid where the first image is bigger than all the other ones.
1:00:42
So this kind of pattern allows us to create to reuse this page promo renderers for the child but again to use something like a setter on the first item to give it a larger image size.
1:00:57
So this is why we do that include pattern while we do this.
1:01:02
So that that page promo code is included once rather than having to copy and paste that code all into these parent templates.
1:01:11
And then what we do is we create ourselves a very straightforward example of this page list standard.
1:01:17
M so if an editor were to go into the CMS and they were to create a new page list, a new version of the page list and select the page list.
1:01:28
Standard.
1:01:29
M template that we that style, this is what the Jason would look like, that.
1:01:36
It is a page list template.
1:01:39
But the style the template which is the style that the editors chose is page list standard.
1:01:45
M.
1:01:46
That's the render that we created up here.
1:01:49
and then you know, we give it a title just so it's we want that notice we're skipping the title description which is no big deal.
1:01:56
We can add that later if we want to see what that looks like in the local style guide.
1:02:01
We give it a C.
1:02:03
T.
1:02:03
A.
1:02:03
U.
1:02:03
R.
1:02:04
O.
1:02:04
And then in that list in that items array we simulate the editor adding nine page promos into that.
1:02:12
So they might link to nine different articles.
1:02:15
So we're kind of simulating that here.
1:02:17
And so this is our first step in in creating this list style, the next step is we're going to edit the configuration file so we have a page list configuration file here and then we're and if I just pull this show the whole file here, there are, this is where we specify all the different versions of that particular list.
1:02:44
So we have all the different versions of this G H I J K L.
1:02:49
We've now added list em at the bottom of that list because that's the newest list style that that we've added.
1:02:56
we know we're gonna add a couple of very basic fields to that where you can, an editor could specify the background color or of that, or inverse the colors of that particular module.
1:03:07
And then you'll notice in this configure Father some width and height things.
1:03:11
So what are billed does whenever our build gets built and the bundle gets built.
1:03:18
Now we've got an application that goes and pulls up all of these different examples and actually takes a screenshot of that example on in a browser and then puts the screenshots in the CMS so that when the editor sees this list of styles of this page list style, they don't just see like a through M or whatever.
1:03:44
They're actually seeing the screenshots of what each one of these modules look like.
1:03:48
So they have a better visual picker, this width and height actually just specifies the width and height essentially aspect ratio of what that screenshot looks like.
1:03:57
So if we were have some module that's like super tall but not very wide.
1:04:02
We could, you know, make the height taller in the with less or something like that to show the screen shot a little bit better.
1:04:09
Which is but all of these are kind of standard list styles that are kind of gritty or like a grid or a list or whatever, which is why you see the same width and height for all of these screenshots sizes in the CMS.
1:04:21
So anyway, so this adding this into the page list Config gives the editors this new list style that we've created as a choice with the screenshot of this example file that we've created as the screenshot, as a little visual picker for them of what that style is gonna look like.
1:04:43
So the next step now we've got the renderers, we've got the configuration policy that shows up in the CMS.
1:04:48
So now let's write some styles for it.
1:04:52
and then you can so we have this pattern where we just we have an all dot less where we include all the import the styles for that individual version of it.
1:05:04
And then you can see here.
1:05:05
I just wrote some very very basic CSS where we do a 20 pixel gap on a grid.
1:05:12
We add a little border to the bottom and some padding just to make this visually look a little okay.
1:05:19
And then on some since we do all of our kind of styling mobile first we in the medium breakpoint which we used less variables to kind of define our breakpoint sizes all.
1:05:30
so that we're all using the same exact breakpoints for everything.
1:05:34
So in the medium breakpoint we're gonna go to a two column grid.
1:05:38
And like I said I think the first item is gonna span two it's gonna be bigger than the rest.
1:05:46
So that's why I wrote some CSS here to basically say hey the first item in the list it's gonna be across both grids and you know the rest of the items will span one.
1:05:57
And then the same kind of and then now that I kind of see the CSS like sorry we could have just skipped these lines because it's since it's well first we could just only override the stuff that we need.
1:06:09
So well we just go into a four column grid here and then the first item is gonna span all four columns here.
1:06:21
So we've got some CSS written we've got all the configuration files and then our last step here is going to be to add this page list.
1:06:32
Standard M into our style guide navigation.
1:06:35
So so it shows up on the left side of the style guide app and then we've got this like one page that that we've created that has every single standard list so you can see them all together just to make sure everything kind of looks good together on a page.
1:06:51
Once we're done with these four steps we can run the style style guide application and I've already got that running here.
1:06:58
So now I can go to my local host and now I see the Style Guide application running.
1:07:06
So now I've got all my standard lists here so I can view them in context of this novel or I can pop them open and view them in context of an entire page so I can more QA them and check them out and check to see all of that my CSS is working.
1:07:26
But now when we get to the bottom here we see the new standard list em that I added and now you'll see the CSS like everything working where it's got the standard header and then it's got a number of page promos on the mobile view ports, they're all together with 20 pixel gap and a porter, whereas when you get to the larger breakpoint that you'll see the two column grid and you'll see the four column grid.
1:07:51
So this is kind of that that working and kind of now to show like how this whole like working locally here.
1:08:01
So if we want to add some more C.
1:08:04
S.
1:08:04
S.
1:08:04
So for example here we look at this and we're like well this is a larger promo and it's got a big title and then the rest of these like kind of small and the title looks a little bit big so maybe we want to make that title a little bit smaller so we can write some basic CSS here and kind of add that and we can say that if you're not the first item On the page promo instead of having the default promo title which happens to be out size, I want to use promo title six which is an element that we've created in our topography file.
1:08:42
So in the global topography last we create a number of page sort of topography styles that we can then extend throughout our code.
1:08:51
So we created a number of promo titles here where we have one through six and they kind of cascade down in terms of size.
1:09:01
So one is the biggest.
1:09:03
Six is the smallest.
1:09:05
So here what we're gonna say is I want to use some smaller font size for every promo, that's not the first promo.
1:09:12
So I wrote write some CSS save it and then you'll see in the bottom right corner that re compiled my less.
1:09:19
And so now I'm ready to see this new less and now you see my smaller promo promo title font size here locally and it's instant.
1:09:32
Right?
1:09:32
So I can right all of my CSS here and I can change everything locally, hit save and see the stuff instantly in my style guide application.
1:09:44
So that way I don't have to write this code, pull it up in the C.
1:09:48
M.
1:09:48
S.
1:09:49
And and see how it works because I'm checking out locally.
1:09:53
Same goes for handlebars and same goes for javascript.
1:09:57
So if I look at the page list standard m here, I've got the html here.
1:10:04
and I if I make changes here So if I, you know for example like undo all of this code and just make a list of items and then go into here and I undo like all of this this code for the first item.
1:10:24
Now I can make a very straightforward grid, I've got all of that and then instantly I can review my code and now I've got a little hanger because I simulated that an editor adds nine things.
1:10:38
So now as an editor I'm gonna add eight things instead of nine and then instantly go in here and refresh and see and I was like oh I can simulate for example that an editor did not include a C.
1:10:53
T.
1:10:54
A.
1:10:54
U.
1:10:54
R.
1:10:54
L.
1:10:55
And I can see what that's gonna look like and I can check all that code out instantly and I can see the results of that.
1:11:03
and this is exactly what the CMS is, definitely.
1:11:06
See actually the first ones got still the bigger font size.
1:11:09
So I'm like, oh man, I've got a bug in my code, so now I can go in my CSS and say, wow, now that I have a full normal grid, I shouldn't do that anymore, I can compile that, I can refresh that, I can verify.
1:11:20
Oh yeah, everything's looking great here.
1:11:22
Or I might want to take out and say, not first child, so that every promo now get some smaller text because I've got a four column grid and it's like I see all of my changes instantly.
1:11:33
and then this is sort of, this is the main tool and all the main patterns that Oh yeah.
1:11:39
And then to show you this, like I said, we created this also this page with all the standards lists and your seeing all of these lists, they're just shown in this view ports and they're not really in context.
1:11:53
but since we can simulate full page content tiles.
1:11:57
you'll see here in this folder, we created this page with standard lists and this is actually an entire page that includes a page lead and then we simulated in the main of that page and editor adding each one of the styles of each of these lists together into one page and it's a, it's a page so we can view that whole entire page.
1:12:24
So when we pull this up here, it shows this in this little window with this navigation, just for sort of some basic coding, but you can also take these and open these pages up and in a tab and then this actually shows you this and dire page, how it's gonna look like.
1:12:44
And when you look at the code for this page, it is the page as it would exist on the full life site except you're viewing it all locally.
1:12:54
So this is, this is simulating and a standard page content type with a page lead that an editor has added with a whole bunch of page lists where they selected a list style for each individual page list.
1:13:10
So you can look this over locally, this is where you can say, hey, how are these lists working together?
1:13:15
How are these mod working together in the main or is there enough spacing between them that I write all that code properly?
1:13:21
And like at the bottom here, you'll see my standard list em that I've already, like, you know, made it changed up the CSS, It already looks good, I can check all of this locally and now I've got confidence that when I take this bundle and I it gets deployed out in this thurber, that standard list, m is going to work the same exact way here and on the web as well and this is not to say that like, you know, we as friend of developers, we can just like, you know, spray and pray in the sense of just like find this code, checking it locally and just like shooting it out to QA and be like, hey, we're done.
1:13:58
It works local.
1:13:59
Like we still definitely have QA process for developers where you know, we'll create a pull request with this code and that's what like in the training repo you'll see that there is a pr where it is, you know, this pr has been created and like on a normal project we would create this pull request, we can then have our, you know, senior developers comment to talk about the code and then we can deploy these pull requests out to our QA servers so you can deploy that code to a QA server, you can check to actually like double check to make sure it's working and really all you're doing then though is making sure that the CMS editorial interface is working.
1:14:42
That this feels like things are actually getting done correctly in terms of, you know that it's in there is an option for you, the screenshot like all that worked.
1:14:51
the editor can go in and select it, you kind of you want to view that you want to just double check that all of your code is working.
1:14:58
but what you can do purely locally is like I've got 1000% confidence in my, in the CSS here, so that I do know that if like four or eight modules are put in, this is this is what it's going to look like.
1:15:13
And so if I, as a developer am making some CSS updates, I'm, I, a lot of times, I don't double check that on QA because it's just CSS and I'm not actually editing editorial interface with the code that I wrote, which I am doing here, but if I was just changing the CSS, I probably would just go ahead and shoot that directly.
1:15:34
The QA because I have verified that my CSS change is working in this particular instance.
1:15:41
So if I wanted to make this, if I got a request to make the byline date bolt or something like that, I would just write that CSS right here and I would change the I believe it's called just by line if I just do that double check that my code here works and I've got a bold byline and so now if that's all the bug ticket that was put in and that's all that I'm doing, then I will, I've got confidence that that byline is bold and I wrote and said, hey, page the standard m page primo byline is bold and again, this kind of circle back to the object during the CSS versus how we did sort of our BM The reason we do that is because I can just specify something like this while not messing with the html and having this code reuse instead of having to like write those h CSS classes once and then having to go through this html to kind of to direct that this is sort of why we wrote things this way.
1:16:44
So anyways, this is sort of the end of the training, this is kind of what I've got if you guys and then like I said, there's a there's a link to the pr here and a link to all the commits for for these things so that you guys can check them out this whole recording as well as the presentation is going to go out to you guys through list.
1:17:12
and then if you guys have any, like if you think of any follow up questions or something else that you kind of didn't get to or feel free to also if we need to like, if you want to ask, Liz and we can kind of feel through them to me and I can answer them that way, We can also do that.
1:17:31
So there was there's one last question that I kind of missed that what are the task to run the style guide in the same version as the as node and you are used for the build?
1:17:45
that's actually specified in the root of the project and build dot grade file.
1:17:52
I can actually show you that for the training repo it's in this build profile, you specify the node and yarn version in that in that great deal.
1:18:03
And that's what that's what greater will use those will download those versions and use those in the build.
1:18:11
so that's specified right there to make sure that you've got a good match or you know what no diversion, what all the versions grader is going to be using compared to what you're using locally.
1:18:23
so that's where that is.
1:18:27
Great.
1:18:27
Well, thanks everyone for attending.
1:18:30
And like I said, Liz will follow up with the presentation as well as the recording, and thanks for everyone's time.
1:18:40
Thank you tom