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
Using the Concrete Migration Tool Addon
Apr 27, 2023

How to use the Concrete CMS Migration Tool

How To Add Page Last Updated To Your Concrete CMS Pages
Mar 7, 2023

Concrete CMS has a page attribute you can add to a global area called "Page Date Modified." Here's how to add it

How To Exclude Subpages from Navigation
Dec 24, 2022

How to exclude subpages from navigation - useful for a news or blog link in your main navigation where you don't want all the subpages to appear in a drop down menu.

How Can I Change The Maximum Size Of Uploaded files
Dec 13, 2022

This tutorial explains how to update your php settings.

Updating Concrete Themes from Version 8 to Version 9
Nov 24, 2022

This tutorial covers commonly encountered issues when upgrading a Concrete CMS theme from version 8 to version 9

Transferring ownership of an add-on and a theme
Nov 15, 2022
By katzueno.

If you encounter a Concrete CMS add-on or theme that you love but not being maintained, you may want to ask the author to help or take over the add-on or theme. Here is the quick step-by-step guide of how to transfer the ownership.

Was this information useful?
Thank you for your feedback.