January 30, 2015 JavaScript-and-Kentico.png

Introduction

So JavaScript. It's one of those things that is really good at invoking strong opinions from just about everybody; people who like working with it seem to like it a bit too much and everyone else loves to hate it. Fortunately/unfortunately, it doesn't look like JavaScript is going anywhere soon. The language has become an essential part of building web applications and some would even call it a glue language across all disciplines of software development. So if you don't like JavaScript, I hope we can still agree on the importance of creating organized maintainable systems. The ‘hack it; hack it harder until it works kinda’ mentality that is sometimes paired with not liking the language won't get us very far.

JavaScript and Kentico

You might be thinking to yourself, "I've read this before," and I definitely won't fight you there. There are a ton of JavaScript management/organization/best-practices articles out there; this one is different in that it relates specifically to the Kentico CMS. So hopefully, if you're taking the time to read this article, you are at least familiar with Kentico. Maybe you even work with it on a daily basis.

This post is the first in a series of articles that I hope to write relating to Kentico and JavaScript. I think there is a lot to talk about here. For instance, Kentico has the ability to power full-fledged JavaScript applications with its built in REST API, but that's another article. I wanted to start with JavaScript management within the Kentico CMS (where we put our scripts). It's a pretty basic topic, and to most developers it might not seem super important in the grand scheme of everything, but I think we can save ourselves a bit of pain and tech debt by sitting back for a second and thinking about how, where, and when we load our scripts in Kentico.

Six Thousand Ways to Do All the Things

Kentico is awesome. It's a robust content management software package that makes building web sites and applications a breeze. That being said, if you have any experience with Kentico, you know that there about six thousand ways to do any given thing. Among all the options, we're supposed to somehow figure out the best, most efficient way to solve any given problem (so fun). As far as JavaScript management within Kentico, here are some of the patterns I’ve seen (and maybe even implemented, but I’m going to keep that to myself).

  • Small scripts in the text source of an Editable text web part (yikes)
  • Small scripts in a web part’s HTML envelope (not as much yikes, but still)
  • Small scripts in their own file in the content tree (?)

The list goes on - I promise. I'm not necessarily calling out these patterns as the wrong way (after all, bad software succeeds), but I think we can improve here. Since we're dealing with Kentico, the official documentation sounds like a fantastic place to start if we're looking for sweet wisdom on this issue. Let's see what the guys at Kentico have to say about managing our JavaScript:

82ed02f0-a7cd-11e4-904c-d00f165aeba9.png

Nifty. We can add custom (!) Javascript files in Kentico and use them anywhere (!!) in the application. Also, as a side note, Kentico doesn’t support Javascript files that lack the .js extension—good to know. I think it’s safe to say that the documentation doesn’t give us much guidance in terms of best practices. There are still so many ways we could manage our scripts! From this point, I'm going to try my best to explain a few patterns that have been helpful for me in achieving more consistent, maintainable script management.

The JavaScript Files Application

Even though the documentation on this topic is pretty sparse, Kentico's JavaScript files application isn't a bad place to start. Kentico tells us that this is where we should put our JavaScript. Not in the content tree. Not in a stylesheet theme folder. Although these other places may have their benefits (e.g. database storage in the content tree), the JavaScript files application is where we will want to park our JavaScript libraries and plugins. I recommend that you put your smaller, template-specific scripts inline right after the related markup, but for plugins and libraries (e.g. jQuery, Modernizr, FullCalendar), this approach isn't a great idea because HTML doesn't cache on the client side. We want to separate these larger files out in order to leverage browser caching.

Tip: You can cache your HTML on the server using Kentico's implementation of IIS output caching. Friendly advice: don't throw this switch when your site is in production.

Use JavaScript Web Parts

