I often received questions how to change the site prefix or control pre-fetching of static resources like JavaScript in Oracle Content and Experience (OCE) Sites. The answer to these or similar question is often, – you should customize the Controller File for your site. In this post I will explain what the Controller File is, how you can and why you would customize it.

In OCE Sites, the Controller File is used to display each of the constituent pages in an online site.  When the browser sends a request for a web page, the server responds with a copy of the Controller File.  This is true for every page of the site – the same copy of the Controller File is delivered from the server. In short,  the Controller File is a small HTML web page that dynamically initiates the rendering sequence for the remainder of the page.  In this unique position it is the first place that customization can be applied to affect the behavior of every page of your web site.

The primary task of the Controller File is to provide and host an execution environment for the Controller JavaScript  (the Controller JavaScript subsequently loads and displays the web page).  Customizations in the Controller File provide the ability to override and influence the operation of the Controller JavaScript.

Customizing the Controller File

When an OCE Site is initially created, a default Controller File is associated with the site.  You can though, customize it for a site by using the Settings > Site > Controller File controls in the Site Builder (see screenshot at the top of this article).  There you can download the default Controller File (controller.html) and then modify the file to fulfill your requirements. Controller File customizations are part of Sites Builder’s “Update” framework.  As such, the site “Update” must be committed, and the site must be published in order for the online site to use the custom Controller File.

Note: Customization to the Controller File is only used in the online site.  The custom Controller File is not used in Site Builder editing or in site previews.

The Default Controller

A sample Controller File is displayed below.  It is a simple HTML file that defines JavaScript variables and includes the main Controller JavaScript.

Now, what does it actually do:

• Line 4: Thistag is used for IE browsers.  It indicates that the browser should use the latest rendering mode to display the web page.
• Line 5: Thistag is used for browsers on mobile devices, setting the initial viewport scale to the full page.
• Line 7: This is the initial definition of the “SCS” object.  The SCS object must be present, and this variable name is reserved for use by OCE.
• Line 9: This tag loads the full controller JavaScript, which is used to display the web page.
• Line 11: The tag of the controller must have the id “scsControllerBody”.  This identifier is used by the Controller JavaScript.
• Line 11: This line is displayed to browsers (and crawlers) that do not process JavaScript.
• Line 12: This is an image that displays if it takes too long to display the web page.  By default this is an animated “wait” circle.  The wait image must have the id “scsWaitImage”.

The “SCS” Object

The Controller JavaScript makes use of variables and properties defined in the global “SCS” object in order to render the web page.  This global JavaScript object must be defined in the Controller File, before the inclusion of the controller.js file. There are two primary properties in the SCS object that can be used for customization purposes.

SCS.sitePrefix

This variable defines the path prefix of the online site.  Normally this defaults to “/site/{siteName}/”.  The Controller JavaScript uses this value to determine what web page to display.  For example, if the browser is requesting the page at “/site/SampleSite/products/index.html”, the sitePrefix, “/site/SampleSite/”, allows the JavaScript to compute that the “products/index.html” page in the site should be displayed. Modifying this variable allows the site prefix to be customized.  For example, setting the sitePrefix to “/intranet/ExampleSite/” would allow the web site to be delivered with that pathname in the browser instead of the default “/site/SampleSite/” path prefix.  (Of course, a proxy or other infrastructure like Akamai CDN and URL mapping rules would need to be in place for this to work.) Please keep in mind that :

• Internally the default Controller JavaScript will use “/” as the sitePrefix if the URL in the browser does not match the site prefix.  This allows the site to be served via a vanity domain without customization.
• The sitePrefix must be a String value that begins and ends with a ‘/’ character.

SCS.preInitRendering

This function is called, if defined, by the Controller JavaScript code before any of its computational logic executes.  This is a useful function to define in custom Controller Files in order to override basic operations of the Controller JavaScript. If defined, preInitRendering must be a function.  It will be called without any arguments, and no return value is expected or processed.

Auto Replacements / Untouchable Sections

Certain sections of the Controller File are processed by the OCE Server in order to use the static.oracle.com CDN and to define URL caching segments.  These are noted inline in the sample below.

Portability

The name of the site appears in certain places of the Controller File which makes it non-portable  between the sites. Consider the Controller File shown in the “Default Controller” section above.  On lines 7 and 9 the site name “SampleSite” appears.  This ties this Controller File to the particular site named “SampleSite”.  Attempting to use this Controller File on a different site with a different name would not work.  This also applies to sites created from a Site Template having a customized Controller File.

Samples

The HTML snippets described in this blog can be downloaded from here.

Changing the Site Prefix

The following sample Controller File defines a preInitRendering function to allow the site to be delivered on multiple prefixes.

Please keep in mind when using this sample:

• Note the “/SampleSite/” keywords in the sample.  See the section on Portability above.
• Additional prefixes for the site are defined on lines 12..14.  If none of these match the browser URL, the default behavior would be used.
• To make use of sample, Akamai or another proxy would need to be configured to respond to the defined prefixes.

Customizing the wait graphics

The following sample Controller File customizes the wait graphic that is displayed for when rendering is delayed due to network delays.

Please keep in mind when using this sample:

• Note the “/SampleSite/” keywords in the sample.  See the section on Portability above.
• This sample uses a “Data URL” for the image instead of incurring a separate request during the rendering

Custom favicons

The following sample Controller File defines a custom favicon for the site.  This may be useful for browsers that do not dynamically load the favicon from the rendered page’s Document Object Model.

Please keep in mind when using this sample:

• Note the “/SampleSite/” keywords in the sample.  See the section on Portability above.
• This sample uses a “Data URL” for the image instead of incurring a separate request during the rendering.

Prefetching JavaScript Files

Certain browsers allow the declaration of resources that will be needed in the current or subsequent navigations.  Markup in a Controller File can declare resources that should be pre-fetched or pre-loaded.

Please keep in mind when using this sample:

• Note the “/SampleSite/” keywords in the sample.  See the section on Portability above.
• Since every OCE web page utilize require.js and renderer.js, these are good candidates for the pre-loading and pre-fetching techniques.
• When the href is listed first in the tag, its value is subject to fix-up by the OCE server to be delivered from the static.oracle.com CDN

Summary

I hope you realized that ability to customize the Controller File gives you a powerful tool that allows you to alter default behavior of pages for the whole site. In the past we often recommended to use custom Controller File to change the no-script message and meta tags for bots or search engine crawlers that do not process JavaScript or to inject a site verification markup for 3rd party crawler and search engines. With addition of the Prerender service for sites in July (19.3.2) release of OCE, this not required anymore – Prerender service can detect requests coming from search crawlers or bots and respond with pre-rendered HTML page which allows even crawlers that do not understand JavaScript to successfully index you OCE site.