Menu

Umbraco Rich Text styles another way.

In Umbraco the common way to add styles to the Format drop down in an RTE (Rich Text Editor) is to use the Umbraco back office. You go to the settings section and under style sheets you create an entry. You then create additional nodes to that represent these entries.

Now, I'm not here to talk about those. There are detailed articles and tutorials discussing this so there is no need for me to explain it again. However if you are interested in this approach here are two great links to get you started:

There is another way.

If you aren't already aware, the RTE is actually TinyMCE, and it has its own dedicated config file. This config file is pretty powerful. By default it governs things such as what elements are allowed, what buttons can appear on the tool bar, and what plugins are available.

What you might not know is that you can also use this to add styles to theĀ Format dropdown.

By using the config file approach you gain a few perks. Two of which I think are exceptionally useful. The first, is that it allows you to nest styles under additional drop downs. So lets say you want to group Headings together or group button styles, this is perfectly possible. The second, and possibly one of the most useful, is the ability to add selector rules and classes.

Now I mentioned button styles earlier, but in the web these days it is common to style links to look like buttons, or big flashy call to actions. This can be a bit tricky using the common way of adding styles because we don't always want our links wrapped in P tags or Spans.

Step 1 - The Location

So, how do you add your styles to the config file you might ask?

Well it all starts with the below code block. This XML element needs to be added to theĀ customConfig element within the TinyMCE config file. [/Config/tinyMceConfig.config]

<tinymceConfig>
 .....
    <customConfig>
        <config key="style_formats">
            <!-- Your styles go here -->
        </config>
    </customConfig>
</tinymceConfig>

Step 2 - A basic style

Now we have our entry point, we need to build it out. The contents of our custom styles are JSON. This is important as we are effectively create an array of objects, which when you think about it makes sense.

So, we start by creating an array object and in the first instance we will add a single style. This style will allow us to add the class "blue" to an element. (Basically we are replicating something we could easily do in the Umbraco back office).

<config key="style_formats">
    [{"title": "Blue text", "inline":"span", "classes":"blue"}]
</config>

What this will do is wrap text in a span with blue class. Now this is great, but it's not necessarily the most useful example. But wait, what if we only want the blue class to added to links.

Well, this approach allows us to specify selectors. These selectors are CSS selectors and you can specify multiple different selectors (you might want to allow it on a tags and spans for example.

Step 3 - Selectors

Using the code block below, we've changed our blue class to only allow it to be applied to links. What's great about this is that is actually disables the style in the Formats drop down if you haven't selected text that is contained in valid tags matching the selector(s).

<config key="style_formats">
    [{"title": "Blue text", "selector":"a", "classes":"blue"}]
</config>

Now I could go into large amounts of detail discussing all the different combinations. But instead I'm going to do 3 things:

  1. I'm going to link to you to a great page on the TinyMCE website which talks about custom formats.
  2. I'm going to share an important bit of knowledge, when you make these changes to the XML config, you need to recycle the website by touching the web.config file in order for them to get picked up.
  3. I'm going to leave you with a final example code block.

This final example is a complete example that has nested styles, selectors, inline elements and blocks (things like h1's and p tags). Feel free to add it your website to see what it does.

<config key="style_formats">
    [{"title":"Headers","items":[{"title":"Header 1 (H1)","block":"h1"},{"title":"H1 Lookalike","selector":"p,span","classes":"h1"},{"title":"Header 2 (H2)","block":"h2"},{"title":"H2 Lookalike","selector":"p,span","classes":"h2"},{"title":"Header 3 (H3)","block":"h3"},{"title":"H3 Lookalike","selector":"p,span","classes":"h3"}]},{"title":"Quotes","items":[{"title":"Style A","block":"blockquote","classes":"quote-a"},{"title":"Style B","block":"blockquote","classes":"quote-b"}]},{"title":"Links","items":[{"title":"CTA Loud","selector":"a","classes":"cta cta-loud"},{"title":"CTA Subtle","selector":"a","classes":"cta cta-subtle"},{"title":"Button look-a-like","selector":"a","classes":"btn btn-mimic"}]},{"title":"Inline colours","items":[{"title":"Orange","inline":"span","classes":"orange"},{"title":"Red","inline":"span","classes":"red"},{"title":"Blue","inline":"span","classes":"blue"}]}]
</config>