JavaScript customization overview

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 that you add will need to subscribe, or listen, to a specific lifecycle event and will be triggered as those events occur during the lifecycle of the application. 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 enters or leaves a particular page of CONTENTdm.

The reason we chose to use React to build the CONTENTdm website is that page speed is very good because page renders are pre-built and portions of the page are loaded or refreshed only as they are needed. Custom JavaScript added to a CONTENTdm site will not gain all of these benefits since the code is not tightly integrated into the React application, but you can optimize the 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 they are needed within the 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 created by CONTENTdm, be warned that approach may conflict with the way the React application needs to use and change 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 is creating its own elements and modifying or removing them, there should be no problems on the React side.

If you are used to working with jQuery, note that it relies on a lot of direct DOM manipulation and abstracts some of this manipulation so that 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 is creating its own elements and modifying or removing 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 time in the lifecycle. 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.