Requirejs demystified

[Martin-Pankraz]

Requirejs is an open source JavaScript module loader and mostly used to improve script file loading times and to simply add external libraries. For example, normally all of your declared script objects (contribution.xml) will be loaded upfront on app start. Requirejs enables SDK developers to load libraries on demand. This short introduction shall be sufficient for now as my goal is to show how to integrate libraries into DesignStudio extensions.

When you start coding right after reading the developer guide you would most likely try to load external libraries by placing them in your SDK folder structure and referencing them in your contribution.xml. So far so good, but when you open your favorite browser’s developer tools you might notice an error message coming from DesignStudio’s built-in requirejs plugin: MISMATCHED ANONYMOUS DEFINE() MODULES (This problem doesn’t apply to all of the libraries but it would be too extensive to explain all of the possibilities right now). Until recently this was no real problem, because the errow was only showing in devel mode, if you made sure that all of you external libraries are loaded in the correct order. But IE started to expose this requirejs error as a standard DesignStudio error. That's when I thought it is time to address this issue after all.

The following code examples are inspired by Mike Howles and Karol Kalisz, with whom I collaborate on the SCN DesignStudio SDK repository. I chose Leaflet and OpenStreetMap to show the integration.

First thing you have to do, is erase all of the libraries from the contribution.xml file which you want to load using requirejs. After that wrap your code in component.js like this:

The first section locates the SDK folder structure during runtime (local and platform mode) to address the external library files later on (lines 22-27). The following section configures requirejs for the on the on demand loading process (lines 30-44). Please note that the file references are missing the “js” file extension (Requirejs will provide it by default). One quick note regarding the “shim” section. Leaflet-Providers is a Leaflet plugin responsible for the loading of the freely available OpenStreetMap map tiles. This plugin relies on the global Leaflet variable “L” which is exposed on library load completion. Therefore we need to define a dependency for this plugin making sure that the library loading order and global variable declaration is correct and transparent for the plugin. The JavaScript method call sdkReqs actually loads the defined libraries. Please note that I am not exposing “prv” to the app code. But you could either assign an additional variable in line 46 to the function closure or load the library into a variable like this: var prv = require(“prv”);

At last you only have to ensure that all of the function closures opened at the top are closed again (lines 53-54). Now the tedious mismatched anonymous define error should be gone for good 🙂

Have fun using requirejs and as always feel free to ask lots of follow up questions.

Find the fully functional example project and the source files on GitHub: https://github.com/MartinPankraz/DesignStudioSDK-Components

Yours

Martin

References:

•     http://requirejs.org/

•     https://github.com/org-scn-design-studio-community/sdkpackage