How to create rich text editor snippets

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

Rich text editor snippets are text placeholders. They are added to your content and then replaced with other information when the editor is saved. Examples of this are Page Name and Page User. Both are default snippets that are part of Concrete CMS: Page Name will be replaced with the current name of the page and Page User will be the name of the current user. The information that replaces the text placeholder can be almost anything, like system information, page information, user information, and even HTML.

This is where the snippets are in the editor toolbars:

Redactor

CKEditor

This is what the snippets look like when they've been added to your content (before replacement):

Here is an example of what the HTML for a snippet placeholder looks like:

<span class="ccm-content-editor-snippet" data-scshandle="page_name">Page Name</span>

Creating a package to add a snippet

First let's create the package folder structure and files. The package name will be "Editor Snippet" and the package handle will be "editor_snippet".

Folders

  • packages\editor_snippet
  • packages\editor_snippet\src
  • packages\editor_snippet\src\Concrete
  • packages\editor_snippet\src\Concrete\Editor

Files

  • packages\editor_snippet\controller.php
  • packages\editor_snippet\src\Concrete\Editor\TestSnippet.php

Now we need to add the package controller code to controller.php.

<?php
namespace Concrete\Package\EditorSnippet;

use Concrete\Core\Editor\Snippet;
use Package;

class Controller extends Package
{
    protected $pkgHandle = 'editor_snippet';
    protected $appVersionRequired = '5.7.5';
    protected $pkgVersion = '0.9';
    protected $pkgAutoloaderMapCoreExtensions = true;

    public function getPackageName()
    {
        return t('Editor Snippet');
    }

    public function getPackageDescription()
    {
        return t('Add a snippet to the rich text editor.');
    }

    public function install()
    {
        $pkg = parent::install();

        $snippet = Snippet::add('test', 'Test Snippet', $pkg);
        $snippet->activate();
    }
}

In the package controller install() method we use Snippet::add() to add the snippet. What this does is add an entry into the SystemContentEditorSnippets table for the snippet. The arguments for add() are the snippet handle, the snippet placeholder text, and an instance of the package object. The snippet handle will be the snippet class name, minus the word "Snippet", in lowercase, and each word separated with an underscore. If the snippet class was "PageNameSnippet", the snippet handle would be "page_name". After the snippet has been added, it needs to be activated using activate().

Now that we have a package controller, let's create a snippet in TestSnippet.php.

<?php
namespace Concrete\Package\EditorSnippet\Editor;

use Concrete\Core\Editor\Snippet;

class TestSnippet extends Snippet
{
    public function replace()
    {
        return 'test snippet text';
    }
}

Whatever is returned by the replace() method will be the replacement for the snippet placeholder. TestSnippet is going to return a simple string "test snippet text".

After installing our new Editor Snippet package, we will see a new snippet called "Test Snippet" in the snippets drop-down. When it is added into your content the placeholder will be "Test Snippet" and the replaced text will be "test snippet text".

Here is a GitHub repo for the Editor Snippet package example. https://github.com/MrKarlDilkington/editor_snippet

Adding multiple snippets in a package

Bundling multiple snippets together in a single package uses the same steps as creating a single snippet, except that you will be adding multiple snippet files and using slightly different PHP to add and activate them.

In your package controller, instead of adding and activating the snippet in two steps, you can use method chaining to do it in one step. In some situations, method chaining can be useful to condense code down to fewer lines and make it more readable (excessive method chaining can make code harder to read).

Example: adding and activating multiple snippets

Snippet::add('page_added', 'Page Added', $pkg)->activate();
Snippet::add('page_author_name', 'Page Author Name', $pkg)->activate();
Snippet::add('page_modified_author_name', 'Page Modified Author Name', $pkg)->activate();
Snippet::add('page_modified', 'Page Modified', $pkg)->activate();
Snippet::add('page_type_name', 'Page Type Name', $pkg)->activate();
Snippet::add('parent_page_name', 'Parent Page Name', $pkg)->activate();

Here is a GitHub repo for a Multiple Editor Snippets package example. It adds 6 snippets (3 are courtesy of community member hissy). https://github.com/MrKarlDilkington/multiple_editor_snippets

Recent Tutorials
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

WebOps Tutorial on Running and Upgrading a Concrete CMS Website
May 2, 2024
By myq.

Describes how to deploy, manage, and upgrade a Concrete CMS website

Improvements?

Let us know by posting here.