JavaScript events

The custom events used in CONTENTdm are fired by the React-based front-end website application. These events are based on the CSS classes and provide several timing options, :enter, :ready, :update, and :leave. If you are already familiar with how CONTENTdm's events work, you can go directly to the List of JavaScript lifecycle events.

• :enter :  This event indicates that a user has navigated to a page, but the page has not started to render yet.
   
• :ready :This event fires when a page has rendered and is ready to use. This is the point where the page markup has been built, which means it can be acted upon by custom JavaScript and an end user can see the UI.
   
• :update :  This event fires whenever a page updates its state. Since React applications depend heavily on changing portions of pages rather than full page refreshes, this event is a critical part of the page lifecycle.
   
• :leave :  This event fires when a user has chosen to leave the current page.

Depending on what your JavaScript code is doing, you may want it to fire at one or more of the above points in the page lifecycle. For example, a simple script that redirects the end user to another page would most likely need to run at an:enter event since that is the earliest point in the lifecycle prior to rendering and a page redirect doesn’t need or want any of the UI to be displayed. 

On the other hand, a script that modifies the UI elements in the page, would need to wait until a  :ready event so that the HTML is available for manipulation. The :ready event is going to be the most commonly used for any JavaScript operations that add or modify UI in a page.

The :update event will be used by custom JavaScript that depends on specific conditions within a page. For example, if your custom script looks at an end user’s search results and adds some UI to them, you would want that code to keep firing each time the user clicks ‘next’ to another set of results. The ‘next’ and ‘previous’ actions are linked to the :update event. You can determine which end user actions are :update events vs. :enter events by observing whether the entire page reloads. In CONTENTdm, if the URL in the browser address bar does not change, then the end user action is most likely happening simultaneously with an :update event. Many common JavaScript customizations will need to subscribe to both the :ready and :update events for the page so that they fire once when the page starts up and any time afterward that end user actions change the page state.

The :leave event is useful if you need to clean up any changes your custom code may have made. For example, if your code creates a custom feature in the page header but only on certain pages or depending on conditions within a page, you might not want that UI to persist when the user clicks to another page. You can create a cleanup function that fires only at a :leave event and removes or resets the UI you created.

There is a special event that fires one time at the initial load of the website application: cdm-app:ready. This event fires once for a given end-user session and is the earliest time point in the application lifecycle.

Here is a simple example of JavaScript that subscribes to these events. The following code applies a random background color to each of the collection cards on the default CONTENTdm home page.

// 
// change the background color of the cards on homepage 
// 
// random color generator
function getRandomColor() { 
    var letters = '0123456789ABCDEF';
    var color = '#'; 
    for (var i = 0; i < 6; i++) {
        color += letters[Math.floor(Math.random() * 16)]; 
    } 
return color; 
} 

// subscribe to the homepage ready event
document.addEventListener('cdm-home-page:ready', function(){
    Array.from(document.querySelectorAll('.cdm-collection-card'))
        .forEach(function(card){
            card.firstChild.style.backgroundColor = getRandomColor();
        });
});

// and subscribe to the homepage update event
document.addEventListener('cdm-home-page:update', function(){ 
    Array.from(document.querySelectorAll('.cdm-collection-card'))
        .forEach(function(card){
            card.firstChild.style.backgroundColor = getRandomColor();
        });
});