Restricted editing

The restricted editing feature introduces two modes: the standard editing mode and the restricted editing mode. Users working in the restricted editing mode cannot change the content, except for parts marked as editable.

# Demo

The demo below lets you emulate both the standard editing mode and the restricted editing mode.

Start by creating a template of the document in the standard editing mode. Select a section of the text and use the enable editing toolbar button to turn a selected area into an editable region or remove an existing one.

Then switch to the restricted editing mode to see how the editable and non-editable regions behave.

# Additional feature information

The restricted editing feature enables two editing modes:

• Standard editing mode – In this mode the user can edit the content and choose regions that should be editable in the restricted editing mode.
• Restricted editing mode – When you initialize the editor in this mode, the user can edit the content only within the regions chosen by the user in the standard editing mode.

You can imagine a workflow where a certain group of users is responsible for creating templates of documents. At the same time, a second group of users can only fill the gaps (for example, fill in the missing data, like names, dates, product names, etc.).

By using this feature, the users of your application will be able to create template documents. In a certain way, you can use this feature to generate forms with rich-text capabilities. This kind of practical application is shown in the How to create ready-to-print documents with CKEditor 5 pagination feature blog post.

# Configuration

You can configure which features should be available in the restricted mode. For instance, the following configuration allows the users to type, delete but also to bold text.

import { RestrictedEditingMode } from '@ckeditor/ckeditor5-restricted-editing';
import { Bold } from '@ckeditor/ckeditor5-basic-styles';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Bold, RestrictedEditingMode, /* ... */ ],
        toolbar: [ 'bold', '|', 'restrictedEditing', /* ... */ ],
        restrictedEditing: {
            allowedCommands: [ 'bold' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

Note: Typing and deleting text is always possible in restricted editing regions. For more information, check out the config.restrictedEditing documentation.

# Enabling commands in the restricted editing mode

The restricted editing mode allows modifying the editor content only in designated regions. Outside these regions, most of the editor commands are turned off by default. If you wish to enable some commands outside the restricted editing regions, you can use the RestrictedEditingModeEditing.enableCommand() method. You must execute this method in the afterInit() callback of an editor plugin.

import { Plugin } from '@ckeditor/ckeditor5-core';

class MyPlugin extends Plugin {
    afterInit() {
        this.editor.plugins.get( 'RestrictedEditingModeEditing' ).enableCommand( 'myCommand' );
    }
}

# Installation

To add this feature to your rich-text editor, install the @ckeditor/ckeditor5-restricted-editing package:

npm install --save @ckeditor/ckeditor5-restricted-editing

# Running the standard editing mode

To initialize the editor in the standard editing mode, add the StandardEditingMode plugin and add the 'restrictedEditingException' button to the toolbar:

import { StandardEditingMode } from '@ckeditor/ckeditor5-restricted-editing';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ StandardEditingMode, /* ... */ ],
        toolbar: [ 'restrictedEditingException', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Running the restricted editing mode

To initialize the editor in the restricted editing mode, add the RestrictedEditingMode plugin and add the 'restrictedEditing' button to the toolbar:

import { RestrictedEditingMode } from '@ckeditor/ckeditor5-restricted-editing';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ RestrictedEditingMode, /* ... */ ],
        toolbar: [ 'restrictedEditing', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Related features

CKEditor 5 has more features that help you control user permissions:

• Read-only – Turn the entire content of the editor read-only.
• Track changes – Mark user changes in the content and show them as suggestions in the sidebar for acceptance or rejection.
• Comments – Users can add comments to any part of the content instead of editing it directly.

# Common API

The StandardEditingMode plugin registers:

• The 'restrictedEditingException' button that lets you mark regions as editable.
• The 'restrictedEditingException' command that allows marking regions as editable.

The RestrictedEditingMode plugin registers:

• The 'restrictedEditing' dropdown that lets you navigate between editable regions.
• The 'goToPreviousRestrictedEditingException' and 'goToNextRestrictedEditingException' commands that allow navigating between editable regions.

# Real-time collaboration

When using real-time collaboration, all the connected users should always be in the same mode. You cannot have a different list of plugins enabled among users of a single collaborative session.

# Contribute

The source code of the feature is available on GitHub at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-restricted-editing.