Adding Redactor custom styles in a theme (content block/rich text editor)

This is a community-contributed tutorial. This tutorial is over a year old and may not apply to your version of Concrete CMS.
Apr 2, 2015

Custom styles work on a theme by theme basis.

1. You start by creating page_theme.php in your theme folder.

2. Add the namespacing and extend the Theme class.

Namespacing for a theme in application

namespace Application\Theme\Your_Theme_Name;
class PageTheme extends \Concrete\Core\Page\Theme\Theme 
{
    //...
}

Namespacing for a theme in a package

namespace Concrete\Package\Your_Package_Name\Theme\Your_Theme_Name;
class PageTheme extends \Concrete\Core\Page\Theme\Theme 
{
    //...
}

3. Add the getThemeEditorClasses() method.

public function getThemeEditorClasses()
{
    //...
}

4. Add an array with the custom style names and classes you want Redactor to use.

As an example, these are the arrays that come with the Elemental theme
"concrete\themes\elemental\page_theme.php"

public function getThemeEditorClasses()
{
    return array(
        array('title' => t('Title Thin'), 'menuClass' => 'title-thin', 'spanClass' => 'title-thin'),
        array('title' => t('Title Caps Bold'), 'menuClass' => 'title-caps-bold', 'spanClass' => 'title-caps-bold'),
        array('title' => t('Title Caps'), 'menuClass' => 'title-caps', 'spanClass' => 'title-caps'),
        array('title' => t('Image Caption'), 'menuClass' => 'image-caption', 'spanClass' => 'image-caption'),
        array('title' => t('Standard Button'), 'menuClass' => '', 'spanClass' => 'btn btn-default'),
        array('title' => t('Success Button'), 'menuClass' => '', 'spanClass' => 'btn btn-success'),
        array('title' => t('Primary Button'), 'menuClass' => '', 'spanClass' => 'btn btn-primary')
    );
}

5. getThemeEditorClasses() array keys

  • title - is the name that will be displayed in the custom styles dropdown in Redactor
  • menuClass - will be the class/classes applied to the dropdown title text (this makes the title text a preview of the style)
  • spanClass - will be the class/classes you want applied for that custom style (the classes applied to the selected text).

As an example, here I added a custom pina colada button that changes the text color and background along with a pina colada picture.

public function getThemeEditorClasses()
{
    return array(
        array('title' => t('Title Thin'), 'menuClass' => 'title-thin', 'spanClass' => 'title-thin'),
        array('title' => t('Title Caps Bold'), 'menuClass' => 'title-caps-bold', 'spanClass' => 'title-caps-bold'),
        array('title' => t('Title Caps'), 'menuClass' => 'title-caps', 'spanClass' => 'title-caps'),
        array('title' => t('Image Caption'), 'menuClass' => 'image-caption', 'spanClass' => 'image-caption'),
        array('title' => t('Standard Button'), 'menuClass' => '', 'spanClass' => 'btn btn-default'),
        array('title' => t('Success Button'), 'menuClass' => '', 'spanClass' => 'btn btn-success'),
        array('title' => t('Primary Button'), 'menuClass' => '', 'spanClass' => 'btn btn-primary'),
        array('title' => t('Pina Colada Button'), 'menuClass' => '', 'spanClass' => 'pina-colada')
    );
}

default Elemental custom styles

alt text

new Pina Colada Button style

alt text

new style applied

alt text

Refresh the theme when adding a page_theme.php to an existing theme or if settings in page_theme.php are not being applied

Dashboard > Pages & Themes > Themes
1. activate the default Elemental theme
2. remove the custom theme
3. install the custom theme
4. activate the custom theme

Writing custom style CSS that will display in the Custom Styles preview

It is a best practice to scope theme CSS with the .ccm-page class. This helps prevent theme CSS from overriding the CSS of the Concrete CMS interface. Scoping CSS this way, using .ccm-page or another class, will prevent custom style title previews from displaying. This can be addresed by creating a second selector for your custom style using #redactor-dropdown-holder.

Example:

#redactor-dropdown-holder .your-style-name,
.ccm-page .your-style-name {
    /*...*/
}

New in Concrete 5.7.5+

When defining custom styles, there is now the option to make the style inline or block. An inline style will wrap the selected text in a span tag and then apply the the custom style to the span. A block style will apply the custom style directly on the block level element tag of the selected text (examples of block level elements are p, h1-h6, etc.).

What makes a custom style inline or block is determined by a new getThemeEditorClasses() array key called "forceBlock". A 'forceBlock' value of -1 will make the style inline and a value of 1 will make the style block.

Example: the Elemental theme default styles

public function getThemeEditorClasses()
{
    return array(
        array('title' => t('Title Thin'), 'menuClass' => 'title-thin', 'spanClass' => 'title-thin', 'forceBlock' => 1),
        array('title' => t('Title Caps Bold'), 'menuClass' => 'title-caps-bold', 'spanClass' => 'title-caps-bold', 'forceBlock' => 1),
        array('title' => t('Title Caps'), 'menuClass' => 'title-caps', 'spanClass' => 'title-caps', 'forceBlock' => 1),
        array('title' => t('Image Caption'), 'menuClass' => 'image-caption', 'spanClass' => 'image-caption', 'forceBlock' => '-1'),
        array('title' => t('Standard Button'), 'menuClass' => '', 'spanClass' => 'btn btn-default', 'forceBlock' => '-1'),
        array('title' => t('Success Button'), 'menuClass' => '', 'spanClass' => 'btn btn-success', 'forceBlock' => '-1'),
        array('title' => t('Primary Button'), 'menuClass' => '', 'spanClass' => 'btn btn-primary', 'forceBlock' => '-1'),
    );
}

If you create a custom style that you want to use both as an inline style and a block style, then you can define the custom style twice. One approach is to add a "- Inline" or "- Block" suffix to the custom style title.

Example: a custom style used both as inline and block

public function getThemeEditorClasses()
{
    return array(
        array('title' => t('Title Thin - Block'), 'menuClass' => 'title-thin', 'spanClass' => 'title-thin', 'forceBlock' => 1),
        array('title' => t('Title Thin - Inline'), 'menuClass' => 'title-thin', 'spanClass' => 'title-thin', 'forceBlock' => '-1'),
    );
}
Recent Tutorials
Redirect all requests to HTTPS
Oct 9, 2024
By myq.

How to follow best practices for a secure web

Upgrade Concrete versions 9.3.1 and 9.3.2
Sep 10, 2024
By myq.

How to get past a bug in versions 9.3.1 and 9.3.2 that prevents upgrading the Concrete core through the Dashboard

How to use Composer with Marketplace extensions
Aug 22, 2024

Composer can be used to manage third-party extensions from the marketplace

Controlling Google Tag Manager Tags Based on Concrete CMS Edit Toolbar Visibility
Aug 13, 2024

This document provides a step-by-step guide on how to control the firing of Google Tag Manager (GTM) tags based on the visibility of the Concrete CMS edit toolbar. It explains how to create a custom JavaScript variable in GTM to detect whether the edit toolbar is present on a page and how to set up a trigger that ensures GTM tags only fire when the toolbar is not visible. This setup is particularly useful for developers and marketers who want to ensure that tracking and analytics tags are not activated during content editing sessions, thereby preserving the accuracy of data collected.

Upgrading Concrete from 8.5 to 9.x
Jun 21, 2024
By myq.

How to avoid problems upgrading from 8.5 to 9.x

How to change the default date format
May 30, 2024
By myq.

Change the format of the default date

Improvements?

Let us know by posting here.