JavaScript web parts are sweet Kentico goodness. Coming from non-portal-engine web development, the idea of putting JavaScript in a component that you drag onto a page wasn't my favorite thing at first. With some time, I've come to realize their major benefits. If you're not using JavaScript web parts even for your smallest scripts, I would recommend that you use them. The JavaScript web part gives you full control over what pages your scripts will be on, what section of the document the script will be loaded, and provide a nice visual representation of where your scripts live. In addition, JavaScript web parts ensure that your scripts will work correctly in Kentico's preview mode; this is especially important when hooking up jQuery. Let's look at some of the options we get here:

Screen-Shot-2015-01-30-at-10-01-27-AM.png

You can see here that we have the option to link a script file from the JavaScript files application or add an inline script. Regardless of which option you are using, we have the ability to change the script's location on the page (e.g. header, beginning of page, startup script, inline) with a simple dropdown menu. We can avoid copying and pasting our scripts or script references in a frantic, hacky effort to get our blasted scripts to run when we want them to run.

Tip: When adding an inline scripts using the JavaScript web part, I always uncheck the 'Generate script tags' box and just add them in myself in the editor. Without the script tags in the editor, you don't get any syntax highlighting.

Another reason why I love using JavaScript web parts is how they allow you to relate templates and scripts. Say you have a few lines of JavaScript that are interacting with markup in your page template. If your JavaScript is living at the bottom of your master page layout, in an HTML envelope, or another obscure place, it can be frustrating when you have to go digging just to make a simple change to your script. JavaScript web parts are highlighted in red in Kentico's page design tab, which makes finding scripts related to your template simple and obvious.

JavaScriptAndKentico.png

A picture definitely explains it better. Take a look at the above screenshot of the same template side-by-side. They both have the same script associated with them, but it is much more obvious in the template on the right. In the template on the left, the JavaScript could very well be hooked up to the template, but we have no idea where. Even if you know exactly when you linked up your scripts, the next developer who comes behind you will probably have to do some digging.

Overwrite Kentico's jQuery

You may have noticed that I didn't mention one of the options in the screenshot of the JavaScript web part configuration: Include jQuery. In short, I don't have much trust for this little checkbox. I can't control it and it may or may not keep me awake at night. As of Kentico 8.2, Kentico has removed jQuery from the entire application, so if you're developing sites on that version, you'll have to manually include jQuery anyway.

Tip: It is especially important to use a JavaScript web part to link up jQuery as all other scripts that depend on it will not work correctly in Kentico's preview mode if jQuery is linked up elsewhere (e.g. master page layout). 

If you are developing on previous versions, you could potentially use the version of jQuery included in Kentico, but I've found that it's much safer (and more predictable) to go ahead and overwrite Kentico's jQuery after the <head> tag. To do this, upload jQuery to the JavaScript application, drop a JavaScript web part at the bottom of your master page's design tab view and set the configuration to pull in jQuery from the JavaScript files application. For the 'Linked file page location' field, select 'Beginning of the page' like so:

Screen-Shot-2015-01-30-at-12-23-19-PM.png

This will ensure that your version of jQuery overwrites Kentico's. The reason I recommend the beginning of the page rather than before the closing </body> tag, is that it enables you to put small template related scripts inline after the related HTML.

If you're religiously opposed to inline JavaScript, (many people seem to be), you can ignore this, link up jQuery at the bottom of your page, and place all your tiny, semantic, beautiful jQuery calls in a script.js file. I would still recommend hooking that file up using a JavaScript web part. Surprised?

Conclusion

You could totally ignore all these suggestions and continue to build successful websites in Kentico, but hopefully, they might help you to bring some amount of repeatable process to your JavaScript management. I would love to hear your thoughts on this topic. If something works nicely for your process, please share in the comments below, especially if said something contradics information here. Also, Brad, thank you for the giant Reese's Cups.

Peace and Love,
Nate (for some stuff about me, click here)

Contact Information

  • Aurora, OH, 49 East Garfield Rd. Ste 100
  • Phone: 888.867.8557
  • Twitter: @codesummit
  • E-Mail: connect@codesummit.com
Kentico

Do you have any questions? Feel free to ask or send a message here!