How to create rich text editor snippets

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
Generate a report with author information and form summaries in Concrete CMS.
May 9, 2022

In Concrete CMS, you can use a form to initiate contact between logged-in users and then create helpful reports. After form submissions are collected, they can be searched, sorted, and exported as a spreadsheet. This tutorial will detail how to add author information to a report using the advanced search.

How to clone and customize Atomik theme
Feb 14, 2022
By linuxoid.

How to clone and customize Atomik theme

Update jQuery to 3.5 on Concrete CMS version 8.5.x
Dec 1, 2021
By hissy.

If you have to take some time to fix your site to work with version 9 and want to update jQuery immediately, you can override it.

Add-On Developers: Get Your Add-Ons Ready for Concrete CMS 9.0
Aug 6, 2021
By andrew.

Concrete CMS 9.0 is coming! But there are some changes in version 9 that might affected your add-ons and themes. This document aims to answer questions about the most common ways that your add-ons might need to be changed, and common problems you'll run into.

Permissions for editors in a multilingual site
Jun 2, 2021
By myq.

How to set up a multilingual Concrete CMS site for groups of language-specific editors

Getting Started with Doctrine in Concrete CMS
Jan 20, 2021
By linuxoid.

Doctrine is a very flexible, simple (once you get to know it better) and powerful PHP library for database interactions primarily focused on the ORM = Object Relational Mapping and DBAL = DataBase Abstraction Layer.

Was this information useful?
Thank you for your feedback.