Bundling Resources in a JavaScript Import Map Entry Client Extension

Liferay 7.4 2023.Q1+/GA92+

JavaScript import map entry client extensions make JavaScript code or resources available to any page rendered in a Liferay instance. When you must include JavaScript code or resources from multiple locations, you can bundle them in one client extension in your Liferay workspace.

Define and export code in the client extension with a specifier that the import map in Liferay provides to anything that imports it. For example, you can bundle a library like jQuery into the client extension, and then import it into a fragment’s code to use it.

Start making JavaScript import map entry client extensions with one from the sample workspace.

Prerequisites

To start developing client extensions,

Install a supported version of Java.

Note

See JVM Configuration for recommended JVM settings.

Download and unzip the sample workspace:

curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip

unzip com.liferay.sample.workspace-latest.zip

Now you have the tools to deploy a client extension bundling multiple JavaScript resources.

Examine and Add to the JavaScript Exports

The JavaScript import map entry client extension is in the sample workspace’s client-extensions/liferay-sample-js-import-maps-entry/ folder. It’s defined in the client-extension.yaml file:

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

It also contains the assemble block:

assemble:
    - from: build/static
      into: static

This specifies that every file created in the build/static/ folder should be included as a static resource in the built client extension .zip file. The liferay-sample-js-import-maps-entry example uses webpack (configured in the included webpack.config.js file) to define the exported entry and its output location. It imports jQuery, which provides various utilities for manipulating HTML via JavaScript.

In the assets/ folder, the index.js file contains this JavaScript code:

import jquery from 'jquery';

export default jquery;

This code uses the jQuery library and exports it using default. Exporting it here allows it to be used in Liferay when you import the defined bareSpecifier in client-extension.yaml.

You can also add another export that can be accessed using the same specifier. Add this JavaScript code to export a new function that doubles a value:

export function doubleValue(value) {
    return value * 2;
}

Now deploy the client extension.

Deploy the Import Map Entry

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Once Liferay starts, run this command from the client extension’s folder in the sample workspace:

../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)

This builds your client extension and deploys the zip to Liferay’s deploy/ folder.

Note

The command used to deploy your client extension changes if you use a self-hosted instance outside of Docker, Liferay PaaS, or Liferay SaaS. See Deploying to Your Liferay Instance for more information.

Tip

To deploy all client extensions in the workspace simultaneously, run the command from the client-extensions/ folder.

Confirm the deployment in your Liferay instance’s console:

STARTED liferaysamplejsimportmapsentry_7.4.13 [1459]

Now that you have imported a new entry into the JavaScript import map, create a new fragment to use it.

Add a Fragment Importing the Code

On any site in your running Liferay instance, click Design → Fragments.
Click Add () to add a new fragment set.
Enter FS as the name and click Save.
Click New to add a new fragment.
With Basic Fragment selected, click Next.
In the Add Fragment modal, enter Outlined Text as the name and click Add.
On the fragment design screen, click into the HTML editor and add a paragraph (<p>) tag in the existing div with text to be outlined:
```
<div class="fragment_1">
    <p>
        Outlined text!
    </p>
</div>
```
The text appears in the preview panel in the lower-right corner.
Click into the JavaScript editor and add this code to import from your client extension:
```
const jq = await import('jquery'); // dynamic import

var outline = jq.doubleValue(2) + "px solid blue";

jq.default("div.fragment_1").css("border", outline);
```
This code imports the code from your client extension into the jq constant. Then it uses your exported doubleValue function to double the number of pixels in an outline string, and finally uses jQuery’s css function to add an outline using that string with the default export.

The text now appears in the preview panel with a 4-pixel wide, blue outline.

![The fragment’s JavaScript uses your client extension to use two functions to define and add a blue border to the tebundling-resources-in./using-a-javascript-map-entry-client-extension/images/03.png)

Tip

If the outline does not appear correctly, make sure the div element’s class name in the HTML editor (e.g., fragment_1) matches the code you copied into the JavaScript editor.