Home / Beginner’s Guide to Site Compilation

Beginner’s Guide to Site Compilation

Introduction

Oracle Content Management provides powerful site-building capabilities. Site contributors can use Site Builder to create site pages, add components 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, which 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 time out before page construction is complete. In either case, search bots won’t 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, vs.
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’s delivered as controller page, you’ll see the controller.html file instead.

Custom Components in Compiled Pages

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 doesn’t 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’s no such implementation of the component, then the component will continue to render dynamically within the compiled page at runtime.

To indicate that there’s 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 you 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 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 the Oracle Content Management Content Toolkit, which provides a set of command-line options that allow 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 Content Toolkit can be found on GitHub or in the documentation here.

The key toolkit commands for site compilation are:

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 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’ll 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:

Create an enterprise site called “StaticSite” using the Blank or Starter template.
Edit the site and update the home page with these basic seeded components: Title, Paragraph, and Button.
Save and commit your changes.
Publish the site.
Bring the site online.
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 Sites 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

Although this site has no content, using the --excludecontent (or -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

You’ll see warnings about no page compiler being found, but don’t worry, we’ll 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

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

Publish the Compiled 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 Compiled 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’ll 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’s finally produced for the page. If the custom page compiler doesn’t exist, the page layout will be used as-is 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 their 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 displayed. 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’ve validated that the site and components compile successfully and produce the result you’re looking for, you should move to using the built-in site compilation server to automatically do this after you publish a site. To enable site compilation on publish, you need to turn this on in the site properties UI. With this option turned on, when you publish a site, it will automatically 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:

Log in to the Oracle Content Management web interface with the appropriate privileges.
Open the site properties.
Open the Static Delivery tab.
Enable the Compile site after publish option.

Properties for Site dialog, with the Compile site after publish option selected.

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:

Properties for Site dialog, with the Static Delivery tab open and a progress bar.

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 the 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’s deployed on Oracle Compute VM. You should also look at the various options to speed up the compilation process.

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 action 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.

Selected site with its action menu, which includes the Compile option.

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’s 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.

Develop, Debug and Test a Site

Now let’s delve into how to develop, debug, and test a site in more detail, but before we do that, here are some things to consider:

Developer productivity — When developing any Oracle Content Management component, whether for rendering or compiling, you want to be as productive as possible. You should not use a model where you have to make a change, find where to upload the file, upload the file, wait for the upload, navigate back to the site, and refresh the page (even though this would work). At a minimum, you want to be able to edit your JavaScript and then save/refresh to see the change. Only once you have all the code as you want it, should you upload it to the server to validate in the full Oracle Content Management server.
Node vs. browser environment — When creating a custom compiler, you’ll be writing a Node.js module. You need to be aware of the constraints when writing Node.js applications, as Node.js modules don’t have access to browser objects such as the DOM, window, or common browser libraries such as JQuery. Similarly, REST calls in Node.js and the web browser use different libraries and syntax. So any code using these types of objects in your renderer implementation will need to be translated to native “node” calls when you’re writing the compiler.
Technology choice and common code — When developing component renderers and compilers you’ll most likely want to share as much code as possible. This impacts the choice of JavaScript technology as using any third-party JavaScript stack that renders elements dynamically in the browser will require special handling to make the same code work efficiently when you’re compiling the component into the page. For example, choosing a simple templating solution such as MustacheJS will allow you to share a lot of code, since it works when both compiling under Node.js and rendering directly in the browser. If you choose a sophisticated JavaScript stack, it may allow you to have advanced UI elements and user interaction when the page is run dynamically, but you’ll also need to work out how to have those elements compile directly into the page.

Development Flow

The easiest way to develop components is to start with the default implementation of the component in a basic site with the minimum set of resources required to render the component. For example, if you want to display a new content item of a new content type, you would perform these steps:

Create the content type.
Create a content layout component.
Map the content layout component to a category in the content layout map for the content type.
Create an item of this content type in the site’s repository.
Edit your site and drop the item of the content type onto a page and select the content layout map category.

To further develop the content layout, you’d use the Content Toolkit to leverage the work you’ve already done to render the content item onto the page:

Commit your changes in the Site Builder web user interface.
Then, using CLI commands in the toolkit:
- create a template from the site, which saves the site to the local file system, and
- use the local development server provided by the toolkit to render the site.

At this point, you have all the code on your files locally. You can change the source of the content layout you created and refresh the site that’s rendered by the site’s toolkit development server to see the changes. After you’ve made all the required changes locally, you can use the toolkit to upload the Content Layout component back to the Oracle Content Management server. Follow the same development flow for creating custom compilers.

Develop Custom Compilers

In this example, we’ll develop a compiler for a custom component. All the custom compilers follow the same pattern. To get started, install the toolkit using the setup instructions on GitHub. After you are done, 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 established, you can download a site from the Oracle Content Management server and compile it in the toolkit.

Create a Local Component

On the /documents/components page of your Oracle Content Management web UI, create a local component named “SampleComponent” and choose Mustache as the component type (technology). After creating the component, click on the component and view its ‘assets’ folder. You’ll see the following files in this folder:

SampleComponent
  assets 
    common.mjs --- shared code between render.mjs & compile.mjs
    compile.mjs --- sample custom component compiler
    render.js --- wrapper for when component is included in the page using RequireJS
    render.mjs --- renders the component dynamically into the page
    template.html --- shared template used by common.mjs

The seeded compile.mjs file contains a basic implementation of the component custom compiler that matches the default render.mjs file.

Create a Basic Site And Add the Local Component

Next, create an enterprise site called “StaticSite” using the Blank or Starter template. Edit the site, update the home page and add the “SampleComponent” to the page. Save and commit your changes.

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 folder:

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

If you get the error below, you can remove the existing template by removing or renaming the folder under cec-src/src/templates/StaticSite and run the command again.

ERROR: A template with the name StaticSite already exists. Please specify a different name.

Compile Your Site

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

cec compile-template StaticSite --verbose

When you compile the site, you’ll see the following warning message from the SampleComponent’s compile.mjs file:

Warning: the custom compile() function has not been implemented in: file:///.../cec-src/src/components/SampleComponent/assets/compile.mjs

This message is returned by the SampleComponent compile.mjs file to let you know that you need to update the file to make sure it’s in sync with any changes to your render.mjs file. You need to keep both these files in sync to ensure that the user sees the same content regardless of whether the component is rendered dynamically or statically.

Dynamic Component in Compiled Page

If you now open up the compiled page for the site, you’ll see that the component is still rendered dynamically, even though the page has been compiled. To view the page, start the toolkit development server, if it’s not already started:

cec develop

Open your web browser and view the compiled home page:

http://localhost:8085/templates/StaticSite/home.html

If you right-click anywhere on the page and choose to view the page source, you’ll see the slots on the page, but no content for the SampleComponent you created. The SampleComponent is being added to the page dynamically after the page is loaded. You can see the component in the page by right-clicking any part of the rendered SampleComponent and choosing to inspect that component.

The reason the component is not being compiled into the page and instead is being rendered dynamically is that the compile.mjs file currently doesn’t return any content for the component.

Static Component in Compiled Page

If you open up the src/components/SampleComponent/assets/compile.mjs file in an editor, you’ll see the following entry:

if (false) {
    // return the generated HTML and use hydrate in the render.js file to add any event handlers at runtime
    return resolve({
        hydrate: true,
        content: componentHTML
    });
} else {
    // warn the user that the compile function hasn't been implemented
    console.log('Warning: the custom compile() function has not been implemented in: ' + import.meta.url);
 
    // If the compile() function doesn't return any content, then the component will execute dynamically at runtime
    return resolve({});
}

To remove the warning and instead return the compiled HTML for the component so that it renders statically in the compiled page, change the "if (false)" statement to "if (true)", save the file, and then re-compile the site:

cec compile-template StaticSite --verbose

This time you won’t see the warning message. Open your web browser and view the compiled home page:

http://localhost:8085/templates/StaticSite/home.html

Right-click anywhere on the page and choose to view the page source. Now you’ll see the SampleComponent HTML code inserted into the compiled page.

Compilation Errors

During compile you will get three types of messages: Info, Warning, and Errors.

Info messages are about issues that you should be aware of, but these messages are probably expected as part of compilation:
- Placeholder content items that will render at runtime.
- Missing page layout compilers. Page layouts might not have any dynamic element and so aren’t considered an issue if they are missing.
- Items marked as “render on access”; that is, the site developer wants this component to be dynamically rendered at runtime even though the page is compiled.
Warning messages are about issues that will likely affect the performance of the running site and should be fixed where possible. Items in this category follow:
- Missing content layout or custom component compilers. Without these, the components will render dynamically into the page as they did previously.
- Missing content layout maps. It’s unlikely that you would want to use the system default content layout to render content items.
Error messages are about issues that indicate a compilation failure. The pages will continue to compile where possible, but the overall compilation will exit with an error.
- This is most likely caused by JavaScript errors in custom compilers, and any errors must be resolved.

Note: To reduce repetitive messages, the same message will appear only once per compilation regardless of whether it occurs on multiple pages.

Debug Custom Compilers

Debugging Node.js applications is very similar to debugging browser applications. To debug a Node.js application, you can use the same web developer tools that you’d use when debugging JavaScript within a web browser. For more details on the options for debugging Node.js application, review the Node.js documentation.

To enable debugging of cec commands, there’s a --debug parameter. This will start the Node.js application in --inspect-brk mode, which means the debugger will break before user code starts and wait until the debugger is attached. Once the debugger has been attached, you can enter breakpoints and continue debugging as you would any JavaScript code and then click on resume to start executing the code.

Connect to the Debugger

To start debugging your component, start the complication command in debug mode:

cec compile-template StaticSite --verbose --debug

The output from this will look something like below, and it will stop until the debugger is connected:

Debugger listening on ws://127.0.0.1:9229/0545c509-cc26-4c3c-966e-e0d1b5ddd56e
For help, see: https://nodejs.org/en/docs/inspector

To connect your debugger, bring up Google Chrome and enter the following URL

chrome://inspect

The browser will display the cec command as a gulp.js entry in the Remote Target section.

DevTools window with Remote Target section.

If you click on the inspect link, it will bring up the Chrome Developer Tools with the debugger paused at the beginning of the cec compile-template command. In the debugger, if you click on the resume option, the compile will run through and complete.

Break in Your Custom Compiler

Using the ‘Filesystem’ entry in the source tab of Chrome Developer Tools, you could navigate until you find your component and then put a break point within the component. A simpler way to make sure the debugger stops in your custom component is to update the compile.mjs file for your custom component and add the debugger; command to the compile() method:

Debugger console.

Re-run the compile-template command with the debugger:

cec compile-template StaticSite --verbose --debug

Go back to the Chrome browser and click on the inspect link, which will automatically reappear on the chrome://inspect page. Click resume in the debugger and the compile-template command will start and it will stop on your debugger; breakpoint.

Debugger console.

The same pattern can be used for all custom compilers.

Test Compiled Pages

Minimize Compilation Time

During the develop/debug/test cycle, you want the fastest turnaround time. You don’t want to wait for the entire site to be compiled to validate your changes. In the example so far, there’s only one language and a few pages, so compiling the entire site hasn’t been an issue. As your site grows, however, you may want to focus only on specific languages or pages for validating your component.

To restrict the list of pages that will be compiled, you can use the --pages option. This option restricts the page that will be compiled to the selected set. For most component development, this should be a single page.

cec compile-template StaticSite --verbose --pages 10,12

To restrict the list of languages that are compiled, you can use the --localeGroup option. This option will limit the compilation to only the selected languages.

cec compile-template StaticSite --verbose --localeGroup en-US,de-DE

Combining these options will allow you to validate all your changes on a few select pages before you kick off the complete site compilation to generate all the static files for your site.

Preview URLs

When you compiled your template, you may have seen the following output showing a preview URL:

createPage: Processing pageId 12. Preview URL: http://localhost:8085/templates/StaticSite/home.html

The preview URL uses the local development server that comes with the Content Toolkit. To start up the development server, run this command:

cec develop

After the server is up and running, you can enter the preview URL in the browser and see the compiled page. If you view the page source in your web browser, you’ll see your custom component compiled into the page.

Local Development Server and Compiled vs. Controller Pages

When you access a page in the development server, the server will return the compiled page. If the compiled page doesn’t exist, it will fall back to controller page—that is, to loading the controller.html file, which will run the page dynamically. If you do want to see the controller pages, then you need to remove the ‘static’ subfolder from your template folder. In this example, we’re using the template named ‘StaticSite’, so to render the controller pages you’d remove the files under src/templates/StaticSite/static.

Content

The examples so far have only considered custom component compilers. If you want to build custom content compilers, you need to consider how to access the content. When you create a template using the Content Toolkit, you have the option of downloading the content as part of the template. However, while there’s some basic support for querying that content using the local development server, the local development server is not a replacement for the actual Oracle Content Management server and does not support all REST APIs for content.

In most cases, the better option is to exclude the content when downloading the template. To exclude the content when creating the template, use the --excludecontent parameter:

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

Now, in order to access the content, you need to provide both the server and channel token when compiling a template. To get the channel token, select the API property for the publishing channel for your site. In the Oracle Content Management web UI, navigate to Administration > Content > Publishing Channels. Once you have the channel token, you can compile the template with these values:

cec compile-template StaticSite --verbose --server DEV --channelToken df5d1d4c1a8e4d77b7c7e54ab016843e

All REST API calls to get content will now be made back to the server using the given channel token.

Published vs. Draft Content

By default, both the create-template and compile-template commands will use the draft version of the site and content.

Please note the following:

To download the published version of the site, use the --publishedversion option. This will ignore any unpublished changes to the site, theme, and components when creating the template and download the published files only.
To use published content during compile, use the --type published command-line option. This will use the content delivery REST API calls.

Upload and Publish Compiled Files

Compiled Files Structure

After you’ve compiled your site using the Content Toolkit, you’ve created a set of HTML files that are in a ‘static’ folder in the corresponding template folder. In previous examples, we were using a template called ‘StaticSite’, so the compiled pages are placed under:

src/templates/StaticSite/static

The structure of the files under this folder uses a _files structure to disambiguate actual URL segments from file names. For example, if you had a page with a URL https://.../StaticSite/home, then the files you would have listed are:

static
  _files --- folder containing files resolving all URLs under: https://.../StaticSite
     home --- compiled HTML for https://.../StaticSite/home

Extending this to a hierarchy, if you have:

https://.../StaticSite/home
https://...//StaticSite/products/productA

then files you would have listed are:

static
  _files --- folder containing files resolving all URLs under: https://.../StaticSite
     home --- compiled HTML for https://.../StaticSite/home
     products --- compiled HTML for https://.../StaticSite/products
  products --- folder containing URLs under https://.../StaticSite/products 
     _files --- folder containing files resolving all URLs under: https://.../StaticSite/products
        productA --- compiled HTML for https://...//StaticSite/products/productA

The folder hierarchy static/products maps to the StaticSite/products URL segment, whereas the actual HTML to display is stored in the _files folder.

Locales

If you have locales in your site, you’ll have an entry at the top-level of the HTML files for each locale that’s compiled. Using the above example and assuming you have en-US and de-DE locales, you’d have the following structure:

static
  en-US
    _files
       home - compiled HTML for https://.../StaticSite/home
       products - compiled HTML for https://.../StaticSite/products 
    products - folder containing URLs under https://.../StaticSite/products 
       _files
          productA - compiled HTML for https://...//StaticSite/products/productA
  - de-DE
      (same set of files as for en-US compiled in the de-DE locale)

Upload Compiled Files

Once you have compiled your template, you’ll need to upload the resulting HTML files to the corresponding site in the Oracle Content Management server. This will place the files in a ‘static’ folder under the site. You have the option of uploading individual files or creating a zip of all the files and uploading a single zip.

Upload a zip

To upload a single zip file of all your files, create a zip file zip of the entire ‘static’ folder (and all subfolders), for example:

cd src/templates/StaticSite/static
zip -r ../staticFiles.zip \*

Once you have the zip file of all your compiled files, you can upload it to the ‘static’ folder on the server.

cec upload-file src/template/StaticSite/staticFiles.zip --createfolder --folder site:StaticSite/static --server DEV

Upload Individual Files

If you wish to upload individual files, you can use the upload-static-site-files command:

cec upload-static-site-files src/template/StaticSite/static --site StaticSite --server DEV

Publish Compiled Files

After you’ve uploaded the HTML files, these files will automatically take part in the site publishing. When you publish the site, the HTML files are copied to the site runtime along with all the other site resources. When a request comes in for a site URL, the compiled pages are first checked to see if the URL matches any HTML file in the path of the static files:

If a match to the HTML file is found, the compile page is returned.
If no match to any HTML file is found, the controller page is returned—that is, a controller.html file is returned to allow the page to be rendered dynamically.
If JavaScript loaded in the controller.html file is unable to match the URL to any site page, the site’s 404 error page will be displayed.

Publish Files via the OCM Web Interface

If you publish a site in the Oracle Content Management web interface, any files in the static folder will automatically be included in the site publish. There’s no option to only publish the static files.

Publish HTML Files via the Content Toolkit

To publish the HTML files using the Content Toolkit, use the control-site command. For example, to only publish the compile files, you can use:

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

If the site is not published, this will only copy the files to the published folder. The files will only be visible once the site has been published and brought online.

Controller Page vs. Compiled Page vs. Prerendered Page

How Oracle Content Management Resolves Site URLs

When a site URL is requested, the server may return one of the following page types in response:

Compiled page—a precompiled HTML page.
Controller page—a controller.html file for the site with JavaScript that decodes the incoming URL and builds the site page in the browser.
Prerendered page—an HTML snapshot of a controller page that’s generated by the Oracle Content Management Prerender service.

The site page is rendered dynamically in a headless browser, the resulting HTML is scraped from the browser, and then stored to allow prerendered page reuse in subsequent page requests.

To determine what page type to return, the server will first try to match the URL with a compiled site page. If the server doesn’t find a match to HTML file in the site ‘static’ folder, the server will behave differently depending on the user-agent header in the request:

The server will first try to match the URL with a compiled site page.
- If the server finds the compiled site page, the HTML file for the page is returned.
- If the server can’t find a compiled site page:
  - If the user-agent is a not a search bot known to Oracle Content Management, it will return a controller.html file to the browser and let the page controller deal with the request.
  - If the user-agent is a known search bot, it will return the prerendered page to the browser.
    - If the server can’t find the prerendered page, then a controller.html file is returned to supply a dynamic site page as a fallback.

This order means that if you have a compiled page, that page will also be returned for search bots and not the prerendered page.

Compiled Page

Compiled site pages are static HTML files generated by the Oracle Content Management compilation server and optimized for runtime performance of your site. Compiled site pages are designed to behave exactly the same as the original dynamic site page. All user interactions with the page are maintained so that the end-user will typically not be able to tell the difference between the two, unless you applied an extra post-compilation HTML optimization of compiled pages.

Controller Page

Controller pages use controller.html file for a site with JavaScript that decodes the incoming site URL and then loads the associated page.json and page layout files to build up the site page dynamically in the web browser based on the page metadata. If the controller JavaScript can’t find a site page matching the URL in the request, then it will display the 404 error page for the site.

Prerendered Page

Prerendered site pages are specifically designed to help with site indexing by search bots, and this meets search engine optimization (SEO) requirements for your site. While some search bots can handle JavaScript rendering to some degree, if a search bot only saw content of the controller.html file and it didn’t execute the JavaScript it loads, then all the site pages would be indexed as having only the controller.html file content, which is empty by default.

To avoid this scenario, the Oracle Content Management server checks the user-agent header in a site page request. If a request is coming from a known search bot, the built-in Prerender server is used to handle it. The Prerender engine uses controller.html file to render site pages dynamically in a headless browser, scrapes the resulting HTML from the browser and then returns it in response. The Prererender server also stores the resulting HTML to reuse it in subsequent requests to the same site page. To further optimize page request-response time, the Prerender server periodically runs through public sites created on your Oracle Content Management instance and indexes each site by rendering its pages and caching pages as scraped HTML. Cached HTML is then returned in response to the next request by a search bot.

Note: The objective for prerendering site pages is to provide the raw content of each page for site indexing and not to maintain user interaction with the site page. Therefore, prerendered pages won’t function the same as the original dynamic site page.

Title and Copyright Information

Beginner’s Guide to Site Compilation

July 2023

Primary Author: Oracle Corporation