We have seen in the previous chapter how to use GateIn module system and the script integration. The goal of this section is to provide a list of common use case and how they can be addressed by GateIn. The section is two parts: the module cookbook and the script cookbook.
Let's study how to declare a GateIn module, the integration of the Highlight.js library. This example can be found among the GateIn examples in the amd-js.war. The Highlight.js is actually a jQuery plugin, jQuery plugins are perfect examples as they are natural GateIn modules and follow the self-invoking pattern that consumes the jquery dependency as $. Here is an overview of the Highlight.js source code:
It is integrated using the XML declaration:
- The module is named highlight and uses the /highlight/highligh.js source code bundled in the war file
- The depends tag creates a dependency on the jquery module. The dependency is aliased as $ using the as tag to match the Highlight.js self-executing function argument $.
|The jquery plugins comes out of the box with GateIn and one should not worry about declaring it. The jquery module is simply named jquery and provides the jQuery 1.7.1 .|
In the previous section we mentioned that GateIn can integrate native AMD modules since GateIn modules are translated to AMD modules. Asynchronous module declaration is well explained in the RequireJS documentation and you should read it if you want to be familiar with the format.
AMD modules follow the pattern:
GateIn can use such module out of the box, however some parts will be overridden by the XML declaration:
- The "module" name will be ignored and replaced by the declared module name
- The module dependencies from "dependency1" to "dependencyN" have to be declared with the same name in XML (we will see later that we can use the as tag to override the dependency name)
Assuming that the dependencies dependency1 to dependencyN have been declared in XML, such module definition can be declared with the following XML:
GateIn provides the jQuery library 1.7.1 as a jquery module, the configuration of this module can be found in the eXoResources.war file. To reuse this jQuery version one just has to declare a dependency over it:
The default jquery module alias is $ so if you are using it, it should be named $ in the self-executing function:
If your library use a different name such as jQuery the XML as tag should be used:
With the following self-executing function:
Consider an example with a jQueryPortlet using jQuery version 1.6.4, what we need to do is to configure the two modules properly:
In this section, we are going to see how to configure a jQuery plugin and how to use it in jQueryPluginPortlet portlet. The plugin code is a minimal plugin:
The plugin is then declared as a module:
Finally we use this plugin in our portlet:
One important point to have in mind is that our portlet module should depend on the jquery and the jquery-plugin modules even it will not use the plugin itself:
- declaring the dependency on jquery allows to use the jQuery object
- delcaring the dependency on jquery-plugin ensures that the plugin will be loaded in the jquery dependency before it is injected in the portlet module
We have seen previously how to declare a native AMD module and said that the module dependency names must match the AMD dependencies declared in the define function arguments. When there is a mismatch between a module declared in the native module and the module system of GateIn the as tag can be used for renaming the dependencies.
Let’s say that there is a foo.js file defining an AMD module named foo with two dependencies ["dep1", "dep2"] as following :
Now let's suppose that the dependencies are declared as module1 and module2 in GateIn, as we can see the names don't match. To override this we can use the as tag to rename the dependencies:
CommonJS defines its own module format, although it is not supported natively by GateIn, the adapter format can be used to adapt CommonJS modules to work nicely in GateIn.
Here are two simple CommonJS modules:
CommonJS modules use its require function which is conflict with RequireJS same function. So in order to make it works in AMD
enabled environment, these modules need to be wrapped and injected predefined modules: require, exports and module provided by Requirejs (details here). The good news is that developers don't need to do this themselves, GateIn will wrap the code for you based on configuration using the adapter format:
We need to use adapter tag here and declare the require, exports and module dependencies of the CommonJS module. Now any module can have Mustache instance injected just by declaring it in its dependencies list:
RequireJS provides support for loader plugin allowing a module to be a plugin and use the AMD system for loading web resources in an efficient manner.
Text.js is a native AMD module, it also depends on the module dependency predefined dependency provided by the AMD loader. Thanks to the native AMD support of GateIn, it is straight foward to declare and use Text.js in GateIn:
Now we can use the mustache and text modules to load templates and render them in our own module:
Sometimes it is required to access a module from a script, RequireJS provides such capability by using the require function to execute a function in the managed context:
In such situation we need to use the AMD module name of the module we need to depend on, PORTLET/ModuleA in this case. The prefix in upper case is the module scope among SHARED, PORTLET and PORTAL.
As explained previously, the built-in jQuery is currently declared as an AMD module. By default jQuery will not be available in the window object of the browser. This cookbook recipe shows how to make it available so one can write code like in a plain script.
The following script will make jQuery available by mounting the jQuery object in the window object:
This script must be integrated as a shared script:
A portlet can then provide its own script that depends on this script:
We can define a globally available custom jQuery quite easily. For this we reuse existing recipes seen previously and combine them:
- Use a custom jQuery version
- Expose GateIn version of jQuery globally
There are a few ways to implement this recipe. However, the most important point to keep in mind is to make sure that the global jQuery is available before the global jQuery plugin is loaded.
We have seen before how we can scope a module to a portlet, the module will be loaded when the portlet is on a page using the PORTLET scope. In this recipe we will change and use instead a PORTAL scope, the main difference is that the loading of our plugin will be triggered on a specific portal instead of a specific portlet.
First step we create our jQuery plugin as a script named myPlugin.js and we integrate our plugin:
Second step we bind the script in our portal and also reuse the immediatejs script seen before:
Now, our plugin is globally available and we can use it: