artabro/wire/modules/Inputfield/InputfieldCKEditor/README.md

# 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`.