Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix docs for the editor's read-only mode management #11611

Merged
merged 4 commits into from
Apr 11, 2022
Merged

Fix docs for the editor's read-only mode management #11611

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f5abe75
Improved docs for the read-only guide.
ma2ciek Apr 11, 2022
30ab33b
Fixed docs.
ma2ciek Apr 11, 2022
7ff4a05
Update docs/features/read-only.md
scofalik Apr 11, 2022
f26df72
Apply suggestions from code review
scofalik Apr 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions docs/features/read-only.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,14 @@ modified_at: 2021-11-15

{@snippet features/read-only-build}

CKEditor 5 offers an out of the box read-only mode. The feature does not require any additional plugin and the editor can be set into a read-only mode simply by changing the value of the {@link module:core/editor/editor~Editor#isReadOnly `Editor#isReadOnly`} property.
CKEditor 5 offers an out of the box read-only mode. The feature does not require any additional plugin and the editor can be set into a read-only mode using the editor's {@link module:core/editor/editor~Editor#enableReadOnlyMode `Editor#enableReadOnlyMode()`} method.

The read-only mode may have several applications. It may be used to impose user-based access restriction, where a selected user or a group of users is only allowed to access the content for evaluation purposes but not change it.

The feature may also be used to view content that should not be edited, like financial reports, software logs or reprinted stories. While not editable, this content will still be accessible for copying or for screen readers.

Editor can be switched to or out of the read-only mode by many features, under various circumstances. The editor supports locking mechanism for the read-only mode. It enables easy control over the read-only mode when many features wants to turn it on or off at the same time, without conflicting with each other. It guarantees that you will not make the editor content editable by an accident (which could lead to errors).

<info-box>
See also the {@link features/restricted-editing restricted editing feature} that lets you define which parts of a document can be editable for a group of users with limited editing rights, leaving the rest of the content non-editable to them. You can also read the [dedicated blog post](https://ckeditor.com/blog/feature-of-the-month-restricted-editing-modes/) about write-restricted editor modes.
</info-box>
Expand All @@ -27,6 +29,14 @@ Use the demo below to toggle between editing modes and test the feature. Some fe
You can see that after switching to read-only mode, some of the toolbar items are still active and functional. It happens thanks to the {@link module:core/command~Command#affectsData `affectsData` property}. For most of the plugins, it is set to `true` by default, which makes them inactive when entering read-only mode. However, for those plugins that do not make any changes in the model &ndash; do not affect the content &ndash; it is set to `false`, thus allowing to still make use of them in modes with restricted user write permissions.
</info-box>

### API

The editor provides the following API to manage the read-only mode:

* {@link module:core/editor/editor~Editor#isReadOnly} is a read-only, observable property that allows you to check the `isReadOnly` value and react to its changes,
* {@link module:core/editor/editor~Editor#enableReadOnlyMode `Editor#enableReadOnlyMode( featureId )`} Turns on the read-only mode on the editor by creating a lock with given unique id.
* {@link module:core/editor/editor~Editor#disableReadOnlyMode `Editor#disableReadOnlyMode( featureId )`} removes the read-only lock from the editor. The editor becomes editable when no lock is present on the editor anymore.

## Hiding toolbar in read-only mode

Some use cases might require hiding the editor toolbar when entering the read-only mode. This can be achieved easily with the following code:
Expand All @@ -52,7 +62,7 @@ ClassicEditor
} );
```

When the button is clicked, the property `editor.isReadOnly` is set to `true`. This triggers the code showed above, which in turn hides the toolbar using CSS styles. After clicking the button once more and setting `editor.isReadOnly` to `false`, the toolbar is visible again. This approach will work both for classic and decoupled editors.
When the button is clicked, the `editor.enableReadOnlyMode()` creates a lock that sets the read-only mode on the editor. This triggers the code showed above, which in turn hides the toolbar using CSS styles. After clicking the button once more, the `editor.disableReadOnlyMode()` is called, which removes the read-only lock and the editor's and the toolbar is visible again. This approach will work both for classic and decoupled editors.

Use the demo below to see this code in action, toggle read-only mode together with the editor's toolbar with the dedicated button.

Expand Down