1. Building Sites with Oracle Content Management
  2. Developing for Sites
  3. JavaScript Technologies

18 JavaScript Technologies

When developing components and themes for Oracle Content Management, you can choose any JavaScript technology stack you prefer. Samples provided with Oracle Content Management are based on vanilla JavaScript with some Mustache for basic templating, but there is no requirement to choose any specific JavaScript technology.

Load Custom Components

When using Oracle Content Management Site Builder, custom components and section layouts must be loaded into a page dynamically. This allows site contributors to add, remove, and position the components or section layouts on the page. To support this, each custom component must implement a render file that is responsible for bootstrapping the component into the page.

Components may be self-contained and work within any theme, or may rely on supporting JavaScript files in a theme's assets. Note that if custom components rely on theme assets, they will only work with sites based on that theme. Such components can be marked as Theme Components so that they are only available to sites that are based on the theme.

Load Components Dynamically

To dynamically load custom components into a page, the components must be built using either JavaScript Modules or, for legacy usage, RequireJS. If a component is built with JavaScript Modules, Oracle Content Management will load the component using: 

import(".../componentName/assets/render.mjs").then((Component) => {...});

If a component is built with RequireJS, Oracle Content Management will load the component using: 

require([".../componentName/assets/render"], function (Component) {...});

To distinguish between the technologies, components that use JavaScript Modules for component loading use a .mjs extension, for example render.mjs, and those that continue to use RequireJS will use ".js".

Note:

The use of JavaScript Modules is not supported by Internet Explorer. If your Oracle Content Management site still requires support for Internet Explorer, you must continue to use RequireJS for component development.

Default Inclusion of Components in a Site

If the the template used to create an Oracle Content Management site is set to use JavaScript Modules as the default JavaScript technology, then it uses a file called render.mjs to dynamically load custom components used in the site. If instead the template used to create a site is set to use RequireJS as the default JavaScript technology, then it uses a file called render.js to dynamically load custom components used in the site.

To change the default setting. select the site on the Oracle Content Management sites page and click Properties to open the side panel. Select the JavaScript technology to be used as the default under the Properties tab in the panel.

If for any reason the renderer can't find the default option for loading a custom component, it will note this in the console and try to load the component using the alternate file. This allows for backwards compatibility and helps migrate from RequireJS to JavaScript Modules.

Note:

Components can have both render.js and render.mjs files so that they can work regardless of the default JavaScript technology setting for a site. Typically this means that the render.js file is a simple generic wrapper that loads up the render.mjs file.

Alternatives to RequireJS Functionality

RequireJS provides additional functionality that JavaScript Modules does not. For example, with RequireJS you can access scoped technologies such as JQuery and Mustache that are exposed in Oracle Content Management through an API call. You can also take advantage of non-JavaScript resource loaders such as CSS or text.

To support this additional functionality when using JavaScript Modules, the SCSRenderAPI has been enhanced.

// To access scoped resources
SCSRenderAPI.getJQuery();
SCSRenderAPI.getMustache();
 
// To load non-JavaScript resources
SCSRenderAPI.importCSS(".../css/design.css").then(...)
SCSRenderAPI.importText(".../template.html").then(...)

When using content layouts in headless mode, the API call needs to provide the information and leverage the ContentSDK.

Note:

Implementation of these functions will update based on web browser support of ECMA standards. For example, import of stylesheets like JavaScript Modules.

Non-native JavaScript Technologies

Some choices of JavaScript technology stacks require additional processing before they can run in a browser. For example, using JSX or TypeScript in custom components will require the use of a transpiler such as BabelJS in the runtime environment unless the developer includes their own build step to create a version of the component that uses native JavaScript.

Oracle Content Management does not include Babel or provide any additional support for these non-native JavaScript technologies and it is up to the developer to make the decision on how the resulting JavaScript will run within the page.

Runtime Optimization

Adding components dynamically to a site page provides a site contributor with a custom experience for designing their pages. However, at runtime you want pages to run as fast as possible.

To support this, Oracle Content Management provides a compilation step that allows the developer of custom components and themes to generate the final HTML and CSS for the component and have it inserted directly into the page so that it is immediately available as the page renders.

There may be no need for any additional JavaScript execution for a custom component at runtime. However, if there are interactive elements for a component, there is a hydrate option available for the custom component that can be called after the page has rendered.

Default Inclusion of Components During Compile

The compilation step is run as a NodeJS application that looks for a compile.mjs file in the component's asset folder. If it finds the file, it will load the file and try to execute the compile() function within the component. If it doesn't find the file, it will try to load the compile.js file instead and use that.

NodeJS has historically used CommonJS for component loading. Similar to how there can be a render.js and a render.mjs file, there can be a compile.js file used by CommonJS for legacy components and a compile.mjs file for loading by JavaScript Modules.

Because JavaScript Modules are supported by both the browser and NodeJS, standardizing on .mjs files allows for easier sharing of common code between the render.mjs and compile.mjs implementations.