1. Beginner’s Guide to Oracle Content Management Sites Compilation – Part 1

Oracle Content Management (OCM) provides powerful site-building capabilities. Site contributors can use Site Builder to create site pages, add component to them in WYSIWYG manner and create or update the content on those pages. The actions of contributors are stored as metadata for each page in a page-ID.json file. To render the resulting page, Oracle Content Management uses a “page controller” architecture – when a web browser requests a site URL, the server returns controller.html file that loads a ‘page controller’ JavaScript file in the browser. The JavaScript parses the requested URL to identify which page-ID.json file should be downloaded and then uses metadata in the file to construct the HTML for the page to display in the end-user browser.

A “page controller” architecture is perfectly suited for intranet and extranet sites where data is constantly changing. However, it does have some drawbacks in terms of search engine optimization (SEO) and for sites that need to be optimized for speed. For SEO, any request should ideally return only HTML for a page as search bots may not execute JavaScript at all or can timeout before page construction is complete. In either case search bot will not index page content correctly. Similarly, if you’re optimizing your site pages for speed, you want to reduce the JavaScript code executed on the page to render page content and only download HTML and CSS content to the web browser.

This is where site compilation in Oracle Content Management comes in.

Site compilation is the process of creating a static HTML file for each page in a site. It generates a server-side rendered page by combining the page layout with the page-ID.json metadata to generate the HTML file that will be returned, instead of the controller.html file with JavaScript. The resulting HTML page will behave exactly the same as the dynamic page that would have been rendered by the JavaScript controller file in the web browser. The difference is only in what is initially downloaded to the browser in response to a site URL request:

• Controller page – a controller.html file with JavaScript to parse the URL and generate page HTML based on the page-ID.json metadata, or
• Compiled page – a fully rendered HTML file for the page that was generated on the server-side.

Site compilation in Oracle Content Management is an optional process that can be called after the site is published to generate the static HTML pages for the site. Please note that while the HTML files for compiled pages are being created, the site pages will render dynamically as a controller page. As soon as the HTML files have been created and published, site URL requests will return the compiled pages.

Note: If any component isn’t compiled into the page, then the component will still render dynamically within the compiled page at runtime. This allows you to have dynamic content within an HTML page.

Site Compilation Process

Site compilation is a Node.js application that executes in the background after the site has been published. Since the Oracle Content Management compiler is a Node.js application, it requires Node-based implementations of any component that are used on the page. If such an implementation doesn’t exist, then the component won’t be compiled into the page and the component will instead be rendered dynamically within the compiled page.

The compiler will walk through the entire site and generate the HTML files for all pages in the site. Please note the following:

• If the site has multiple languages, it will generate the HTML files for each language.
• If the site is using detail pages to display individual content items or digital assets with their unique slug-based URLs (for example, display a blog post or news article), then it will also generate the detail pages to display individual items with their unique URLs.
• If you have both a mobile and desktop implementation of a site, it will generate both sets of pages.

Once the site compilation is completed, the generated HTML files are uploaded to a ‘static’ folder under the site. From there they are published to the site runtime. Subsequent requests to a site URL will return these compiled HTML files.

Tip: To find out if a site page is being rendered as a compiled or controller page, you can view the page source in your web browser. If the page is delivered as compiled, you’ll see the page HTML code. If it is delivered as controller page, you will see the controller.html file instead. 

Custom Components in Compile Page

Oracle Content Management allows you to use the JavaScript stack of your choice for developing components. You may be using VueJS, React, or simply a templating option such as Mustache to create your custom components. Since Oracle Content Management does not control what JavaScript stack is used, it’s up to you, as the component developer to also provide the Node.js based implementation of your component so that it can generate HTML to be included into the compiled page. If there is no such implementation of the component, then the component will continue to render dynamically within the compiled page at runtime.

To indicate that there is a Node.js based implementation of a component, you need to create a compile.mjs file within the assets folder of the component.

