189 lines
8.7 KiB
Markdown
189 lines
8.7 KiB
Markdown
# CKEditor for ProcessWire
|
|
|
|
[CKEditor](http://ckeditor.com/) is a web text editor like TinyMCE.
|
|
This module can be used anywhere TinyMCE can be used in ProcessWire.
|
|
|
|
CKEditor has a nice *inline* mode that is desirable in the page editor
|
|
when you may have lots of rich text inputs. The reason for this is
|
|
that the page editor loads a lot faster. Some people also prefer
|
|
CKEditor for other reasons.
|
|
|
|
This module is tested and confirmed compatible with both repeaters and
|
|
multi-language support.
|
|
|
|
1. Go to **Setup > Fields** and locate a textarea field that you want
|
|
to use CKEditor (or create a new textarea field).
|
|
|
|
2. When editing the settings for a textarea field, click the **Details** tab.
|
|
Change the **Inputfield Type** to **CKEditor** and save.
|
|
|
|
3. While still editing the field settings, click to the **Input** tab for
|
|
CKEditor-specific settings you may optionally configure.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
### Inline Mode vs. Regular Mode
|
|
|
|
When configuring your CKEditor fields, you may notice the option of either Regular
|
|
Mode or Inline Mode.
|
|
|
|
#### When you should use inline mode
|
|
|
|
The Inline Mode is new to CKEditor 4.x and is preferable if
|
|
you need to have several instances of CKEditor on the same page at once. Inline
|
|
mode editors are not initialized until hovered, making the initial page load time
|
|
faster (at least versus several Regular Mode editors). Another benefit of inline
|
|
mode is that the editor interface and buttons are not visible until the field is
|
|
focused, which some may prefer visually. Another aspect of inline mode worth
|
|
noting is that the editor area is always as tall as the content it contains...
|
|
this may be good or bad, depending on your preferences. We recommend using
|
|
inline mode in these instances:
|
|
|
|
- Multi-language textarea fields
|
|
- Textarea fields in repeaters
|
|
- Any instance where you have multiple (3+) CKEditor textarea fields
|
|
in the same page editor.
|
|
|
|
|
|
#### When you should use regular mode
|
|
|
|
If you only have one or two instances of CKEditor on a page, you may prefer to
|
|
use Regular Mode because it has been around longer and tends to be more reliable.
|
|
Regular Mode runs in a separate frame, making it more isolated and thus less prone
|
|
to any other CSS or Javascript interference. Regular mode editors are also more
|
|
obviously rich text editors, as their interface and buttons are always visible.
|
|
We recommend using Regular Mode in these instances:
|
|
|
|
- Page editors with only 1-2 CKEditor textarea fields (like `body` and `sidebar`).
|
|
- When you do not want CKEditor to consume too much vertical real estate on the editor page.
|
|
- When you want the greatest amount of compatibility with other CKEditor plugins.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
## Advanced Tips
|
|
|
|
This section contains contextual instructions that are linked to from
|
|
within the module. These cover specific needs during field configuration
|
|
and you do not need to read this section in order to use CKEditor.
|
|
|
|
|
|
### Custom Editor JS Styles Set
|
|
|
|
**This is an option that appears in your CKEditor field settings when editing
|
|
a textarea field in the ProcessWire field editor. Use this option if you
|
|
want to have a *Styles* dropdown that contains your own custom styles that
|
|
users can choose from your editor.**
|
|
|
|
#### Instructions
|
|
|
|
1. Edit your CKEditor field in **Setup > Fields**, and click to the **Input** tab.
|
|
|
|
2. In the **CKEditor Toolbar** field, enter `Styles` somewhere. Here is an example
|
|
of what my first toolbar line looks like:
|
|
`Format, Styles, Bold, Italic, -, RemoveFormat`
|
|
|
|
3. Open the **Custom Editor JS Styles Set** field, and type or paste in:
|
|
`mystyles:/site/modules/InputfieldCKEditor/mystyles.js`
|
|
|
|
- ProcessWire's default profile comes with a
|
|
[ready-to-go mystyles.js](https://github.com/processwire/processwire/blob/master/site-default/modules/InputfieldCKEditor/mystyles.js)
|
|
in the exact location mentioned above. Feel free to use this.
|
|
|
|
- The term **mystyles** is just something we made up, and you
|
|
may use whatever keyword you like, but note you will have to use that same
|
|
keyword in the file itself. In our example below, you will see where we
|
|
used the term **mystyles** again. If you want to keep things simple, then
|
|
just stick with using mystyles.
|
|
|
|
- If you don't have a mystyles.js file in /site/modules/InputfieldCKEditor/,
|
|
then you can copy the one in /wire/modules/Inputfield/InputfieldCKEditor/
|
|
to /site/modules/InputfieldCKEditor/mystyles.js.
|
|
|
|
4. Edit and modify the mystyles.js file to suit your particular
|
|
needs. Save and you are done.
|
|
|
|
When editing a page that uses your CKEditor field, you should now see a
|
|
**Styles** dropdown with the styles you specified in your `mystyles.js` file.
|
|
Note that you may not initially see all styles in the dropdown, as they may
|
|
be contextual. For instance, you will not see the styles related to images in the
|
|
example above unless you are focused on an `img` element in your editor.
|
|
|
|
You may wish to combine your settings here with a custom editor CSS file
|
|
covered in the section below.
|
|
|
|
[Read more about the CKEditor styles set option](http://docs.ckeditor.com/#!/api/CKEDITOR.config-cfg-stylesSet).
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
### Custom Editor CSS File
|
|
|
|
**This option enables you to modify the way that text and other elements
|
|
appear in your editor. This covers how they look in the administrative
|
|
environment only, and has nothing to do with the front-end of your site.
|
|
Typically you would use this option if you wanted to modify the default
|
|
look-and-feel in the editor to something that is more stylistically
|
|
similar to the front-end of your site.**
|
|
|
|
Example editor CSS files can be found here:
|
|
|
|
- **Regular Mode:** /site/modules/InputfieldCKEditor/contents.css
|
|
- **Inline Mode:** /site/modules/InputfieldCKEditor/contents-inline.css
|
|
|
|
You can use this files directory, or you can copy them somewhere else.
|
|
However, since they are located in your /site/ directory, they won't
|
|
get overwritten during upgrades. For the same reason, it's also possible
|
|
that you don't have those files in the location mentioned above. If
|
|
that's the case, you can copy the versions in /wire/modules/Inputfield/InputfieldCKEditor/
|
|
instead, and I recommend putting them in /site/modules/InputfieldCKEditor/.
|
|
|
|
*There is also a Sass (SCSS) file called `contents-inline.scss` which you
|
|
may prefer to use as your starting point if using Sass. Just remember to
|
|
compile it to a contents-inline.css file when done. The Sass file is located
|
|
here: /wire/modules/Inputfield/InputfieldCKEditor/contents-inline.scss*
|
|
|
|
As you can see above, you will be using a different CSS file depending
|
|
on whether you need to modify the styles in a regular editor, or an
|
|
inline-mode editor.
|
|
|
|
1. Modify the file(s) mentioned above and style the elements as you wish,
|
|
or you may return to this step later. If using more than one CKEditor
|
|
inline editor in your page, please see the important note below these
|
|
instructions.
|
|
|
|
3. Edit your textarea field that uses CKEditor in **Setup > Fields > your_field**.
|
|
Go to the **Input** tab and see the **Custom Editor CSS File** option. Type
|
|
or paste in the location of the file you copied in step 1 (relative
|
|
to web root). Example: `/site/modules/InputfieldCKEditor/contents.css`. Save.
|
|
|
|
4. Your editor should now be using your new `contents.css` or
|
|
`contents-inline.css` file rather than the defaults. Note that sometimes it
|
|
can be difficult to see the results of your new file immediately,
|
|
especially in regular mode, due to browser caching. If you run into trouble,
|
|
quit your browser and re-open (or use Incognito mode).
|
|
|
|
#### Important Note About Inline Mode (contents-inline.css)
|
|
|
|
If using more than one CKEditor inline mode editor on your page, and
|
|
not using the same `contents-inline.css` file on all of them, then you
|
|
will end up having them compete with each other or fall back to the
|
|
default `contents-inline.css`. In order to avoid this, you would need
|
|
to make your CSS selectors more specific to the field they apply to.
|
|
|
|
Lets say that you had a field named `body`. You could target it specifically
|
|
in your `contents-inline.css` (or whatever you named the file), by replacing
|
|
this CSS selector...
|
|
```
|
|
.InputfieldForm .InputfieldCKEditorInline
|
|
```
|
|
...with this CSS selector:
|
|
```
|
|
.InputfieldForm .Inputfield_body .InputfieldCKEditorInline
|
|
```
|
|
Note the `.Inputfield_body` part, as `body` is the name of the field
|
|
in ProcessWire.
|
|
|
|
If you will use the same `contents-inline.css` file for all of your
|
|
inline fields, then just make sure it is specified with the settings for
|
|
each of your CKEditor inline textarea fields, otherwise you may end up
|
|
reverting back to the default `contents-inline.css`.
|
|
|