Detecting the CMS
The following techniques can be used to detect when a page is being rendered in the CMS. This lets you change the behavior of pages in the editor using HTML, CSS, and JavaScript.
Your site's scripts run in the editor too. If a script changes anything inside a content region, those changes will be published, so use these techniques to keep such scripts from running in the editor.
HTML
Special HTML comments can be used to tell the editor to ignore them. They use the following syntax.
<!--cms-ignore-->
<p>This shows on your website, but not in the editor.</p>
<!--/cms-ignore-->
Write the comments exactly as shown, with no spaces inside them. The first closing comment ends the block, so they can't be nested.
When a page is rendered in the editor, everything inside of these special comments will be removed, so don't use them inside content regions or static includes. Anything ignored inside a content region is lost when you publish.
One popular use for special comments is to prevent scripts from running.
<!--cms-ignore-->
<script>
console.log('This will run on the website, but not in the editor.');
</script>
<!--/cms-ignore-->
Notice
Previous versions of Surreal CMS used cms-disable instead of cms-ignore for
special comments. The old syntax has been deprecated but is still supported for backwards compatibility
purposes.
CSS
When editing a page, we add the is-cms class to the <html> element. You can
use this to target the CMS in your stylesheet.
Here's a contrived example that adds a red border to every <div>, but only in the
editor.
.is-cms div {
border: dashed 2px tomato;
}
Guide colors
If the editor's guides are hard to see against your design, you can change their colors. Set
--cms-guide-color for content regions and --cms-repeatable-color for
repeatables on the root of your page. The colors apply to the whole page.
They have no effect on your live website.
:root {
--cms-guide-color: #0f766e;
--cms-repeatable-color: #c2410c;
}
@media (prefers-color-scheme: dark) {
:root {
--cms-guide-color: #2dd4bf;
--cms-repeatable-color: #fb923c;
}
}
If your site has a dark mode, set the colors again wherever it switches its other colors. That can be a
media query, a class, or an attribute, as long as it's on <html>. A dark mode class
on <body> won't change the guides. See
light and dark mode for how we recommend
setting that up.
Guides are drawn just outside each region, so pick colors that stand out against every background your regions sit on, including colored sections, hero images, and cards. Aim for a contrast ratio of at least 3:1, or 4.5:1 for repeatables, since their outlines are thin and dashed.
Your brand color is a good place to start. If it's too faint, use a darker shade of it in light mode and a lighter shade in dark mode. If a page has both light and dark sections, a mid-tone can reach 3:1 against both.
Use different hues for regions and repeatables so editors can tell them apart, and make one lighter than the other for people who are colorblind. Avoid red, which looks like an error, and colors your design already uses for borders near regions. Use solid colors, since the editor fades the guides on hover.
JavaScript
For more control over your scripts, you can test the value of window.isCMS. It will be
true when the page is rendered in the CMS.
if (window.isCMS) {
console.log('This is the CMS.');
} else {
console.log('This is not the CMS.');
}
This variable is set at the end of the <head>, so scripts that run earlier in the
<head> will see undefined. In those scripts, check for the
is-cms class instead. It's safe to check at any time.
if (document.documentElement.classList.contains('is-cms')) {
console.log('This is the CMS.');
}
Meta tags
When a page is rendered in the CMS, it will also include the following meta element.
<meta name="is-cms" content="true">
You can check for this meta tag using JavaScript.
if (document.querySelector('meta[name="is-cms"]')) {
// This is the CMS
} else {
// This is not the CMS
}