How To Allow Stylesheets in the HTML Editor

Among the relatively few things that a developer can do to make the HTML editor in the CMS more user-friendly, the most significant is to set up the editor stylesheet properly.

Setting up the Preview

There are a number of default styles in the HTML editor, but the strong likelihood is that those styles do not necessarily match the styles on your live site. The first step to correcting that is to set up an editor stylesheet. You can do this by navigating to Site -> Site Properties and selecting your primary site stylesheet to be the new Editor Stylesheet.

After saving your template settings and refreshing the page, you should see the same styles in the HTML editor that you see on the live site. If the styles are NOT the same, there are three probable causes:

1. You forgot to refresh the page (this is easy to do if you have multiple tabs open). I know this step is a pain, but it is necessary.
    
2. Your live page uses a different stylesheet, or possibly multiple stylesheets. Unfortunately we only currently have the ability to include a single editor stylesheet, so if this is the case for you, perhaps consider combining multiple stylesheets into a single master stylesheet. SCSS is helpful for this (which also comes with additional benefits).
    
3. The styles in your stylesheet are too specific. When your content is displayed on the live site, it is almost always displayed in a different context - such as in <div class="container"> or some other HTML construct. If your site styles are prefixed with that context (eg: ".container p { font-family: ... }") then the styles will not match in the WYSIWYG editor.

Adding Classes to the Editor

Now that the stylesheet is included in the editor, wouldn't it be helpful if users could apply classes from the stylesheet to their content? Thanks to some fancy fake styles, they can!

Rule #1

The first rule you have to follow when writing styles for the editor is that it will only include styles with a SINGLE classname, optionally prefixed by a tag type. For example, the following will work:

.button{ ... }

a.button{ ... } 

The following WILL NOT work because they are too specific:

.container .button { ... }

#main .button { ... }

div a.button { ... }

.button, a.button { ... }

Rule #2

The second rule you have to follow when writing styles for the editor is that, if desired, the FIRST style after your selector should be the "-style-elements" (alternatively "-mp-elements") rule. Yes, we know that this is NOT a valid CSS style. All that means is that the browser will ignore it, but the editor will not. If present, the value for the -style-elements style should be a comma-separated string identifying elements that the style may be applied to (or * for all).

a.button {
  -style-elements: a;
}

If the classname is prefixed by an element, it will be applicable to that element in addition to any elements specified by -style-elements. If the classname is not prefixed by an element and there is no -style-elements rule, the style will be applicable to all elements.

Rule #3

The third rule when writing styles for the editor is that the SECOND style after your selector MUST be "-style-title" (alternative "-mp-title"). This is the text that will be displayed in the HTML editor for the user to select. Classes in the stylesheet without the -mp-title style will not be stripped by the editor but will not be able to be applied through the HTML interface.

a.button {
  -style-elements: a;
  -style-title: 'Anchor Button';
}

Examples

.orange { 
  -style-title: 'Orange Text'; 
  color: orange; 
}

.clear { 
  -style-elements: 'p,img,table'; 
  -style-title: 'Clear Floated Elements'; 
  clear: both; 
}

a.button { 
  -style-elements: 'button'; 
  -style-title: 'Gray Button'; 
  display: inline-block; 
  padding: 5px 10px; 
  background: #999; 
  color: #FFF; 
  border: 2px solid #444; 
  border-radius: 3px; 
  box-shadow: 2px 2px 3px rgba(0,0,0,0.5); 
}