How to create rich text editor snippets

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