Adding Custom JavaScript
AEM allows you to use custom JavaScript files to provide extra functionality and styling to your pages, in much the same way as custom CSS is implemented. These can enhance your AEM site and make them more unique. Some examples of custom JavaScript files are transition effects – such as block of text slowly transitioning in as the mouse hovers over them – menu systems, and jQuery scripts.
When using JavaScript, it is assumed that you or your AEM Site Admin have the knowledge of how to properly use and configure the script.
Important note: As some scripts — particularly those utilising the jQuery library — can interfere with AEM's authoring functionality, scripts are disabled during authoring mode. To test your script, click on the magnifying glass in the Sidekick to enter Preview mode. Refresh the page using your browser's refresh button and the script will be run.
Adding a JavaScript file to a Page using Page Properties
If you only want to use a JavaScript file on one page of your site, it's best to add it to one specific page using that page's Page Properties. This reduces loading time across your site. In most cases, this is the preferable method for adding a JavaScript file to a site.
1. Upload a JavaScript file to the DAM.
2. Open the Page Properties for the page you want to use your JavaScript on. To learn how to use the Page Properties, see Page Properties.
3. In the Advanced tab, expand the Custom Stylesheet and Javascript section.
4. Beside JavaScripts, click the Add More button.
5. Click the magnifying glass beside the field that appears.
6. In the window that appears, navigate to the location in the DAM where you uploaded your JavaScript file to, and click OK. Click OK again to close the Page Properties and save your changes.
Adding a JavaScript file to a Site Configuration Page
If you want to use a JavaScript file on multiple or all pages of your site adding it to your site's site configuration page is the most efficient way to do this. Typically, your AEM Site Admin will manage the site configuration page.
To learn how to add a JavaScript file to a Site Configuration page see Site Configuration Page.
Initializing a JavaScript on your AEM Page
Some JavaScripts and jQuery scripts require a small block of script to initialize variables, or otherwise run the script.
Typically, this small block of code would be called in the <head> of an HTML page. In AEM, this is done using an HTML Component.
1. On the page where you want to use your JavaScript file, create an HTML Component.
- If your initialization script has structural tags, such as
<div>tags, place the HTML Component where you want it to be in your layout.
- If it's just JavaScript, placement of the HTML Component doesn't matter.
2. Inside the HTML Component, add your initialization. It may look someting like this:
$(".a_class").aScript({
variable: "a name",
width: 100px,
description: "an example of a javaScript initialization",
});
3. Surround your initialization with <script> elements, which lets the browser know what kind of code it's receiving. If you have any structural tags, such as <div> elements, make sure they are outside the <script> elements.
<script type="text/javascript">
$(".a_class").aScript({
variable: "a name",
width: 100px,
description: "an example of a javaScript initialization",
});
</script>
4. Click OK to save your changes to the HTML Component.
5. Check if your JavaScript is working properly. In the Sidekick, select Preview Mode, and then refresh your browser. You should see your script properly working at this point.