Options available when inserting JavaScript into a Kentico site

By Ilesh Mistry
January 23rd 2015

8 minute read

What options are available and where do you place your JavaScript files into your Kentico website?

 

The basic options that are available for you, on a Portal Engine Kentico website, are to use :-

  • the Kentico JavaScript Module

  • external JavaScript file(s)

  • inline JavaScript
     

So from these basic options, using inline JavaScript is something that is not heavily recommended as it is hard to manage and maintain the code within Kentico.

Here are MMT Digital, we don't really utilise the Kentico JavaScript Module for our main site JavaScript.

This is purely because we code our JavaScript in a modular fashion and working with such files away from Kentico is quicker and cleaner for us. We also can run tasks like Grunt minification locally with the file system JavaScript files.

Our recommended approach is to use external JavaScript files.
 

Where do we place the JavaScript files?

 

Assuming we are using the external JavaScript file route, then you have a few options.
 

  • You can put the reference to the JavaScript file(s) in the Head tag/area of your Master Page.

  • Another approach is to put the JavaScript reference in the Header section of your page templates.
     

Option 1, is the older way of applying JavaScript files to your site, which is in the Head tag. So I wouldn't recommend this.

Option 2, is still using the Head tag to put the JavaScript, but it is template dependent. It has some benefits where only the pages that have the Page Templates with the JavaScript applied to them will use it. However this is not that great either, as it also is placed in the Head tag.
 

Well, what do you suggest then?

 

My suggestion is to place the JavaScript files at the bottom of the page, as this is something that is recommended in terms of loading a page quicker. By this I mean a page is loaded from the top to the bottom, so if you want your pages to load quicker you need to put any 'blockers' near the bottom of the page to provide a better user experience for your end users.

As JavaScript is a blocker for page loading, it is recommended to place this at the bottom of the HTML structure within the Body tag. Also recommended is making sure you combine your JavaScript files into one. We tend to minify our combined JavaScript file for maximum optimisation and performance.

The basic thing to do for the main JavaScript file(s) is to insert them at the bottom of the page within the Master Page.
 

What methods are available to insert the JavaScript at the bottom

 

There are two main options -

  • Manually insert the JavaScript file into the Master Page at the bottom. By this I mean, you will have a single JavaScript file, as mentioned above, which would be stored in the File System. On the Master Page you can provide a link to that file using the usual script tag.

  • Another option is to use the Kentico JavaScript web part. This web part is very powerful and useful for what people may require. So you can add this web part to any zone in your Master Page and then select the option for StartUp Script.
     

Both these options place the JavaScript files at the bottom of the page, which is the recommend approach.

This is all good, but we all know as we all try to build more complex sites, that this approach is not sufficient and we need more flexibility.
 

Different JavaScript scenarios

 

We need to consider what scenarios we could come across that would change the way we approach our inclusion of JavaScript files.
 

Scenario 1

 

I have a lot of JavaScript code in the minified file, but only certain Pages use specific functions.
What approach should I use?
 

Scenario 2

 

I have a lot of JavaScript code in the minified file, but only certain Page Templates use specific functions.
What's my best option to handle this?
 

Scenario 3

 

I have a lot of JavaScript code in the minified file, but only a certain Page Type uses the majority of the functions.

What can I do about this?
 

For all of these scenarios, the question usually is...

 

Why should I need to load all this code in the Master Page and therefore every page for something that is only used for my scenario?

That is a good question and if we are building sites, which need to be as optimised and quick as possible then every byte matters.
 

What are the options out there?

 

Well let's make sure we stick with our principle of having the JavaScript file at the bottom of the page. Then we just need to remember, that code within our file needs to be in sequential order. As JavaScript works in a way where the order of the code matters.

With this in mind, imagine our main JavaScript file, which sits at the bottom of the page, we would need to exclude the code that we wish to fit our different scenarios. An example of such items included in the main file would be initialisation functions.

Lets look at the scenarios in more detail
 

Scenario 1

 

For this the situation is that the JavaScript code is page specific, so you could have specific templates, but a particular page needs some specific unique JavaScript code. This sort of scenario is not that common, so you would need to consider how often this is going to happen and whether creating a new template for this might resolve it, which would fall into scenario 2. If creating a new template is not feasible, you would need to consider how to apply this on the different templates.

One option is that you add in the JavaScript widget so it can be used on any page template, that has a widget zone. This is ok, but it means the widget could be added in by anyone who has the rights to do so.

I don't like this approach so I would recommend using the approach, which I will suggest for Scenario 2.
 

Scenario 2

 

For this situation, it is for Page Template specific JavaScript code. Now if we follow the same principle of placing the JavaScript at the bottom in the Master Page, then we need to consider how we can incorporate our Page Template JavaScript code/file to come after the one placed in the Master Page.

One option for this is to use Multiple Page Placeholders. This approach is fairly simple to use and the one I would recommend to help resolve this scenario. The way it would work is that you place you Page Placeholder web part, how you would normally, within your main zone.

Then in your Master Page Layout markup you would add the JavaScript link to your main file near the bottom.

Your next step is to add another web part zone into your Master Page, which will sit underneath the link to you main JavaScript file. Then into this zone add another Page Placeholder. This will mean the second Page Placeholder can be used on your Page Templates, so you can insert the Page Template specific code, which would mean the code would be in the sequence order.

The assumption is that you set the Multiple Page Placeholders properly using the information provided by Kentico and apply this throughout your site and all the templates. If you are using this approach, it is recommend to set it all properly at the start of the site development, as incorporating this later on is still possible, but tricky when you have more and more templates created.

This seems like a decent solution for the two scenarios.
 

Scenario 3

 

For scenario 3, where the JavaScript should only be applied to certain Page Types, then you can use the Conditional Layouts. I really like this approach as it seems really clean and a great way to use Kentico functionality.

For additional information about this please read the documentation as Conditional Layouts seems like a very powerful way of composing your Page Templates.

The other benefit for this approach is that all your JavaScript files are managed on the Master Page and only when the appropriate Page Type is used you will get that JavaScript file/code.

This seems a like a really good approach to me, because for the other Page Types no additional code will be loaded!

Excellent as Mr Burns would say!
 

So there you have it, this was my explanation of the different dilemmas developers need to overcome when building Kentico sites when it comes to using JavaScript. The scenarios I provided in this blog post are just a few, if you have or come across some more please let me know!

 

Useful links
Kentico Documentation - Conditional Layouts in Page Templates
Multiple Page Placeholders in Kentico - DevNet Article by Martin Hejtmanek CTO at Kentico Software