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.
NoteSee 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.112-ga112
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.
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.
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 existingdiv
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 exporteddoubleValue
function to double the number of pixels in an outline string, and finally uses jQuery’scss
function to add an outline using that string with thedefault
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)
TipIf 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.
Now you can publish the fragment and use it on any page.
You have successfully used a JavaScript import map entry client extension in Liferay. Next, learn about other types of frontend client extensions.