Frontend WYSIWYG Editor for Grav CMS
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
css Update Feb 15, 2019
pages Initial release Jan 30, 2019
templates Hide inspector widget Feb 15, 2019
vendor Added to local Feb 7, 2019
.gitignore Initial release Jan 30, 2019
CHANGELOG.md Updated to version 1.4.5 Feb 15, 2019
LICENSE Initial release Jan 30, 2019
README.md Minor textual changes Feb 12, 2019
blueprints.yaml Updated to version 1.4.5 Feb 15, 2019
editable-contenttools.php Optimized shortcode processing Feb 15, 2019
editable-contenttools.yaml Added Git Sync Mode option Feb 7, 2019

README.md

Editable with ContentTools Plugin

The Editable with ContentTools Plugin is for Grav CMS.

The plugin allows authors to edit page content in the frontend using the WYSIWYG editor ContentTools and save it as Markdown.

Important: The plugin works with plain Markdown content from regular Grav pages. In other words, it can not work with content which is processed or inserted dynamically via Twig, shortcodes, through Javascript, by means of a plugin or any other way.

This may limit its use case depending on your requirements.

Please visit the ContentTools website for tips on using the ContentTools editor, like holding down the Shift key for about 3 seconds to see what regions on the page are editable (tip!).


Screenshot of Grav with the ContentTools editor in use


Installation

Typically the plugin should be installed via GPM (Grav Package Manager):

$ bin/gpm install editable-contenttools

Or you can manualy install it by downloading the plugin as a zip file. Copy the zip file to your /user/plugins directory, unzip it there and rename the folder to editable-contenttools.

Before configuring this plugin, you should copy the user/plugins/editable-contenttool/editable-contenttools.yaml to user/config/plugins/editable-contenttools.yaml.

Make configuration changes to that copy so your changes will be kept when installing a new version of the plugin.

Alternatively the plugin can be installed via the Admin Plugin. When using the Admin Plugin there is no need to copy the configuration files manually.

Configuration

Here is the default configuration and an explanation of available options:

enabled: true
git-sync: false
git-sync-mode: foreground

Setting enabled to true enables or activates the plugin.

When git-sync is true and the Git Sync plugin is installed and enabled, every save action triggers a Git Sync synchronisation.

The git-sync-mode setting defaults to foreground where the plugin halts until the synchronisation is finished before control is handed back to the user. When set to background the sync is unobtrusive to the user.

Note: background syncing on Linux systems is not guaranteed to work and has currently not been tested on a Windows server. Feedback is welcome!

Possibly limited use case

This plugin works on plain simple Markdown only. This limits the use case but is a consequence of the conversion of Markdown to HTML and back again.

Just to set expectations right please note that this plugin will not work on a page or on content which:

  • is processed by a Twig template, for example modulars
  • is injected by plugins, for example the Page Inject Plugin
  • is altered in the browser through Javascript

and will corrupt special Grav Markdown tags such as:

![Sample Image](sample-image.jpg?lightbox=600,400&resize=200,200)

Mitigating problems

There are some simple rules to keep on the safe side:

  • Keep images and other shortcodes outside your editable regions
  • Create small editable regions; it does not matter how many
  • Experiment and test to make sure it works for you and you don't lose valuable content
  • When you notice a difference in markup of the page with the ContentTools pen icon present and without keep that part of the page outside of your editable regions, it means trouble is ahead ;)

The shortcode [editable]

Page content that may be edited in the frontend should be marked by using the shortcode [editable].

For example:

[editable]
# Chapter 1

Once upon a time ...
[/editable]

A page may contain any number of such editable regions.

Shortcode name parameter (optional)

For the ContentTools editor to work every editable region in a page must be uniquely identified by a 'name' parameter. Optionally you can give each shortcode a name which must be unique within the page.

The name parameter is optional. When non or an empty shortcode name parameter is present the plugin assigns names like "region-x" where x is a sequential increasing number.

For example:

[editable name="region-0"]
Once upon a time ...
[/editable]

To be able to save changed content back into the right regions the names need to be present in the page content and are therefor automatically saved in the page.

User Permissions

Frontend Users

To enable users to edit content in the frontend they must be able to login.

Access to the frontend requires a seperate login as documented in the Grav Login plugin or the Private Grav Plugin.

To edit a page a frontend user must have the permission site.editable. Add the required authorization to each user in the user's account file:

access:
  site:
    login: 'true'
    editable: 'true'

Backend Users

By default Grav separates backend (Admin) and frontend users into separate sessions.
Allowing backend users to edit pages in the frontend requires the Grav option session.split to be set to false (in system.yaml or in the Admin panel).

A backend or Admin user must have the permission admin.super or admin.pages to be allowed to edit a page.

Credits

Thanks go to:

To Do's

[ ] Add file upload
[ ] Add superscript and subscript tools
[ ] Think about handling images

BTW all the above to do's require custom ContentTools tools and I don't have a clue how to create one...