Here are some additional things to consider if your aim to optimize page performance at runtime:

• Through the site compilation, you can ideally, remove all JavaScript from the page that is not required to support page functionality on the a client-side. This includes removing any Oracle Content Management JavaScript code, so that only HTML and CSS are rendered in the browser, which gives the page the fastest possible runtime performance.
• As you develop custom compilers for your components, consider implementations that don’t require any further JavaScript files to be downloaded. If JavaScript is required, consider inlining it into the page rather than downloading additional files.

Set Up Site Compilation

Site compilation is built around Oracle Content Management Content Toolkit, which provides a set of command-line options that allows you to interact with Oracle Content Management from a terminal window. While it’s possible to upload compile.mjs files to your custom components within Oracle Content Management and use the built-in compilation server and log files for troubleshooting, you should always start with the Content Toolkit installed on your development machine to develop the compile.mjs files and test/debug them. Details on how to download and install the Sites Toolkit can be found on GitHub or in the documentation here.

The key toolkit commands for site compilation are:

• cec create-template
• cec compile-template

Note: for the purposes of this guide, comments indicating browser instructions assume you’re using the Google Chrome web browser.

To get started, install the toolkit using the setup instructions on GitHub. After installation is complete, you should have:

• A ‘cec-src’ folder, which you need to be in to run the ‘cec’ commands.
• A registered server “DEV”, which allows you to connect to your Oracle Content Management instance and list available resources.

Once the folder has been created and the server connection is established, you can download a site from your Oracle Content Management service and compile it using the toolkit. 

Compile a Site

To get a basic understanding of the site compilation, we will use a site that uses only out-of-the-box components. These already have compilers created for them so you don’t have to do anything to see the site compiled and understand the differences between compiled vs. controller rendering.

Create a Basic Site

These are the main steps for creating a basic site:

1. Create an enterprise site called “StaticSite” using the ‘Blank’ or ‘Starter’ template.
2. Edit the site and update the home page with these basic seeded components: Title, Paragraph, and Button.
3. Save and commit your changes.
4. Publish the site.
5. Bring the site online.
6. View the published site.

Right-click anywhere on the page and view the page source. You’ll see the controller.html file with JavaScript that’s rendering your page. The JavaScript controller file is loaded with the following <script> tag:

<script src="/site/StaticSite/_cache_e01a/_sitesclouddelivery/renderer/controller.js"></script>

Download the Site to the Content Toolkit

Assuming you registered a server “DEV” while installing the Content Toolkit, run the following command to download the site to the toolkit ‘sec-src’ folder:

cec create-template StaticSite --site StaticSite --server DEV --excludecontent

Note: Although this site has no content, using the “–excludecontent -x” command will minimize the download time for content you don’t want to host locally. During compilation, you can specify that content requests should be made back to the Oracle Content Management server.

Tip: cec command-line options also have abbreviations, for example: “-x” instead of “–excludecontent”.

Compile Your Site

Now that you have the site locally, you can compile it:

cec compile-template StaticSite --verbose

Note: You’ll see warnings about no page compiler being found, but don’t worry, we will deal with that later. Page compilers allow you to further optimize the compiled page, for example, to create the HTML menu for the site to be inserted into the page rather than having it be created dynamically at runtime.

Upload Compiled Pages Back to the Server

After compiling your site, you have a set of HTML files created under src/templates/StaticSite/static.

These files need to be uploaded back to your site on the Oracle Content Management instance so that they can be published. The toolkit provides a command to do this for you:

cec upload-static-site-files ./src/templates/StaticSite/static --site StaticSite --server DEV

Note: Later on we’ll see how you can do this as a single zip file rather than with individual files.

Publish the Compile Pages

After the static files have been uploaded to the server, you’ll need to publish the HTML files so that these will be returned rather than the controller.html file. You can use the Oracle Content Management web user interface to re-publish the entire site, which will also publish these HTML files, or you can use a toolkit command just to publish the HTML files:

