Using External Libraries

You can use external (i.e., anything but Metal.js, jQuery, or Lodash, which are included in Liferay DXP) JavaScript libraries in your portlets. There are a few methods you can use to make external libraries available. The method you should choose depends on the external libraries you plan to use and how you plan to use them (as modules or as browser globals).

This tutorial covers how to adapt external libraries for Liferay’s JavaScript Loaders.

Go ahead and get started.

Configuring Libraries to Support UMD

If you’re the owner of the library, you should make sure that it supports UMD (Universal Module Definition). You can configure your code to support UMD with the template shown below:

// Assuming your "module" will be exported as "mylibrary"
(function (root, factory) {
    if (typeof Liferay.Loader.define === 'function' && Liferay.Loader.define.amd) {
        // AMD. Register as a "named" module.
        Liferay.Loader.define('mylibrary', [], factory);
    } else if (typeof module === 'object' && module.exports) {
        // Node. Does not work with strict CommonJS, but
        // only CommonJS-like environments that support module.exports,
        // like Node.
        module.exports = factory();
    } else {
        // Browser globals (root is window)
        root.mylibrary = factory();
  }
}(this, function () {

    // Your library code goes here
    return {};
}));

Next you can learn how to load external libraries as browser globals.

Loading Libraries as Browser Globals

If you want to use a library that doesn’t export itself as a named module (as is the case for many plugins) or load the library as a browser global, follow the steps in this section.

Note: These steps only apply to users on Liferay Portal CE 7.0 GA4, Liferay Digital Enterprise 7.0 SP2 (Fix Pack 8), or lower patch levels. If you’re on a higher patch level, follow the steps in the Using Libraries that You Host section.

Follow these steps to load your libraries as browser globals:

1. Add a <script> tag with the following content before loading your module:

   <script>
       Liferay.Loader.define._amd = Liferay.Loader.define.amd;
       Liferay.Loader.define.amd = false;
   </script>
   

2. Next, add a <script> tag to load the module itself. Below is an example configuration:

   <script type="text/javascript" src="${javascript_folder}/library.js">
   </script>
   

3. Finally, cancel the change made in the previous step, by adding the following <script> tag:

   <script>
       Liferay.Loader.define.amd = Liferay.Loader.define._amd;
   </script>
   

This approach lets you load your modules as browser globals. Next, you can learn how to load libraries that you host.

Using Libraries That You Host

If you’re hosting the library (and not loading it from a CDN), you must hide the Liferay AMD Loader to use your Library.

If you’re running Liferay Portal CE 7.0 GA4, Liferay Digital Enterprise 7.0 SP2 (Fix Pack 8), or a higher patch level, you can hide the Liferay AMD Loader through the control panel. Follow these steps:

1. Open the Control Panel, navigate to Configuration → System Settings.

2. Click JavaScript Loader under the Foundation tab.

3. Uncheck the expose global option.

Note: Once this option is unchecked, you can no longer use the Liferay.Loader.define or Liferay.Loader.require functions in your app. Also, if you’re using third party libraries that are AMD compatible, they could stop working after unchecking this option because they usually use global functions like require() or define().

If you’re running a lower patch level than Liferay Portal CE 7.0 GA4 or Liferay Digital Enterprise 7.0 SP2 (Fix Pack 8), follow these steps to hide the Liferay AMD Loader:

1. Name the library in the define function, as covered in the Configuring Libraries to Support UMD section. Below is an example configuration:

   Liferay.Loader.define('mylibrary', [], factory);
   

2. Remove the UMD wrapper if (typeof Liferay.Loader.define === 'function' && Liferay.Loader.define.amd) or update the UMD wrapper to match the one below:

   if (false && typeof Liferay.Loader.define === 'function' && Liferay.Loader.define.amd)
   

3. Configure your bundle’s build task to run the configJSModules task over the library.

   This task names the library and generates the appropriate loader configuration for you.

Now you know how to adapt external libraries for Liferay’s JavaScript Loaders.

Related Topics

Configuring Modules for Liferay Portal’s Loaders

Liferay AMD Module Loader

Using ES2015 Modules in Your Portlet