Understanding how to code for the Style System understanding-how-to-code-for-the-aem-style-system

Transcript

Let’s take a technical - deep dive into Adobe Experience - Manager Style System. In this video we’ll - take a look at the anatomy of the CSS - and JavaScript used to style the Core Title - Component using the Style System as well as how these Styles are - applied to the HTML in DOM. This video consists of a simple example Style that’s applied to the - Core Title Component by way of the We.Retail Title Proxy Component. The first aspect we’ll - review is the CSS. In this video we’ll use LESS, - which AEM natively compiles in the CSS. Overall CSS is of - course supported. LESS provides many - advantages in terms organization, - readability and reuse. So if you aren’t using it, - I encourage you to check it out. All right. Let’s get started. This will head over - to CRXDE Lite. I installed the package - with our Example Style which deploys to / apps / - enablement / sites / style-system / clientlibs / clientlib-example. This contains the - CSS, or LESS in our case and JavaScript responsible for rendering the - Component Style. Our example Client Library - is included via it’s category in our case - we’ll piggyback on the we-retail.component.base category - to ensure it is loaded onto all the We.Retail pages we’ll be using. So the entry point - to the CSS in the Client Library is always the css.txt. Our file is fairly simple it - imports the main.less file. So let’s take a look at that. Our main.less file’s job - is to include other LESS files, - these often include Global Style rules, variables and mixins, - but also the component styles as well. In our case we’ll - be providing Styles just for this Style Component. We have a single import for that. Opening the imported - title.less file in component / title, we see that this file - acts in a similar capacity as the main.less file, - but is scoped to the Title Component. At the top are - styles that apply to every instance of - the Title Component. And are naturally inherited - by all Styles. In this example all Title - text is bolded by default. This is achieved by namespacing - these Global CSS rules to the cmp-title selector, which is the wrapping CSS class - used by the Core Title Component. We’ll take a look at - the Naming Convention and what drives - it in a moment. Following the Title - Components Global Styles, each discrete Title - Style is imported. In this case we only have one - style to import ‘example’. However typically a component could - be styled in many different ways, so there would be a - number of imports here. This organization of - breaking out styles by file simplifies managing - and maintaining them. Keep in mind if LESS is - not used, all CSS files must be enumerated in the - clientlibs css.txt file. Next up let’s dive into the - style / example.less file. This is the file - where we define our Example Style’s visual aesthetic, and it looks pretty much - like your typical LESS file. For those more familiar - with CSS, the CSS that the compiles to is provided - commented out below. Looking after example.less - file there should be two main aspects - that jump out at you. First is the CSS Class naming, - and secondly the nesting or namespacing - of the CSS classes. Let’s talk about CSS Class Name - first, AEM’s Core Components for the industry - standard BEM or Block Element Modifier CSS - naming convention. In the case of Core Components, these well-defined CSS class names - are considered the stable API. They can be targeted with CSS - styles and is a generally good practice to follow them or - similar conventions even in custom components, and avoid targeting - bare elements. For example LI or A as this - can lead to CSS selector weight conflicts that can be - hard to hunt down and resolve. So let’s briefly talk - about BEM. Again, standing for Block - Element Modifier. You can think of the Component - itself as the Block and is prefixed with cmp- to drive - home that is as a component. So whenever we see cmp-title, - it’s clear that this Style pertains to - the Title Component. Essentially every CSS - class in the Title Components Example - Style should have the Components - Block and CSS name, since they all - pertain to the Title Component, and as we - see they all do. Next up is the Element. The Element follows - the Block with double underscores and identifies some logical - chunk of HTML. So here we have the Text Element - which represents the Title’s Text and a last-modified-at - Element which well, represents the last - modified date and time. By just using the Block - Elements to name our CSS classes we can quickly - and clearly understand what content of our Component - our Styles are targeting. Lastly we have the Modifier. A Modifier can be applied to - either a Block or an Element and denotes a particular variation - of that Block or Element. Considering this video - revolves around applying an Example Style to - the Title Component, it’s no surprise that we have a CSS - Class that has the Title Component Block or cmp-title followed by the example modifier - or --example. Ok, so now that we understand BEM, - the Nesting or Namespacing of the selector should - start making a bit more sense. The Outermost Selector is - the Block plus modifier or cmp-title–example. This hierarchy allows - only the nested CSS classes to take - effect when an HTML Element with the wrapping - CSS class is present. This provides an easy way - to apply this entire Style. We just need to use - the AEM Style System to wrap the entire - Component with the cmp-title–example CSS class. Whenever we want our example - Style to be in effect. Note that Style rules are - typically not attached to the Block with Modifier - Class, because as we’ll see later this class is attached to - AEM’s Responsive Grid Elements. So unless changing the grid is - explicitly desired it’s best not to attach styles - to avoid potential collisions with AEM grid styles. The next lesson class is - typically the block CSS class that represents the - component in question. This may seem redundant - as the wrapping class already includes the - block identifier but this extra level of nesting - provides convenient selector weight which - comes in handy and more advanced style - system in these cases. CSS rules can be - applied at this level as needed including - things like margin, padding, within height, then - otherwise might disturb the AEM grid if applied - at one level higher. The third level - nesting consists of the styles applied to the - block with elements. For instance, cp-title__text. There are most styles for your - components will be defined. Typically there is - little need to finesse further though occasionally - as required the selector organization - is helpful as a CSS code base grows large - since it helps ensure selector - weight is consistent and well understood - by developers. Following this convention - ensures the weight of each style rule - is three CSS classes reducing the chances - of CSS selector collisions and if collisions do occur it’s much easier - to understand why. Okay let’s skip the javascript - for now but we’ll come back to it while the CSS classes - are fresh in our minds. Let’s head back and see how - the style is applied in AEM. Heading back to our - page we set our example style is available - for application to our title component so - let’s see how it got there. For this we need to open up the - page ‘edit template’, size up to ‘allowed components’ - pages at the policy level. So open the title - components policy. Head over to the styles tab and - you can see the available styles. The key here is we map - this style label. The author will see - to the CSS classes we want to wrap the - components with. So the styles take effect as you - remember our wrapping style was cmp-title–example. So let’s make sure that’s map to - our example style label and it is. Note that when we add - the CSS class here we don’t prefix it - with a dot as whatever is added to this field - is simply injected into the wrapping - elements class attribute This has a happy side effect of allowing us to apply - multiple classes to a single style - label if needed. Let’s head back to the page and - see what actually happens here. We select the style and CSS styles - are applied just as expected so let’s take a look at the - DOM and see what’s happening.

