Front-End Best Practices for Developing in Kentico

By Alli Treman on December 13, 2016

Front-End Best Practices for Developing in Kentico
Front-end developers love Kentico. It allows us to create elegant, fully-functional websites while leaving the back-end developers to work on boring things like complicated integrations and custom ecommerce solutions. After working with Kentico for years, you could call any BizStreamer a Kentico expert, and our front-end team is no exception. In fact, we’ve developed a set of best practices for front-end development with Kentico: integrating CSS, using JavaScript, and harnessing Kentico to quickly build high quality websites and user interfaces for our clients.

Finding a Home for our Files

Once upon a time, BizStream’s front-end developers used Kentico’s Virtual Files for storing our CSS and coded CSS in the old-fashioned vanilla way, with no pre-processor. Using Virtual Files gave clients and, even worse, back-end developers, the ability to find and edit our CSS. Back when we were using vanilla CSS, this wasn’t as big of an issue. With pre-processors, our edits might override changes made within Kentico. Having to re-integrate back-end written CSS into our .less or .scss files was never an enjoyable task.

To facilitate moving our CSS out of Virtual Files, we created a folder called _framework which lives inside the CMS folder in the Kentico solution. Yes, the back-end developers can access this folder, but they rarely have Web Essentials and Sass compilation set up in their environments and are therefore more likely to keep their paws off of our stuff. This folder contains all our .scss files, the compiled .css and .min.css files, plus all our JavaScript. Let’s take a deeper look at our folder setup, examine what files go where, and explore the best practices and patterns we follow for writing our front-end code.

When moving our .scss and CSS files to the _framework folder, we moved our JavaScript files at the same time. In fact, the _framework folder is the main location for any files needed for the site’s UI development. This of course includes CSS and JavaScript, but the folder also contains the fonts, sprites, and SVGs used in the project.

Inside the _framework folder live four folders:
  1. css - For our .scss and CSS files.
  2. fonts - For our fonts.
  3. images - For sprites, SVGs, and other iconography. This is not for images added by content admins; those live in the Media Library. 
  4. js - For our JavaScript files. 

Serving Up some JavaScript

Digging down into the js folder, you’ll see even more folders and two files:

image02.png

common.js is our main JavaScript file that runs on all pages and page templates within the site. If page template specific JavaScript files are necessary, they’re added to the app folder. The lib folder contains libraries like jQuery (seen above) and frameworks like AngularJS. jQuery is added by default since we use it in almost every project. The plugins folder houses JavaScript and jQuery plugins such as Owl Carousel

Since most of our projects don’t have a ton of JavaScript, we don’t usually use something like Browserify or RequireJS, but we have used them on more JavaScript heavy projects and keep them around as tools when necessary.

We generally use the Revealing Module Pattern as described here for our JavaScript. Since we usually have multiple JavaScript developers working on a project, this helps us keep our JS consistent and readable. It also has benefits like protecting the $ for use with jQuery, simplifying how we refer to public functions, and giving us control of our public and private functions. 

One problem we’ve dealt with in our JavaScript is CSS classes getting used as jQuery selectors. 95% percent of the time this works fine, but sometimes a class name might get changed to solve a styling problem, and the developer making that change might not know that jQuery is using that selector. Oops, now it no longer works! If the developer is completely unaware, the problem might not even be discovered right away. Suddenly the QA Engineer reports a bug and everyone’s stumped. To solve this we’ve decided not to use CSS classes and instead to create separate, identified classes to use for jQuery selectors, prepended with js-. For example, you might have a carousel with the class .carousel for styling. Instead of using .carousel to initialize the jQuery, you would add another class .js-carousel and use that instead. That way, if the CSS class needed to be changed to .slider, you’d still have a working carousel.

In Kentico, our JavaScript file lives before the closing </body> tag. This speeds up page load by ensuring other page elements are loaded before the JavaScript. On Portal sites, JavaScript files loaded through a JavaScript web part on the Master page template and the Linked file page location is set to Startup script. The web part lives directly above the Page placeholder. This allows page-specific JavaScript files to load after the site-wide file. Like everything in web development, there are exceptions. For example, Google Analytics code must be placed before the closing </head> tag.

Writing Better CSS with Sass

We love Sass. The pre-processor helps us write CSS much faster, and makes writing CSS a lot more enjoyable; you’re using programmatic concepts like functions (called ‘mixins’) and variables instead of just writing list after list of styles, long lists of selectors, and repeating yourself over and over. We haven’t always had it this good. We used to use vanilla CSS and store it in CMSVirtualFiles, where it then could be edited in Kentico. Once we discovered the magic of pre-processors, we chose LESS because of the Visual Studio Web Essentials support. We later switched to Sass because Sass is more robust, allows you to do more with your code, and is the industry standard pre-processor.

image03.png

Sass boasts an involved developer community and it delivered. Through blog posts by developers who love the tool we’ve discovered mixins and other strategies that make our Sass coding better and more enjoyable. Some developers are out there using it to do some pretty incredible things.

Class Names that Make Sense

When we switched to Sass, we also decided to adopt a class naming system. A semantic class name is one that describes but doesn’t specify the content enclosed. In other words, we want class names that make sense even if the design of the element is changed. For instance, a home page might have a row of three orange boxes. You might think that .orange-box might be a good name, but what if the client wants to change the boxes to blue? Then you’d either have a class .orange-box with a blue background color, which doesn’t make sense, or you’d have to change your HTML to reflect the new .blue-box class name. Better to name it after the purpose of the object: .callout perhaps.

