RequireJS Webpart and Module for Kentico 8+

0
Comments
0
Votes
Login to vote

A webpart and module to use RequireJS within Kentico. The webpart uses Kentico's version of RequireJS and jQuery. With the right configuration, you can also setup the webpart to minify your code with Node automatically. There is also a module with global settings. This is a very helpful tool when building large front end apps that need to be minified.

DATA_RequireJS_v1-0.zip
SetupFiles.zip

The RequireJS webpart aids in developing with RequireJS within Kentico.

Features:

  1. Allows you to follow a file and folder convention to minimize configuration.
  2. Enables automatic javascript minification based on global or webpart settings.
  3. Includes Kentico's jQuery and RequireJS files, so that you don't have to worry about conflicts
  4. Multiple webparts can be used throughout the site.

Step-by-step guide

  1. Go to Sites > Import Site or Objects
  2. Import RequireJS_{version}.zip
    1. In Import Settings, make sure that "Import code files" is selected.
    2. Make sure that all items are selected. Kentico likes to deselect items in conflict or from a different hotfix.
  3. Go to your preferred page template and add the RequireJS webpart.
  4. Configure the webpart and point to your main module.
  5. Go to Settings > DATA > RequireJS if you want to change your settings globally.
  6. If you would like to use minification, you will need to add a few more files. Download "SetupFiles.zip" to get a boiler plate setup.

Now you can rely on RequireJS to load your javascript and minimize the need to add javascript webparts. One caveat to that is shims and polyfills. If they are library independent, it makes sense to add those before the RequireJS webpart within an "if ie 8" script include.

Below is an image of the webpart properties.

Some of the above settings can also be managed globally, where you see "Use custom settings".

1. The first box is the path to your initial require module and configuration. I choose to name ours after the template they go with.

2. The second box is the path to a batch file. If you choose to use minification and set a build mode, this batch file is run. This is where you tell node to minify for you. The build process only runs if files are modified within the main js folder. This path is optional and will assume a path to the batch file relative to the main js name and location("build\{main path filename}-build.bat"). Download "SetupFiles.zip" to see an example implementation.

3. The third box represents where the minified javascript lives. When, use minification is on, This is the file that is used. If left blank, conventions will be used. Assumes /dist/{main path filename}-built.js. This path is relative to the main js path.

4. Use minification sets whether to use the main js file or the minified file. If the build mode is set and the minified source is older than any of the files in the main js folder, The batch file will run, minifying the code synchronously and returning the minified code.

5. Build Mode lets you take control of when and how to minify. Off - will never call the batch file. Force Check - will compare the dates of your javascript with the date of your minified code and will build if the minified code is too old. Force Build - Useful for debugging, It will build every time you hit the page (See "include logging"). You might want to only minify your code on your dev environment and push the minified code to production. It should also be noted that the minified code is referenced with a cache buster, so when you push a javascript change, its url changes a bit too and gets by the browser's cache.

6. Page location lets you set where you would like your code to show up on the page. Beware that if you are using a bunch of Requirejs webparts, location matters. It is recommended to set it as a startup script as that will place the code further down the page.

7. Include logging is how you can debug the build process. The logs get added above the script includes on the page. Here is what you might see if logging is on but not building. 
<!--
::::: RequireJS webpart - DATA, Inc :::::

Not using minification. Will not build.
-->
<script type="text/javascript" src="/CMSScripts/Custom/master.js"></script>

Kentico specific issues:

It should be understood that, in Kentico 8, Kentico uses RequireJS and configures it for themselves. This is not that big of a deal as long as we use our own context when we call requirejs.config(). Take a look at the example code below with notes.

 

//get an instance of the new context. Notice that we name a context in the config.
var requireMaster = requirejs.config({
	//set the context to get a unique configuration
    context: 'master',
	//setting waitSeconds to "0" is nice for debugging because require times out on loading modules after 7 seconds. 
	//Breakpoints will blow through the the default timeout and you will get more errors. 
	//You can remove this for production if you want.
    waitSeconds: 0,
    baseUrl:'/CMSScripts/Custom/',
    paths: {
		//We force Kentico to load jquery in the page to simplify jquery conflicts. 
		//It loads after require which is good enough, but we make sure that the 
		//jquery on the page is loaded as a module by defining it.
		//the code of this module is: define('jquery', [], function () { return jQuery; });
		jquery: 'DATA/definejquery',
    },
    shim: {},
});

//Here we temporarily shift around these variables so that when node minifies everything, 
//it will see "require" and include those files in the build. Yes, a bit hackish, but it works.
var temp = require;
require = requireMaster;
//main require
require(
[
	'require',
	'jquery'
], function (require, $) {
	    //we can include require here if we need to obtain the correct context, 
		//the global require context will be muddied by kentico, but everything loaded from this context will be fine.
    }
);
//put the old require back as it was.
require = temp; 
 
Posted by Adam Hass on 7/2/2014 4:50:48 PM
  
Comments
Blog post currently doesn't have any comments.