Mercury Documentation

Use individually customized CSS

It is possible to integrate an individually customized CSS. This allows HTML experts to adapt the appearance of certain pages to specific requirements. 

Advanced HTML and CSS knowledge is required to use this option.

The option to use customized CSS or JavaScript is disabled by default. Please ask your OpenCms system administrator to enable this option for your website if you wish to use it.

Please note that the HTML, CSS, and JavaScript of the Mercury template are constantly being developed. Unfortunately, individual customizations cannot be taken into account. It is therefore possible that your individual customizations will no longer work after an update of the template. In this case, you will have to “repair” these customizations by yourself after an update. 

First, create your own CSS in a local editor as a .css file.

The file name has to be custom.css.

Upload this custom.css file to the start folder of your site or subsite in OpenCms. If individual CSS customizations are enabled, this CSS file will be automatically integrated into all web pages in the site or subsite.  

Only one CSS file is integrated at a time. For example, if you have stored a custom.css file in the start folder / of your site and another one for the subsite in the folder /my/subsite/, ONLY the custom.css file from the folder /my/subsite/ will be integrated for the subsite.

Setting custom CSS classes on an element

If individual CSS customizations are enabled, you can add your own CSS classes for most elements on the page.

In this case, the “CSS modification” element setting displays a “pencil” icon to the right of the standard selection options. Click on the pencil to specify your own CSS classes. These will be added to the generated HTML.

Content with customized CSS formatting

This content has been given the special CSS customization my-special-css in the element settings. This makes the background blue and adds padding to the edges.

This selector is defined in the CSS file /en/resources/basics/customized-css/custom.css.

Show CSS files

A custom JavaScript file is uploaded and integrated in exactly the same way as a custom CSS file.

The file name for this file has to be custom.js (instead of custom.css).

Content with special JavaScript action

This content has been assigned the special CSS modification my-js-demo in the element settings.

In the JavaScript file /en/resources/basics/customized-css/custom.js, this selector is used to change the background color of the element via jQuery when the mouse is moved into or out of this element.

Note: this demo does not work in the page editor, but only in the activated preview mode of the page.

Show JavaScript file

If you integrate your own JavaScript, it can access a jQuery instance that is loaded by the Mercury template.

Please note: We plan to discontinue the use of jQuery in Mercury in the future and only use “pure” JavaScript. We therefore recommend that you create your own scripts directly without jQuery.

To initialize your own JavaScript with jQuery, use the function

mercury.ready(handler) instead of $(document).ready(handler).

jQuery is loaded asynchronously by the Mercury template for performance reasons. If you use mercury.ready(handler), your handler function will only be called once jQuery has been loaded and is available.

The first argument passed to the called handler function is an initialized jQuery object.