Skip to main content
OCLC Support

JavaScript customization overview

  1. Last updated
  2. Save as PDF
Find an overview of using JavaScript customization for your CONTENTdm website.

If you are used to doing DOM manipulation (especially with jQuery) to achieve your customizations, things will work differently in the React-based CONTENTdm website. The JavaScript customizations you add will need to subscribe to, or listen for, a specific lifecycle event and will be triggered as those events occur during the application's lifecycle. Customization code will not directly interact with or manipulate the CONTENTdm React application, but will instead be fired by the event lifecycle established and controlled by the React application. These events allow your code to interact with the DOM as the user navigates in or out of a particular CONTENTdm page.

The reason we chose to use React to build the CONTENTdm website is that page speed is very good because page renders are prebuilt, and portions of the page are loaded or refreshed only as needed. Custom JavaScript added to a CONTENTdm site will not gain all these benefits because the code is not tightly integrated into the React application, but you can optimize execution by adhering to the event lifecycle and page context.

If your custom code interacts correctly with the page lifecycle, your customizations can execute only when needed during page startup, render, update, or exit. The key to making this work is having your code subscribe to the appropriate application event.

If your customizations intend to manipulate the DOM generated by CONTENTdm, be warned that this approach may conflict with how the React application needs to use and modify the DOM. If the CONTENTdm application cannot find what it expects in the DOM, the app can crash, and the end user’s session will be lost. However, if your custom code creates its own elements and modifies or removes them, there should be no problems on the React side.

If you are used to working with jQuery, note that it relies heavily on direct DOM manipulation and abstracts some of it, so it is not always clear when it is happening. It is possible to use jQuery within the CONTENTdm React application, but be careful with the scope of those DOM changes. In general, your code should not use jQuery to remove or change elements in the DOM if those elements were created by the CONTENTdm React application. On the other hand, if your jQuery code creates its own elements and modifies or removes them, it should be safe. 

The CONTENTdm website does not use jQuery, so it is not already available in the default HTML. If you want to use jQuery in your customizations, your custom code will need to link to it and load it at the appropriate lifecycle stage. Your website and customizations will likely perform better if you can avoid using jQuery.

 View a recording:  Ask the Experts: Building a custom JavaScript recipe for CONTENTdm. Requires access to the OCLC Community Center. See Sign in to the OCLC Community Center for more information. Also see CONTENTdm training for related training videos.