aui_script.md

Demystifying aui:script tag

IMPORTANT

Infrastructure is sunsetting AlloyUI since when "The status and direction of the frontend infrastructure in Liferay 7 & DXP" blog post was released. Also, We are working hard in removing those components on Remove AUI / YUI from Liferay Portal Epic. Please, avoid using AlloyUI JS components and tags, except for aui:script tag.

What it does

This tag allow users to use and require ES module/resources inside a JSP.

We have three possible use cases when using this tag:

1. Inline JS on the JSP
2. Import an AUI/YUI module
3. Import an ES module

Inline JS on the JSP

By just placing JavaScript code inside an aui:script tag, you can take advantage of optimizing scripts and place them to be made available in the final compressed JavaScript bundle. It can be achieved when appending the script to the AUI_SCRIPT_DATA WebKey and all these scripts will be applied at the bottom of the page. Finally the Aggregate Filter will take care, of creating the final bundle with all the JavaScript on the page. It is worth mentioning that the same rule applies to all the following use cases.

Like this example:

<aui:script>
	Liferay.fire('myGlobalEvent', {
		payload: 'myPayload',
	});
</aui:script>

it will be turned on:

Liferay.fire('myGlobalEvent', {
	payload: 'myPayload',
});

Import an AUI/YUI module using the use property

⚠️ This is a deprecated use case, though it still works if someone configures it.⚠️

Each AUI / YUI module listed as a value for the use property will be loaded asyncronously by the AUI().use function.

You can import several YUI / AUI modules within the same use property, as in this example:

Here is an example:

<aui:script use="liferay-alert">
	new Liferay.Alert(
		{
			closeable: true,
			message: 'I like drink tea while eating french potatoes',
			type: 'success'
		}
	).render('#myId');
</aui:script>

The output will be a code like this:

AUI().use('liferay-alert', function (A) {
	(function() {var $ = AUI.$;var _ = AUI._;
		new Liferay.Alert(
			{
				closeable: true,
				message: 'I like drink tea while eating french potatoes',
				type: 'success'
			}
		).render('#myId');
	})()
}

Note in the AlloyUI components, coming from the alloy-ui repository, classes are made available from the global variable A on the scope of the aui:script(as in this code snippet the Menu component is defined).

However, components made available from the frontend-js-aui-web module will be under the global Liferay variable. Like this example here, where Liferay.Upload is implemented, used in the code example above.

Import an ES module using require property

Allows users to require a modern ES module as in the following example:

Considering we already have metal-clipboard and metal-dom dependencies listed in our module package.json

By default, the name of the variable referring to the required resource will be composed by transforming the resource's path to camel case. For example:

<aui:script require="metal-clipboard/src/Clipboard">
    // Note how the required metal-clipboard/src/Clipboard is made available in the metalClipboardSrcClipboard variable
	new metalClipboardSrcClipboard.default();
</aui:script>

You can have a look at the details of the algorithm for composing variable names in the VariableUtil.generateVariable() method.

Also, We can set an alias with the as word after the provided path. It would look like:

<aui:script require="my-custom-lib/src/path/main as myLib">
	// ... code that uses some function from myLib like `myLib.someFunction();`
</aui:script>

The output will be:

Liferay.Loader.require('my-custom-lib/src/path/main', function(myCustomLibSrcPathMain) {
	try {
		(function() {
			var myLib = myCustomLibSrcPathMain;
			var $ = AUI.$;var _ = AUI._;
			// ... code that uses some function from myLib like `myLib.someFunction();`
		})();
	} catch (err) {
		console.error(err);
	}
}

You can find more information on this link

Using position to control script placement

This property will change the way in which the script will be injected into the page. By default, those scripts that are wrapped by aui:script will be added to the minified files as described in "Inline JS on the JSP".

When placing the option of inline for this property, the scripts will be placed in a script tag obeying the order of the DOM where the JSP is being rendered. See the aui:script tag implementation here..

sandbox

The purpose for the sandbox attribute is to wrap the contents of the script tag in an Immediately Invoked Function Expression/IIFE.

As a short brief, it will limit the scope of the script tag. See the following example:

<aui:script>
   var myVar = 'foo'; // This variable will be available globally
</aui:script>

<aui:script sandbox="<%= true %>>
   var myVar = 'foo'; // This variable will NOT be available globally
</aui:script>

Caveats

You can't use both require and use in the same tag. use is for declaring dependencies on AUI modules, while require gives access to ES modules.

You can see more information about aui:script in "Loading Modules with AUI Script in Liferay DXP".