image01.png
(Image Source: http://www.slideshare.net/oemebamo/introduction-to-memcached)

There are a lot of CSS naming systems out there. SMCSS is one and BEM is another. We use a simplified version of BEM we call “BEMish.” It’s a little more flexible: instead of underscores and double dashes we just use single dashes. Modifiers are additional classes instead of being appended to the original class. (EX: Instead of .callout__link--hidden we’d have .callout-link.hidden) Elements can have three levels, so you might have .callout-link-icon, which would not be allowed in strict BEM. We understand that a naming system can be good in theory, but doesn’t take long for a case that just doesn’t fit in with the system. Naming things can be one of the hardest parts of writing code! Sometimes you find a situation where a naming convention doesn’t fit, and you have to get creative.

Getting Modular

Working with Sass gave us a push to modularize our CSS. To do this, we had to change our thinking from creating one long, winding CSS file that styled the site as a whole to creating multiple, modular .scss files that styled reusable site components. Following BEMish naming conventions lends itself to this way of thinking. As described in the BEM documentation, the B stands for Block, “a standalone entity that is meaningful on its own.” In other words, a block is a module.

In our code, each module has its own .scss file, where the name of the block class is also the filename. Each project also has the following four.scss files by default:

_mixins.scss - List of Sass mixins.
_normalize.scss - Styles from the latest version of Normalize.
_variables.scss - List of Sass variables and their values.
_global.scss - Global styles, usually site defaults, such as body and paragraph styles.
style.scss - The file that imports in the modules and gets compiled into CSS.

The Sass files live in the following folders:

base - Files that setup the basic building blocks for the site. This folder contains the files listed above (except style.scss).
plugins - Any framework or library .scss styles go in here. _bootstrap-grid.scss is included by default. It’s a simplified version of Bootstrap that includes only the grid. We use breakpoint variables to customize the solution for projects with differing responsive designs and requirements. We’re really excited about Bootstrap 4’s native Sass!
modules - Most of the .scss files live in this folder. These are the components that build up the style of the site or app. This folder is divided further into more folders to help us organize our code: header, footer, layout, ui-element, and content.

The module folders contain a few default .scss files for common elements such as navigation, form elements, and buttons. See the entire structure in the image below.

Brainless Compilation

All these .scss files need to be compiled into one .css file for the project. There are a few different ways to do this in Visual Studio. The first ever Sass project we did with Compass. It worked, but was frustrating to remember to run Ruby and Gulp whenever beginning to work on the project. Since we’re not a Ruby shop, anyone new on the project had to install Ruby to write any CSS. After upgrading to VS 2015, we tried out running Gulp within Visual Studio. This still required additional setup for new contributors and the autocompile on save feature didn’t work 100% of the time. 

Our current solution is the Web Compiler extension. The extension is easy to install and setup and works flawlessly. It’s easy for new people to jump in a project and work can be done without worrying if/when the Sass is getting compiled into CSS. We keep the Gulp + Visual Studio solution in our toolbox for when we want Gulp to do things other than just compile Sass, but Web Compiler works for most projects.

Keeping it Fast and Easy in Kentico

Our goal as front-enders working in Kentico is to make content creation as easy as possible for marketers and content creators. First and foremost, we enjoy building MVC projects. This gives us more power to build more complex nested repeated content. We work with the back-end developers to build some really powerful solutions.



When we work with the Portal engine, we eschew most of the built-in Kentico web parts for a few select few: Repeaters and Hierarchical Viewers to build repeated content and menus, Editable text and image areas for content creators to add content to generic pages, and static text/html for adding macros that dynamically pull in additional content. Transformations are written in Text/XML so we can use Kentico’s macro syntax.

We follow best practices for optimizing page load and making things easier for content creators. For instance, we keep all of the project’s page templates in a new, separate folder and start their names with an asterisk (*) so they’re easy to find. Page types that use a specific page template are set to automatically select that page template when a new page is created. They also direct to the Form tab when clicked so the content creators know what to update.

Kentico is a solution that makes it easy to create and edit content, but it’s on us to develop our Kentico projects in a way that use Kentico to the fullest to make this happen. Kentico is a powerful and flexible solution, and as Spiderman's Uncle Ben says, “with great power comes great responsibility.” Incorrect use of Kentico can create a mess that’s impossible to work with. It’s on us Kentico developers to wield that power to build fast and beautiful web sites and applications that are easy for our clients to use and update. Having and following these standards allows BizStream’s front-end development team to do just that.

In Summary

Here is a simplified list of our best practices regarding JavaScript, CSS, and Kentico:

JavaScript

  • JavaScript lives in CMS/_framework/js
  • We still <3 jQuery
  • We use the Revealing Module Pattern
  • jQuery selectors use specific classes in the DOM prepended with js-
  • JS files go right before </body>

CSS

  • Preprocess with Sass
  • CSS and .scss files live in CMS/_framework/css
  • BEMish standards are used for writing modular CSS
  • Visual Studio compiles SASS into CSS with the Web Compiler extension

Kentico

  • We focus on making things easy for content creators and marketers while keeping pages optimized to load quickly
  • MVC > Portal engine
  • Repeaters and Hierarchical Viewers are preferred to more specialized, built-in Kentico web parts
  • Text/XML Transformations are the way to go
While those standards are set for now, the beauty of working on the web is  that things are constantly changing. This list could easily be out-of-date by the time you’re reading this post!

Share This Post:

Twitter Pinterest Facebook Google+
Click here to read more Events posts
Start a Project with Us

About the author

Alli taught herself HTML when she was 12. Just for fun. After that, she was obsessed with figuring out everything a computer can do. Here at BizStream, Alli does front-end development. When she’s not making websites, Alli is going on adrenaline adventures and tackling her ambitious reading list. She has sweet baby boy named Simon and an extra fluffy cat named Sashimi.

View other posts by Alli

Subscribe to Email

Enter your email address to subscribe to the BizStream Newsletter and receive updates by email.