When creating an AEM Component, one may need to use JavaScript to perform DOM manipulations / Other Tasks on the component. The right way to add a JavaScript to go hand in hand with the component created is to use a Component Manager and to load JavaScript through the manager.
NOTE:
Usually a Component Manager invokes a jQuery plugin/module via its name on the component's element/root DOM node, But this Component Manager uses native JavaScript to achieve the same functionality as we're unsure about the availability of jQuery at load time.
Technical Answer: As AEM supports having multiple components on a single page, it would be a mess to manage all the components on the page via JavaScript. Theoretically, a non-AEM front end developer would write code for component in such a way that the code would be executed irrespective of the fact that the component is either present in the DOM or not.
This would cause the code written to fire on every page and probably causing blocks and errors in script execution. One way to avoid this is to use a simple checks to see if the element exists in order to curb this execution on all pages, but, if you have multiple functions targeting single component, it would be hard to keep track of unless proper documentation exists.
On the other hand, a Component Manager is used to load up such functions into a queue and then to queue up all functions of all components on the page and execute the functions one by one once page content is loaded.
Non Technical Answer:
Standard JavaScript functions which are written (poorly) for components, runs on every page and throws errors if component is absent and possibly breaks page.
A component manager is used to queue up all the said functions for components available on the page and executes them when the component is present.
Component Manager provides an API to queue up a component(s) into execution queue and stack all components into the queue and to execute the stacked queue.
When the page finishes loading and all associated content for components have finished rendering, the Component Queue Executes the function so the tasks in queue are executed sequentially.
Component Manager code is located in /etc/designs/aemcm/clientlib-componentmanager/js/componentmanager.js
The client lib is categorized as aemcm.componentmanager and is not embedded anywhere.
Component Manager should be referenced in /apps/aemcm/components/structure/page/header-libs.jspusing the clientlib category <cq:includeClientLib js="aemcm.componentmanager" />tag so the client lib is included and Component Manager gets loaded just before '</head>'.
Component Manager's method 'AEMCM.ComponentManager.runComponents()' is invoked in /apps/aemcm/components/structure/page/footer-libs.jsp Just before '</body>'
Just include the following code in your component's JSP/HTML file and replace content as necessary:
<script type="text/javascript>
AEMCM.ComponentManager.addComponent({
identifier: "ID_OF_COMPONENT",
method: "METHOD_NAME",
properties: [{
...additionalProperties
}]
});
</script>
replace "ID_OF_COMPONENT" with your component's root node ID and "METHOD_NAME" with the name of the function you want the component to execute If you wish to pass parameters to the function say ID or class names of element or any other data, you could pass it in properties parameter as JSON.
REMEMBER If you wish to send content from CQ Dialog or Server Generated content to your function you should send it the following way
`...
properties: [{
elementHeight: '${properties.elementHeight @ context="scriptString"}',
elementWidth: '${properties.elementWidth @ context="scriptString"}'
}]
...`
Make sure to add
@ context="scriptString"to your variable so that the content from HTL variable can be sent to the JavaScript function.
Use this boilerplate code in your JS and add your functions inside it.
"use strict";
/**
* @function METHOD_NAME
* @description alerts a name passed to it
*
* @author AUTHOR_NAME
* @version 1.0
* @returns {object} - contains a method to initiate the function
*/
function METHOD_NAME(){
/* global properties */
var functionProps;
// default properties
var defaultProps = {
functionName: "METHOD_NAME"
};
/**
* @function alertmyname
* @description alerts a string from a property
*/
var FUNCTION_NAME = function(){
/*
WRITE YOUR CODE HERE
*/
};
/**
* @function init
* @description kickstarts the code
*
* @param {object} properties - JSON object containing id, method and parameters
*/
var init = function(properties) {
// extend global properties with default properties
functionProps = Object.assign(defaultProps, properties);
// calling private function
FUNCTION_NAME();
};
return {
init: init
};
}
REMEMBER: replace FUNCTION_NAME and METHOD_NAME from the code above, and start writing your logic in FUNCTION_NAME function
Make sure that you have merged the Component Manager code in your code. If you haven't merged your code then you won't be able to use Component Manager.
In order to include Component Manager in your code, you need to merge this branch in to yours and build the project first. Here's what you need to do:
-
Open your terminal and navigate to the folder where you want the project to be created. Usually it would be the repository location (i.e., my-aem-project) Make sure your repository is clean (this step can be skipped; but is recommended).
-
Run the command "
git merge AEMComponentManager" to merge the Component Manager in to your code. -
If you use Adobe AEM Maven Archtype, then edit your
filter.xmlto include the files and then run the command "mvn clean install -PautoInstallPackage" to build and push the changes onto your AEM.
Open a ticket and post your problem, or contact me @trancelated