Pay attention to the class - attributes values on the components wrapping div when - we apply our style. Sure enough the - cmp-title–example is added by the AEM style - system and that dictates how this instance of the - title component renders.

So you might be asking - yourself when we’re going to talk about this - last modified date, That’s not part of the - core title componente . So how did it get there. This is where the - javascript comes in. JavaScript primary role in the style system is to - make client side augmentations to the - components HTML. When the HTML provided by - the components HDL script is insufficient to achieve - the desired styling. Let’s see how this works. We’ll head back to CRXDE - and look at the title.js which is directly included - by the client’s js.txt file the use of jQuery in this example - is entirely optional and is simply used because it’s - ubiquitous and well understood. So let’s look at the - top and work down. All the code is wrapped in - the typical JQeury DOM ready event handler and defined - in an anonymous namespace. The bulk of the - work is done by the ApplyComponentStyles - javascript function. So what we’ll be doing - for the style is executing javascript - that will derive and then inject the - last modified date for the current page beneath - the title text. So let’s see how - this function works. First it finds all title - components in the DOM. They have the cmp-title–example - style applied. It then ensures the components - haven’t already been processed by checking - for the existence of a marker data dash attribute. Keep this attribute in - mind as we’ll understand the importance of this - a little later on. For each of the title - components it finds in the DOM that meets - these criteria. Each is immediately - marked as processed by adding this data - dash attribute. Next. The last modified - date is derived and injected into our - components DOM. This is done by making - an ajax call to the current pages - model.json selector which is provided via AEM content - services and provides an enriched json rendition of - the page from which we can get the - last modified time the open source moment - json date and time library is used to format the last modified - time into a human readable value and then this value is - injected via a paragraph tag underneath the title text and - also applies the CSS class name cmp-title__last-modified-at that follows DOM - naming convention. So this function is fairly - simple but we still have to figure how and - when to invoke it. There are two hooks - we need to consider. The first is on page load - or on the DOM is ready. And since we’re already - in a DOM ready event listener via the wrapping jQuery call. we can - simply call the function applyComponentStyles - immediately. This will ensure that whenever - there is a page load such as a user loading the page on - AEM publish our javascript will execute and inject the last - modified time into the DOM. The second hook is a - bit more interesting. Under the covers AEM site page - editor updates and injects components into the DOM during - page and component authoring to ensure the styles are - applied appropriately during this authoring - experience. We need to execute the - javascript whenever we notice inserted into the - responsive grid as well. We can do this by binding - the applyComponentStyles function to the DOM - notice inserted event for the responsive grid. Now you might remember our - applied component sales actually inserts a new node “

” an - element into the DOM since we just added an - event listener that calls applyComponentStyles - every time a DOM notice inserted - we need a way to prevent the insertion - of our paragraph element from kicking off - the cycle all over again. And this is why we need to - apply and check for it the data dash attribute - marker indicating if a component has - already been process. So far then our Javascript - based style application from spinning off into - an infinite loop.

If we had back to our - page we can verify our understanding - of the javascript by first viewing the source of - the page which is the HTML. That AEM generate server side - and serves up to the browser. As we can see there’s - no paragraph tag with our last modified - data in HTML. If we look back to our - Web page and inspect the DOM we can see the - paragraph element has in fact been injected into - the DOM by the javascript and we can also see that our - data dash attribute markers applied indicating that - this has been processed. The last thing to note is not only - can components have styles applied. Below containers and pages - can have them apply as well. If the approaches and - conventions align in this video or followed styles - the layout container or page levels will - cascade down and apply to all applicable - components therein.

It’s worth noting - that when styles are applied at the page - level the CSS classes are added to the - body tag itself and when applied to the - layer container the classes are applied at - the AEM grid element level. All right well that - about covers it. I hope this is giving you - a decent idea about some of the technical - underpinnings and how you’d worked with the - AEM style system. -