Implementing Custom Functionality

While custom style sheets are foundational for modifying the presentation of your solutions, modern websites are expected to provide interactive interfaces, dynamic content, and integrations with third-party services. This kind of custom functionality typically requires JavaScript (JS) resources. With the traditional plugin approach of modifying themes and altering core components, implementing custom functionality can lead to complex redeployments, increased maintenance overhead, and conflicts with future platform upgrades. Developers frequently require more granular control over custom code, with the ability to apply JS resources to specific pages or components without impacting the overall site. The global JS client extension solves these problems by providing a modular approach to implementing custom functionality without modifying core systems or dealing with redeployments.

In addition, many developers often require certain JS libraries, such as jQuery, to be available throughout their sites and Liferay instance. While they could use a global JS client extension to reference the library and register it in Liferay, the granularity of control actually works against them in this case. The referenced library would still have to be added manually wherever it is needed, a time-intensive, error-prone process that introduces more problems than it solves. The JS import map entry client extension provides an efficient, elegant solution to this common use case by making JS resources available to any page rendered in a Liferay instance, eliminating the need to load them multiple times.

In this lesson, you’ll learn how to use the global JS and JS import map entry client extensions to manage your JavaScript resources and implement custom functionality in your Liferay sites.

Using Global JS Client Extensions

The global JS client extension addresses a variety of use cases for enhancing site functionality and user experience. You can use global JS to add custom form validations that enforce complex business logic, such as cross-field validation or dynamic responses based on user input. This not only makes your data collection process more accurate, but also enhances the process for your users. Similarly, you can use this client extension to implement interactive UI elements like carousels, modal pop-ups, and custom navigation tools, improving your site’s usability without altering its theme and visual identity.

Another common use case for applying the global JS client extension is integration with third-party services, such as live chat widgets, analytics tools, and social media feeds. This capability extends to loading external APIs to display dynamic content or personalized data. You can build user-specific dashboards that are scoped to specific pages to minimize the impact on your site’s overall performance. Liferay recommends the global JS client extension as the primary mechanism for adding JavaScript resources to your site pages.

Anatomy of Global JS Client Extensions

The client-extension.yaml file for global JS client extensions has an assemble block indicating the source and target folders for the build process.

assemble:
    - from: build/static
      into: static

The extension definition block contains core configurations for the client extension, as in the following example from liferay-sample-global-js-3.

liferay-sample-global-js-3:
    name: Liferay Sample Global JS 3
    scope: company
    scriptLocation: head
    type: globalJS
    url: global.*.js
    scriptElementAttributes:
      async: true
      data-attribute: "value"
      data-senna-trac;: "permanent"
      fetchpriority: "low"

This table provides descriptions of the properties in the extension definition.

Using JS Import Map Entry Client Extensions

The JS import map entry client extension makes JavaScript resources available to any page rendered in a Liferay instance. This includes not only regular site pages, but also administrative pages accessible through the Control Panel. With this client extension, you can make libraries such as JQuery available everywhere in your Liferay instance. This eliminates the significant effort involved in adding the libraries on a page-by-page basis, and it improves performance by ensuring libraries are loaded only when they are needed.

Apart from the common library use case, this client extension is a key part of the custom element development toolkit, which you learned about in Module 1. With a JS import map entry, you can make a web component available on any page in your Liferay instance. Previously, this could only be accomplished by configuring a widget as a static portlet that would be included on every page. The JS import map entry client extension is the recommended tool for loading external resources efficiently when you need them to be globally available.

Liferay leverages a JavaScript loader to register modules (i.e., libraries) that should be available everywhere. The metadata for registering the module comes from the client extension’s client-extension.yaml file. Once registered, the JS module becomes available globally and can be referenced from your code using the standard import mechanism. For example, if you registered a JQuery module in your Liferay instance, you could access it in the JS code of a fragment with the following import statement:

import jquery from 'jquery';

So, while the library is available everywhere in your instance, the loader will only retrieve and render it on a page if it is imported by an element on that page. With this client extension, you can build increasingly complex user interface components by leveraging the flexibility of the import map, all without sacrificing performance.

Anatomy of JS Import Map Entry Client Extensions

The client-extension.yaml file for JS import map entry client extensions has an assemble block indicating the source and target folders for the build process.

assemble:
    - from: build/static
      into: static

The extension definition block contains core configurations for the client extension, as in the following example from liferay-sample-js-import-maps-entry.

liferay-sample-js-import-maps-entry:
    bareSpecifier: jquery
    name: Liferay Sample JS Import Maps Entry
    type: jsImportMapsEntry
    url: jquery.*.js

This table provides descriptions of the properties in the extension definition.

Conclusion

With the global JS and JS import map entry client extensions, you gain full control over JavaScript resources in your solutions at both the page level and the instance level. Next, you’ll help Clarity add some accessibility features to their website using the global JS client extension.