README.md 5.98 KB
Newer Older
eileen's avatar
eileen committed
1
2
3
4
# ckeditor5

![Screenshot](images/screenshot.png)

5
6
7
8
This adds ckeditor5 as a usable Wysiwig in CiviCRM. Ckeditor5 is being actively developed while CkEditor4 is in LTS stage so it
makes more sense to invest time in ckeditor5 than ckeditor4. However both have gaps.
                                                    
Ckeditor5 is better than
eileen's avatar
eileen committed
9
ckeditor4 when it comes to inserting formatted text from word / google (note
10
11
12
that you no longer see the paste from Word button as you just paste).

Also note ckeditor5 always uses an expandable window so the field will be small if it has
eileen's avatar
eileen committed
13
14
no data.

15
16
17
18
This implementation gets away from  the kcfinder file manager  which was last  updated
in 2014. KcFinder was  brittle around paths - especially  for sites with non-standard layouts
like symlinks or Drupal8.

19
20
21
22
23
24
25
26
27
28
29
30
31
Currently the packaged version comes with 2 options:

* CKEditor5 with uploaded images (recommended) - works in the same way as
  ckeditor4 did, by storing the files on the filesystem. It uses the elfinder
  plugin (eventually we could add support for other storage backends).
* CKEditor5 with embedded images - useful for sites operating behind a firewall
  as it embeds any uploaded images into the html (as a base64 blob), meaning
  that images embedded in emails will not be inaccessible to the recipients.
  For example a user who is sending an email from CiviCRM from behind a firewall
  who wants to add a signature cannot use the traditional ckeditor4 image insert
  because the image will be located behind the firewall and inaccessible to the
  reader. By embedding it it will be available. However, this can have an impact
  on the size of the database.
eileen's avatar
eileen committed
32
33
34

Note - there are discrepancies between email clients and some
might suppress or mis-display embedded images, as some might suppress linked ones.
35

eileen's avatar
eileen committed
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
The extension is licensed under [AGPL-3.0](LICENSE.txt).

## Requirements

* PHP v7.1+
* CiviCRM 5.24+

## Installation (Web UI)

This extension has not yet been published for installation via the web UI.

## Installation (CLI, Zip)

Sysadmins and developers may download the `.zip` file for this extension and
install it with the command-line tool [cv](https://github.com/civicrm/cv).

```bash
cd <extension-dir>
cv dl ckeditor5@https://github.com/FIXME/ckeditor5/archive/master.zip
```

## Installation (CLI, Git)

Sysadmins and developers may clone the [Git](https://en.wikipedia.org/wiki/Git) repo for this extension and
install it with the command-line tool [cv](https://github.com/civicrm/cv).

```bash
git clone https://github.com/FIXME/ckeditor5.git
cv en ckeditor5
```

## Usage

After installation it is  available as an option under
Administer->Customize Data and Screens->Display Preferences

![Screenshot](images/enable.png)

## Known Issues

bgm's avatar
bgm committed
76
- The editor language only works in the ElFinder mode, and is set according to the current CiviCRM language, but Ckeditor5 ships its own set of translations which may not include all CiviCRM languages (see the files in js/ckeditor5/ckeditor-classic-build/translations).
77
78
79
80
81
- some session errors are visible when using elfinder with debug enabled - need to implement a  [session override](https://github.com/Studio-42/elFinder/wiki/Connector-configuration-options-2.1#session-218)
- The file browser for elFinder is in the background when popups are on - but given the
previous item this is OK for now.
- At the moment the elFinder seems to work well for uploading but less so for selecting
previously uploaded files
eileen's avatar
eileen committed
82
83
84
85
86
87
 - a  niche feature of ckeditor4 was a UI for configuration. The toolbar IS configured 
 through a javascript array so it would be  possible to find a way to customise that
 (but there  is  no current plan / demand for this)
- [view source is not a feature in ckeditor5](https://github.com/ckeditor/ckeditor5/issues/592)
- An interesting feature of ckeditor5 is that you can do more Gutenberg-like edit in place.
This would make sense possibly on a contribution page. No current plans.
88
- This uses the es6 script standard which works on browsers from around 2016/17
eileen's avatar
eileen committed
89

eileen's avatar
eileen committed
90
91
## A word about builds

92
CKeditor has a concept of builds constructed with npm. To change some components
eileen's avatar
eileen committed
93
94
95
96
97
98
99
(e.g include base64 uploader) it is necessary to used a build. These can be generated
using the [online builder](https://ckeditor.com/ckeditor-5/online-builder/). Alternatively
the classic editor [can be downloaded & installed](https://ckeditor.com/ckeditor-5/download/).
In the latter case there is no build or src directory or additional files.  So far I have just
downloaded & committed these as they come from the above links.

##  File manager
eileen's avatar
eileen committed
100
101
102
103
104
105
106
107
108

An ongoing challenge with ckeditor4 as implemented with CiviCRM is that the filemanager  (kcfinder)
is pretty hard to work with and requires some hacks to be able to figure out paths.

Ckeditor5 offers the following file managers
- Easy Image & CkFinder -  these  are  not open source
- [Base64 upload](https://ckeditor.com/docs/ckeditor5/latest/features/image-upload/base64-upload-adapter.html)
which is currently packaged & is firewall friendly.
- Integrations. The integration that currently looks most promising is [elFinder](https://github.com/Studio-42/elFinder)
109
This is currently being maintained (as opposed to kcfinder which is not)
eileen's avatar
eileen committed
110
111

Other issues to deal with
112
113
1) Ckeditor works with builds - I am shipping this with one downloaded build
and one created build. Not sure how this is  best managed going forwards.
eileen's avatar
eileen committed
114
115
116
117
118
119
2) We currently need a core fix tweak our settings pages to permit conditional settings based on metadata - ie
only show ckeditor5-specific-settings if $('#editor_id)  = ckeditor5 (this is something)
we also need for invoicing settings).
3) ckeditor builds are generated with npm - it's a bit unclear to me how we deal with that
in extensions (currently committing all the code to the extension). Moving ckeditor4 to a core
extension makes sense but we'd need to figure out this challenge.
120
121
122
123

 Note that I'm currently using the downloaded classic build for elfinder
 as opposed to the lightly customised one I used for the base-uploader
 - this has a slightly different structure -ie no build folder