Smart Snippets

Magnolia Compatibility
5.6
5.7
6.0
6.1

The Smart Snippets module provides a friendly way of managing pieces of content that are reused in multiple places over a website (via CKEditor or Rich text fields), making it easy to update content in a centralized way. Common examples that will benefit from this feature could be a company logo and description, legal statements, some Javascript code (if CKEditor is configured to allow it) or in general, any boilerplate content.

The Smart Snippets app provides interface to create and edit three types of entries:

Text Snippet, a formatted text snippet written in CKEditor, loaded as paragraph,
Inline Snippet, a plain text snippet, loaded in the same line as text surrounding it,
Image Snippet, a snippet that loads an image.

Once an editor places a smart snippet in website content, it can be modified from Smart Snippets content app. It's latest published content will be rendered on all pages where it has been selected. The content app provides as well the usage count of snippets. When editing a smart snippet, in its usage tab links are provided to the pages where the smart snippet is selected.

Author usage

Add one of the three possible types of Smart Snippets, either a rich text, an inline (plain) text or an image,
Edit and save the smart snippet,

(=> a rich text snippet example)
Then, from anywhere in the website or any content app, from every properly configured Rich Text dialog, you can select the newly added or an existing Smart Snippet by clicking on the label button that we introduced:
A selector dialog opens,
Select a Smart Snippet,
Save the dialog with edited Rich Text,
Preview/check the changes on the Author instance,
If all OK, publish both the Smart Snippet(s) AND the page/content item where the Smart Snippet was added to.
Now your snippet is shown on the edited page.

Installation

This module requires Enterprise Edition of Magnolia. The module can be added as a Maven dependency in the main and webapp POM file:

<dependency>
    <groupId>nl.info.magnolia</groupId>
    <artifactId>smart-snippets</artifactId>
    <version>{moduleVersion}</version>
</dependency>

Additionally a dependency from your main module descriptor is necessary:

<dependency>
    <name>smart-snippets</name>
    <version>{1/* | 2/*}</version>
</dependency>

Versions and compatibility table

Compatibility

Module Version	Magnolia Version
2.1.x	6.x
2.0.x	5.7.x
1.0.x	5.6.x

History

Version 2.1.5: Upgrade to JDK11 and Magnolia 6.1.3
Version 2.1.3: Count smart snippets usage also when it's referenced by UUID
Version 2.1.1: minor fix in dependencies
Version 2.1.0: first public release for Magnolia 6.x
Version 2.0.1: Count smart snippets usage also when it's referenced by UUID
Version 2.0.0: first public release for Magnolia 5.7.x
Version 1.0.0: first public release for Magnolia 5.6.x - not supported anymore

Configuration

Module does not have any configurable options, but there are some manual steps that might apply, depending on the environment. All configuration is in app descriptor file (yaml) which can be decorated as any other Magnolia app.

Access to workspace

You might need to setup an ACL for the `smartSnippets` workspace, so that specific roles can read the snippets on rendering.

Magnolia core classes override

Please note that this module overrides `info.magnolia.jcr.util.ContentMap` and `info.magnolia.templating.functions.TemplatingFunctions`

If any of your custom code overrides the same classes, please change your code to override classes from `smartsnippets` package

CKEditor additional configuration

A simple straight forward configuration for CKEditor is provided. You can apply all changes that you want. For CKEditor reference, please visit https://docs.ckeditor.com/

If a custom CKEditor configuration is already provided in the project, Magnolia will not override the toolbar configuration, and therefore there is no way to add Smart Snippets button to CKEditor.

In such a case, the custom CKEditor configuration must be amended in order to enable Smart Snippets. It is suggested to add Smart Snippets to the links toolbar group. The button name to add is 'SmartSnippet':

config.toolbar = [
    { name: 'links', _items: [ 'Link', 'InternalLink', 'DamLink', 'SmartSnippet', 'Unlink' ] }
];

Licensing

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Contributions, questions or findings

Please share your ideas or questions in the comments area on this page.

If you run into a problem, you can report it here: https://jira.magnolia-cms.com/projects/SMSNIPPETS

Page tree