Best Practices for Building on HubSpot CMS Hub | HubSpot.Extend() 2022

Hey everyone, this is Best Practices Building for Scale on CMS Hub. I'm John McLaren, I'm a senior CMS developer advocate at HubSpot. I'm wearing a developer shirt and a cape. Very, very oversimplified history. Before HubSpot, I worked for a company named Spin Group Building on CMS Hub. Got super involved in the developer community. Now I'm at HubSpot and I've written a lot of our CMS developer documentation. I contribute to our Developer Academy content, Developer blog and developer YouTube channel. Speaking of which, if you're watching this on YouTube after the event, be sure to ring that bell and let your friends know about this talk. In addition to creating developer education content, I am constantly connecting with folks in our community to understand your needs, your workflows, and relaying feedback to from you to our engineering teams. Today we're going to talk Best practices for Speed Building for Content Creators, accessibility boilerplates and strategies. These best practices come from a mix of my experiences, my conversations with all of you wonderful developers in our community, as well as numerous conversations I've had with HubSpotters over the years. I I promise whether you're brand new to building on CMS Hub or you've been doing it for years, there's something in this talk for you. So break out any note taking tools you like. I'm going to go fast because there's a lot to cover in a short amount of time. At the end, we'll drop one link that has all of the resources that I mentioned throughout this talk. Since there are a lot of friendly faces attending, I want to encourage you as well. If you have a best practice that you've learned and want to share it, drop it in the chat as we go. Kicking off this speed run, let's talk Website Speed. I'm sure all of you are already acutely aware that website speed is important. Site speed is a ranking factor that Google uses and your site speed can indirectly affect other ranking factors such as bounce rate. Ranking well, can help the business acquire leads, leads can turn to customers and customers. They equal profit. Enough about why speed matters though. I think you all get that the part you care about is what can you do to make your site faster. Your main goal when optimizing a site for speed is delivering only the necessary assets at the right time in the optimal ways for the browser to render the page and make it interactive to the user. That's it. That's all of the core web vitals. It all boils down to that very little of optimizing HubSpot sites for speed is really HubSpot specific at all. It's the areas that are HubSpot specific are where HubSpot optimizes images and things for you automatically, as well as where HubSpot has special functionality that you might want to tap into. So you want to deliver only the necessary assets. Anything you load that isn't used in the page is a waste of loading time. With HTTP 2, building a monolithic CSS or JavaScript file isn't as performant as code splitting. That doesn't mean you shouldn't have a CSS file that most of your pages will load. There will be certain things like layout, typography, et cetera that's going to be consistent across pages. What I'm referring to is building and shipping gigantic CSS files and JavaScript files. And this monolith practice came from the pre HTTP 2 era where every request had to wait until the previous Request finished. With HTTP 2, the browser can request assets while still waiting for prior requested assets to download. So in the HTTP 2 era you want to write your CSS and JavaScript modularly. This can mean using the CSS and JS files that are part of modules, but it can also mean shared CSS or JavaScript files. For a group of modules that you load through require JS and require CSS. Say, for example, you have multiple modules that use the same JavaScript library and CSS library. For anim, you can load them like this. These files will only be loaded once, regardless of how many modules call them on the page. And a couple quick tips for require statements because you write them in Hubble, you can conditionally load CSS or JavaScript based on settings in your module or theme. You can add a field that enables or disables those animations. Why load all of this code if it's never going to be used? Something else you can do is optimize the loading of these assets by setting them to load asynchronously or deferred. This applies to both require statements and module JavaScript and CSS files. Below you can see CSS render options and JS render options in the meta JSON of a module. This is where you would set asynchronous or defer and then also in the require CSS and require JS statements. The second parameter is where you would set asynchronous or defer. Let's talk images Images can be one of the biggest areas of performance improvement for your site. Images next to video are typically the largest files you'll find on web pages. One of the most effective ways to improve images is to only load images that will actually get seen by the user. This is called lazy loading. For most modules, generally those not in your site header, it makes sense to use browser based lazy loading. This prevents images from being loaded until the browser determines they're actually needed. Let's look at lazy loading in practice. This is the rendered HTML for the boilerplate's card module. Notice the loading equals lazy attribute. That's all you need to implement lazy loading. Aside from lazy loading, you should also have the width and height attributes, and there's a few good performance reasons for them. And to be clear, I'm meaning the actual attributes, not css. The attributes allow the browser to accommodate for the size of the image before the image has even started loading. This helps to prevent cumulative layout shift. And another really good reason to include these attributes is that it helps HubSpot optimize these images for you. When that width and height are present, our servers will generate a Resize image URL based on those dimensions. The Resize Image URL is a CDN URL that will resize an image to the size that it will actually appear on the page. And if you've ever added an image field to a module and then used the Copy snippet feature within the Design Manager, that snippet looks a bit like this. While it may look complicated at first, what it's doing is generating the loading attribute and size information for you, as well as ensuring that the image is responsive. This code literally generates what you see above. Something else that's important to know. You don't need to convert JPEG and PNG to webp. We do that for you. We also automatically fall back to the original format for browsers that don't yet support webpage. While support is pretty good for WebP right now, the benefit of being able to take advantage of the Resize image URL capability and automatic sizing based on width and height attributes is well worth it. Aside from images, you also want to make sure that your pages can be pre rendered. If you've heard of static site generators like Gatsby and WP Super Cache, it's a bit like that. HubSpot generates static versions of your pages, posts and Knowledge Base articles, enabling them to be served faster from our cdn. There are some Hubble features that prevent prerendering, and you can find a list in our documentation, but let me show you how you can test if your page can be pre rendered Open up a page you want to test. Then in the URL use the hsdebug true or hsdebug only equals true query parameters in the debug information. It will outright tell you if your page can be pre rendered. If not, it tells you what is preventing it from being pre rendered. And then once you've resolved those issues, you can check again and it should say that the page can be pre rendered. A way to tell conclusively if the page has actually been pre rendered is to check the Network tab in your browser and look for the X HS prerendered header which should state a date and time. One more quick thing while we're talking debug information under where it states if something has been pre rendered or is able to be pre rendered is a breakdown of time it takes for HubSpot to render each part of a page. You can use this to identify which modules or template partials take the longest for the server to render. Reducing the time that it takes to render helps improve loading speed, specifically in situations where HubSpot can't pre render a page. The biggest common mistake that I see developers run into when they're optimizing a site for speed is not focusing on the largest areas of improvement. Let me show you what I mean. I've taken the liberty of running a Google Page speed report on the last website that you worked on. I'm kidding. Obviously I intentionally found a site that had a lot to improve. The page speed report will give you a list of recommended improvements, but unless you're used to looking at this report, it may not be immediately obvious to you where you should focus your efforts. First, the thing you care about most is the overall score. The overall score is the combined point value for each of the core web vitals. The amount of points that each core web vital is worth is weighted. I'm a visual person, so for me it helps to visually see where I can have the greatest opportunity to improve the overall score. When you look a little closer at the top of the report there is a link to a calculator and when you click it you're taken to the Lighthouse scoring calculator. The values here are the actual metric values from your report. The metric score is a 0 to 100 point score for just the individual metric, and that score itself isn't that useful to look at because what matters most is actually the weighting. You want to focus your time on the areas that can give you the highest point increase, because most of the changes you'll want to you'll make affect multiple metrics anyways. You'll likely gain points in some of the other metrics even without focusing on them. It's not like you're neglecting them, you're just not focusing on them. The circle graphic for me personally makes it easier to see and on this site the biggest areas of point improvement are clearly total Blocking time and largest contentful paint. If you were to slide the slider for Total Blocking Time and largest contentful Paint until you hit 100, you'll see that just by improving those two scores alone you could go from a 21 to a 70. That's a 49 point increase. In the real world, the changes you made for this likely also impacted your other scores. And after that you can see that the next two biggest areas of improvement for the site are cumulative layout shift and time to interactive. So as you're looking at the recommendations on your report, look for the changes that say they will impact the metrics that you are actually focusing on. There is so much depth to this topic. I did not call out every little detail. If you have your own tips, drop them in the chat. After the talk, I'll try to answer some questions in the chat. And if you haven't seen our Optimizing CMS Sites for Performance article, I absolutely recommend it. I wrote down many of these best practices and a whole lot more in that guide and we continue to iterate on it. We'll make sure to drop a link in the chat, moving quickly from one big topic to another deep topic. Your website is a bit like a physical store. You want to enable as many customers as possible to come into that store and conduct business with you. If you make it difficult for them to come in, or you don't make it easy for them to buy something or talk to an employee, well, they're going to get frustrated with you and more likely than not, they're going to leave. You wouldn't close a door on a customer as they come into a store, so why wouldn't you make it easy for them to operate your website? Taking a step back, what's the big goal of solving for web accessibility? Enabling those with disabilities, impairments and limitations, both temporary and permanent, by ensuring there are no barriers to access information or take important actions on your site. How do we do that? Well, there's a lot of different things you can do, but one of the things that I like best about having a module system is that you're building reusable components. When you build your modules with accessibility in mind, you've made every instance of that module on your site accessible. Build your templates with accessibility in mind, and you've made all of your pages accessible. If you want to build accessible modules and templates, you're going to need to use semantic HTML. That means using HTML elements like nav, main aside, article header, footer section, button, form, summary, details. I'm not going to list them all. There's honestly a ton of them, and this list is absolutely not comprehensive. It's actually faster to say you tend to want to avoid using div or span elements if a semantic element already exists for the purpose, and semantic elements have a lot of utility for accessibility. Semantic HTML helps users relying on assistive tech navigate, understand, and interact with your page. For example, when someone is using a screen reader, they're given context on where they are in the page. Additionally, these semantic elements are a way for screen reader users to navigate through the page quickly. They're able to jump to the next or previous heading, the navigation, or jump to the next or previous interactive element like a link, a button, or a form input. And if you use a div or span in place of any of those elements and don't provide the equivalent role attribute and ARIA properties, they can't do that. You also want to ensure that all of your links, buttons, and form inputs have descriptive text. Any links or buttons that just contain an icon. For example, you should be providing screen reader text. Otherwise, when a user of a screen reader gets to that link or button, they don't have a way of knowing where it goes or what it does. On that note, it's also important to use links and button elements appropriately. A link should be used for navigation either within the page or to another page. Buttons trigger something to happen, be it starting a video or showing an element that was previously hidden, closing a modal, etc. And now form inputs. You should always have a label element for form inputs. I know a lot of people love the appearance visually of using placeholder text as a field label. A screen reader user won't hear the placeholder text, and a user with cognitive or memory difficulties may find it frustrating that the placeholder text disappears when you start typing. So include a label. I would say most web developers probably know alt text is important, but if an image conveys meaning, you need to make sure it has alt text. And don't just state what all is in the picture. How you write your alt text matters. Think about the meaning of the image, not just what's in it. If the text around the image is talking about the height of a fire truck versus the height of the ladder extended. The important part of the photo of the fire truck is likely that it's demonstrating its ladder, not, say, the picturesque mountain pass that it's on. So here's a better alt text example and if the image is presentational, set empty alt text. This ensures that the screen reader user is also not annoyed or confused by images that are purely aesthetic, since they won't be read aloud to them. The last thing you'll want to do is test your site as you develop Just built a module Test it if you want to wait until the site is almost done to start testing, you may find you have hundreds of little issues you now have to solve versus just a few while your brain is still focused. There are a ton of great accessibility testing tools such as Axe by diffq. There's also an accessibility panel or tab built into most modern web browsers. I also highly, highly recommend testing your site with a screen reader like Voiceover for Mac. You also should never stop learning and empathizing. There are so many things that you can do to positively impact someone's experience using the sites you build. The learning doesn't need to always be technical in nature. Simply watching videos that involve someone talking about their lived experience with a temporary or permanent disability or condition can help you think about problems in different ways. I'd really love to keep talking about accessibility, but but we have a lot more to cover in a short amount of time. We have an intro level guide to accessibility in the CMS docs which gives you a ton of best practices and it's a great jumping off point to more in depth learning. Building for scale means you aren't just building for the site visitor, you're building for the people creating all of the pages too, multiplying your impact we use the term content creator a lot in our documentation. The content creator may be you, it may be the marketers, it may be other stakeholders on your project. It simply means the person who will be creating content with the assets you build. Our goal here is to optimize for who will be using your themes, templates, and modules and empower them to to work more efficiently. Remember, you're not just building a single static web page. You're building a system of interconnected building blocks that are all designed to work together. Those building blocks are designed so that instead of building one page, content creators can build thousands of pages to solve business needs. It's your job to empower them. Use drag and drop areas in templates so that content creators can use fewer templates and create tons of different page layouts. Provide section templates to give users reusable chunks of design or layout. And while full width modules may make sense for say like a cool looking carousel, don't neglect the benefits of also having modules that are designed to be used as parts of sections. Take our image and rich text modules for example. With just a section, rows, columns, and those two modules, you can make a whole multitude of different layouts and looks. This can empower content creators to solve for even more situations than you could have even predicted. You need to also remember your audience if you're building for the asset marketplace, the content creators you're building for have different needs and expectations. They want tons of styling control to make the site their own. If you're building for one specific company, you may have brand standards or a specific design already mocked up for for their website. That means you probably don't need as many theme settings and styling controls. You may even determine to prevent to protect the brand's styling. You may choose to limit what styling options the content creator has. And that though should probably be a conscious agreement with the stakeholders around which functionality will be available now. The other side of this is is it's not enough to know who they are. You need to try and live a day in their shoes. You can't build to empower them if you don't know what it's like to do their work. So I encourage everyone to grab a free theme from the Asset Marketplace, play around and build a simple site with it. Create some CTAs, create forms create smart content as you work with the theme, take note of the good experiences and the things that you think you could do better in your own theme. Use that to inform how you create themes. Modules and theme fields support two different types of help text. There's inline help text and then there is the just standard help text. Help text appears as a tooltip in the label and inline help text appears below the field label. While both exist so that you can give context to the content creator, they shouldn't be used interchangeably. Inline help text is best for information that is required to be able to use the field correctly. Help text is better for supplementary information when building modules. Separate Separate your fields that are content focused from those that are purely presentational or stylistic. By using style fields, say you're providing a way to display an image in your module. If that image provides meaning or context, then it should be controlled with a content field because the user needs to be able to provide alt text. If the image is just visual fluff and doesn't add context like maybe it's an abstract background, well then use a style field. Lastly, accommodate for the content creator not knowing performance or accessibility. Best practices use resize image URL to prevent the content creator from putting oversized images on the page. Make a field required if it's used for screen reader text. We we have a guide in our docs on module and theme field Best practices which goes even further in depth and we'll make sure to share the link you've probably been like Holy smokes. Website Speed Accessibility Building for the Content Creator this is a lot to keep in mind, but you can offload a good portion of this work to your boilerplate. Boilerplates are kind of best practice themselves, but they have their own best practices too. The goal of a boilerplate is to start new web projects with many hours worth of development, planning and optimization work already done. A boilerplate should enable you or your teams to focus on the customer's unique needs versus implementing something you've done a million times before. If you work at a solutions partner or agency and you're building lots of websites, you should at a minimum be starting from the HubSpot boilerplate. As you build more and more sites, you'll likely find that you have opinionated ways of doing things and you'll fork the HubSpot boilerplate or create a similar internal boilerplate. You should also use every new site that you build as an opportunity to improve on your boilerplate. It's not a set it and forget it type thing. The time that you put into it gets saved on all of your future projects. Incorporate into your boilerplate skeleton versions of modules and sections that you tend to create for most of your customers. And this idea isn't new either. I actually gave a talk on this back in 2018. I'm actually going to show a couple of my old slides. The idea is you want to incorporate skeleton versions of modules and sections. That way all you need to do is tweak some styles to implement similar designs for multiple clients. And what I mean is to separate the required structure of a module from the company specific visual flair that you add to it. That way you can reuse that module for every site you create. Good work me from 2018. And lastly, we update the HubSpot boilerplate all the time adding performance, accessibility and all kinds of quality quality updates. I highly encourage you to use the Watch feature on the repository and if you make your company's boilerplate. By forking the HubSpot boilerplate, it makes it super easy to merge in our updates. And if you choose not to fork it, but build a boilerplate from scratch, I encourage you still to watch the boilerplate GitHub repository. It often gets updated with new CMS Hub features and it's just a great way to see all those in context. Boilerplates can also be a great part of your team's strategy. And on that note, one last set of best practices. This time it's about soft skills. The big idea is you want to make you or your team invaluable by getting involved early and prioritizing business needs before jumping right into the deliverables. So you'll want to get involved in the meetings with the stakeholders of the site that you're building, be in the meetings with the marketers and the designers. You know the platform and what it's capable of. Learn what their business objectives are and think about how your work ties into them. In the age of business websites that are just digital brochures with a contact form is over. This is the age of the connected customer. The age of websites that actually help the business operate is now. That goes beyond lead generation business customers expect that they can connect with the business in a meaningful way easily and on their own time, not having to make a phone call or wait for a reply to an email. The norm is self serve access to information. It's signing in, it's managing your own account with the business. It's personalized, you're shown your support tickets, the products you might be interested in, the resources for the products you already have, and news about new products and features. As a customer, you expect to have a way to contact the business through another means other than say the general non signed in contact form which you don't even know if you're going to even be seen. And without needing to make a phone call, you expect you can chat or fill out a form that's again, not that general contact form. And customers also expect to be able to see the status of their orders or projects. All of this is possible to do on HubSpot today. If you build the systems that actually enable the business to operate, you're now a critical part of that business. You've cemented yourself as hard to replace. You've tied yourself further to the income of the business that it's generating, the cost reduction, the products they create or the service they provide. I want to also end this strategy discussion by telling you I just hit you with a lot of best practices. It'd be fair to feel intimidated hearing all that in the rapid fire way that I I told you them all and I wanted to bring up Dave Rupert, a friend of Chris Coyer, recently posted an article called the Web Is a Harsh Manager. In it, Dave talks about how there is so much for web developers to know and there are so many hats that developers wear. The person responsible for knowing how to code a site to make it look like a design is the same person who's in charge of querying and displaying data on the page. And the same person who optimizes a site for speed is also the same person who is making it accessible. Sometimes every year there is just more and more to know and improve. You all wear a ton of hats. Websites, they're complicated. There's so many angles to think about them from. If you've ever felt overwhelmed as a website deadline approached, scope creeped, or you've underestimated solving for speed or accessibility or some piece of functionality, no, you don't need to feel that way. There's a better way to build websites that alleviates the burden of trying to do everything all at once. If you're not familiar, I'm talking about the Growth Driven design philosophy. We have a free certification course on HubSpot Academy and I encourage everyone to take it. But I will try to oversimplify and sum it up. A website is never done. You don't just build a site and then neglect it. You keep improving it over time. You want to focus on the most important customer or business flow first and optimize for that. Anything that doesn't seem like it addresses the first, second or third most important customer business flows. You're going to work with your team to say not yet. We're going to make sure we nail those priorities before we move on to the 4th, 4th, 5th, 6th, etc. You're going to deploy a launchpad website Launchpad, meaning it's not a website with every bell and whistle and every bell of optimization of every kind. It's going to be one focused on the first three most important business and customer flows. You or a marketer will collect data on the flows you built and use that to show the stakeholders the impact of your work. This helps build trust and enables you to work iteratively. Now you work on the next priority. Build and optimize for that while avoiding hurting the top three priorities. Track the data, report it. Repeat. You've simplified your project scope. You've told stakeholders yes, you can have your bells and whistles, but let's prioritize then you got a site up and iterated on the most important flows. We talked about so many different topics, each deserving of its own deeper dive. I know. I also mentioned a ton of resources if you missed them, don't worry, I have compiled them all for you and I'll give everyone a minute to copy down this shortened link. But not short enough link in my opinion. Anyhow, thank you all for coming. If you have questions, feel free to DM me on Dev Slack or LinkedIn. I'll also lurk in the chat for a bit to answer what I can have a great rest of your time at Extend SA.