cec control-site publish --site StaticSite --server DEV --staticonly

View the Compile Site

After the compiled pages have been published, view the published site again in your web browser.  Right-click anywhere on the page and view the page source. Instead of the controller.html file being displayed, you will now see the HTML source being rendered for all the components you added to the page.  

Use Component and Page Compilers

Each component on the page, as well as the page itself, needs to have a Node.js based compiler to produce the HTML code to be inserted into the resulting HTML file.  During site compilation, all the page and component compilers are executed in parallel, and the resulting HTML code is inserted into the appropriate locations within the page once everything has completed.

Custom Compilers

To compile a site that has custom code, you can introduce the following compilers to alter how the site is compiled. Each of these creates the HTML code for the corresponding entity: 

• Page compiler – creates the theme/layout/<page>.html file. This allows you to customize the HTML code that is finally produced for the page. If the custom page compiler doesn’t exist, the page layout as-is will be used as the basis for the HTML page. 
• Component compiler – creates the HTML code for custom components, content layouts, and section layouts. If the custom component compiler doesn’t exist, the component will be rendered dynamically in the compiled page at runtime.

Seeded Compilers

Node-based compilers have been implemented out-of-the-box for all seeded components, apart from the following components that will always render dynamically:

• Document, Social, and Process components. These are rendered with an iFrame, so compiling these into a page provides no benefits.

Plus, some seeded component may render dynamically, depending on its configuration:

• Content Item, Content List, or Placeholder components whose content layouts don’t have a custom compiler. To render content for these components, you must create content layouts. If your content layouts don’t have custom compilers, then no HTML can be created for the component. In that case, the component will continue to render dynamically when the static page is displayed at runtime.
• Paginated Content List component – if you have a content list that allows pagination, then it assumes that you have a potentially unknown number of assets that it could be display. To support this, the paginated content list will render dynamically to allow it to paginate to any amount of items. Non-paginated content lists are compiled into the page.

Out-of-the-Box Site Compilation Server

Using the command-line utilities in the Content Toolkit for compiling your site and pushing the changes back to the server is best suited in development or testing of site compilation. After you have validated that the site and components compile successfully and produce the result you’re looking for, you should move to using built-in site compilation server to automatically do this after you publish a site. To enable site compilation on publish you need to turn on this in the site Properties UI. With this option turned on, when you publish a site, it will submit the site to the built-in site compilation server.

To turn on out-of-the-box site compilation for a site that you’re a manager of:

1. Open the site properties.
2. Open the Static Delivery tab.
3. Enable the Compile site after publish option.

After you publish the site, the compilation job will be submitted to the server and you can track its progress on the Static Delivery tab:

Once compilation is complete, you can download the log of the compilation process from this properties dialog.Note: The built-in site compilation server is a shared service for all tenants on the Oracle Content Management pod. As such, it has a two-hour time limit for compiling a site. You should validate that the time it takes to compile your site doesn’t exceed this limit before using built-in service. If your site does requires more than two hours to compile, you can continue using compilation server in the Content Toolkit that is deployed on Oracle Compute VM.

Compile Only

Once your site has been published, you have the option to re-compile the site without having to re-publish the entire site. This is useful, for example, if you’ve updated and re-published some assets, but not otherwise changed anything else on the site. To compile the site directly, when the site has been published, the compile option is available to you on the context menu when you select the site. This option is only available if the site is published and the Compile site after publish option is enabled for the site.

Manage HTML Files

After compilation is complete, generated HTML files are uploaded to the site. These files will always be published with the site, even if the Compile site after publish option is not enabled. Oracle Content Management server will return compiled page in response to a URL request that matches the HTML file location. If that is not expected behavior, you should remove compiled HTML files by selecting the Delete Static Files option at the bottom of the Static Delivery tab in the site Properties.

In the Part 2 of this blog you will learn about developing, debugging and testing compilers to allow compilation of custom components or content layouts in your site.