DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:ckgedit

CKGEdit Plugin

Compatible with DokuWiki

  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes
  • 2014-09-29 "Hrun" yes

plugin WYSIWYG editor based on the CKEditor

Last updated on
2017-03-23
Provides
Syntax, Action
Repository
Source
Conflicts with
codemirror, creole, fastwiki, fckg, htmlcomment, mathjax, numberedheadings, quickedit, tagentry, lisps, xbr, yalist

Similar to ckgdoku, fckg

Tagged with editing, editor, wysiwyg

About ckgedit

Ckgedit is a graphical editor for Dokuwiki based on the open source CKEditor. The ckgedit plugin supports the basic dokuwiki feature set; the only thing in ckgedit that is not part of that feature set is font styling, which is implemented by means of a dokuwiki plugin that is given special status in the ckgedit pre-processor.

For features which are not included in the basic feature set, you will need to use Dokuwiki plugins.

Ckgedit is an upgrade from fckg, which uses the older FCKEditor. Much of the documentation for fckgLite applies to ckgedit.

History

The original of ckgedit was called DokuwikiFCK (about 2007) and was based on a Perl parser which converted HTML into wiki markup for a variety of wikis, including Dokuwiki. There was another plugin (fckw) which had already integrated FCKEditor into the browser and was using the Perl back-end. For a while I worked with that.

In the meantime, I came across a javascript HTML parser written by John Resig (creator of jQuery) and realized I could convert html to markup in the browser. That became fckgLite, which is still around and in use, but no longer being maintained. Eventually FCKEditor was upgraded to CKEDitor and fckgLite was replaced by ckgedit.

Changelog

Last 15 commits

A more comprehensive account is included in the Changes file of the distribution. The most comprehensive is on github: https://github.com/turnermm/ckgedit/commits/master

Installation

Requires php 5.3.3 or later. See table of versions for a pre 5.3 alternative.1)

For the basic install use the Dokuwiki Extensions Manager. This should work without incident. If not, then for a manual install, follow this procedure:

  1. Download the tarball, then upload it to your DokuWiki installation under the lib/plugins directory
  2. uncompress the file (e.g. tar -xzvf turn*)
  3. rename the resulting directory to ckgedit
  4. Go to your Extensions Manager interface as an admin user to confirm the plugin was installed correctly; correct any issues noted there.

This version of ckgedit uses the latest release of the CKEDitor (4.5.7). Should you experience any difficulties, you can downgrade to the previous version, which uses CKEditor 4.5.1.

Issues: You can post issues to the forum or to github.

Installing in an IFRAME

File Browser

When the plugin is initally installed, you will get an information message saying that a set of symbolic links have been created. These links point to the Dokuwiki data/media directory from ckgedit/fckeditor/userfiles. It is by means of these links that the file browser accesses the media directory. For a complete discussion of how to handle the security for this set-up, see the instructions on the fckgLite web site.

These links are not needed on a Windows server and in some cases may fail to be created because of windows permissions. However, the .htaccess file in the data directory prevents access to your media directory . Therefore, proper security needs to be set up before you can access media files in the Windows set-up. This is also described in the instructions on how to handle the media directory.

It is possible to use the linux set-up on a windows machine by setting the nix_style configuration option and and the windows set-up on a linux system by setting the winstyle option.

There are extended instructions for using the file browser on the fckgLite web site. See also using_fckeditor_userfiles

Many problems can be solved by using the winstyle configuration option or by using the ckgdoku distribution described below.

ckgdoku

There is a version of ckgedit which enables users to access Dokuwiki's native mediamanager and link wizard as well as the ckgedit filebrowser. It requires dokuwiki version Elenor Of Tsort (2016-06-26) or later.

In its default configuration, users can use either the Dokuwiki tools or the ckgedit filebrowser, switching between them as needed. It can also be configured to restrict users to either ckgedit's filebrowser or Dokuwiki's mediamanager/link wizard.

This has been made possible by the work of Steve Glick, who connected the Ckeditor's link and media dialogs to Dokuwiki's linkwiz and mediamanger.

For adminstrators, this means that the media content of your wikis is now fully integrated into the Dokuwiki file history and meta system, whereas until now it has been only the documents that have had this integration. It also allows for simpler installation when the Dokuwiki tools are given preference, since they work exactly as in Dokuwiki and need no additional configuration. This version is code named ckgdoku.

ckgdoku Configuration Options

There are two options:

Option Description Settings default
allow_ckg_filebrowser Select which file/media browser(s) users can use all, ckgedit, dokuwiki all
default_ckg_filebrowser Select default file/media browser; overridden if the selected browser is not allowed ckgedit, dokuwiki ckgedit

With the default settings the editor will open up set to use ckgedit's file and image browser. A button at the bottom of the editor enables switching to the Dokuwiki media manager and link wizard.

Image sizing and positioning

When selecting an image in the Dokuwiki media manger, if you do not select an option, these settings default to the last selected. They can always be changed in the CKEditor's image dialog. If the image has already been inserted into the document, you can right click on the image and select image properties which will bering up the image dialog, where you can make your changes. When the image is initially inserted only the width will appear in the image dialog. To get the height and to make it permanently a part of your image markup, click the Reset Size icon.

:!: After inserting a screenshot by clipboard, the image size cannot be changed unless the page is saved and re-opened.

Captcha Support

A version of ckgedit with captcha support is avaialbe. It is integrated for use with the captcha plugin and will not work with other captcha plugins. When the captcha plugin's foruser option is set to true, ckgedit makes it possible to set the ACL level for which users will get the captcha.

Support for Farms

See farms below.

Reverse Proxy

When dokuwiki is behind a reverse proxy, the save button does not work out of the box. Solution: inside the dokuwiki configuration set the baseurl setting to the outside url. This fixes all “false” and other problems using this plugin. –Thanks to FrankIJskes (github.com)

Configuration and Set-up

Configuration Settings

See the listing and explanation of configuration options, which have their own page: plugin:ckgedit:configuration. It is worth checking these options so as to configure the editor to your own requirements.

Alternate Save Directory

If you set the savedir option to a directory other than the default, there are two things that must be done:

  1. You must use the nix settings, that is you cannot use the winstyle option if you are on a linux machine, and you must use the nix_style option if you are on a windows machine.
  2. The nix setup requires a set of symbolic links in fckeditor/userfiles which point to the media directory of the savedir directory. The links should automatically be created when ckgedit is installed. If they are not correct, they must be changed. You must make sure that the symbolic links point to your media directory. On linux machine you use the ln -s command to make symbolic links:
 
 ln -s /path/to/savedir/media file
 ln -s /path/to/savedir/media image 
 ln -s /path/to/savedir/media media

On Windows machines you can create links using mklink /D in the command window:

mklink /D "C:\apache\htdocs\dokuwiki\lib\plugins\ckgedit\fckeditor\userfiles\image"  "C:\dokuwiki\data\media"

For more information consult the fckgLite documentation: http://www.mturner.org/fckgLite/doku.php?id=docs:auto_install&#background.

CKEditor Upgrades

The current distribution of ckgedit has been upgraded from CKEditor 4.4.7 to 4.5.7. It had previously been upgraded from 4.01 to 4.2.2 and then to 4.4.3 and 4.5.1. There is also a distribution which uses CKEditor 4.4.5.

Browser and Template Compatibility

  1. IE in Windows XP: you may have to use an earlier distribution with CKEditor 4.01. Or you can try to use a current version and replace ckgedit/ckeditor/ckeditor.js with the ckeditor.js with the 4.01 ckeditor.js, which you can get from Sourceforge: ckeditor.js.4.01.tgz.
  2. Internet Explorer 11: If you are using IE 11 or later, then you must use a version of ckgedit which is based on a version of the CKEditor that is at 4.3 or later. On 11/26/2013, ckgedit was been upgraded to 4.3. If you are using an earlier version and are having trouble with IE, use the above download button.
  3. For more discussion of IE compatibility issues see internet_explorer_compatibility
  4. Debian 6: reloading of pages into the editor fails in the Chrome and Epiphany browsers. But, it succeeds with Ice Weasel (which is the Mozilla-based browser) and in Firefox. The source of this problem is the fact that the default Chrome and Epiphany browsers that come packaged with Debian 6 are far out-of-date. Updating to a recent Chrome will solve this issue in the Chrome browser.
  5. Arctic Template (and maybe others): For some templates the .cke_top{clear:both;} setting in ckgedit/ckeditor/skins/moono/editor_gecko.css has to be uncommented to avoid placement conflicts between the CKEditor toolbar and the template itself. See the readme.md file in that same directory.

Plugin Handling

You enter plugin markup directly into the CKEditor window, just as do in the native Dokuwiki editing window. When the document is saved, the plugin's graphics, if there are any, will display in the browser. When you reload the page into the CKEDitor, the markup is again displayed. So,if you were using the wrap plugin, this is what you might see in the CKEditor:

<WRAP centeralign>
Center aligned text ...
</WRAP>

But in the browser, the text would be displayed as centered. See a more complete example here.

Some Plugins which get additional support

Tags Plugin

There is auto-recognition of the tag plugin. If ckgedit finds an active version of this plugin on your wiki, it will add the tag icon to the CKEditor's toolbar, enabling you to add tags from within the CKEditor's editing window. The plugin for CKEditor which handles this functionality was written by Andreas Valder.

Data Plugin

ckgedit supports the data plugin. Please read the documentation and how-to on the discussion page.

Divalign2 Plugin

In the ckgeditor newlines are replaced by divalNLine macros; the newlines are later restored on saving. The newlines are required by the plugin, i.e. they are part of the plugin syntax. So, for instance, if you enter the following in the Dokuwiki editor:

  ;#;
  This is aligned center.
 ;#;

when loaded into the ckgeditor it becomes:

 divalNLine;#;centerdivalNLine;#;

To achieve the same effect when editing in the ckgeditor, you prepend the divaling2 markup elements with the divaNLine macros, as above.

Multi-Line Plugins

Plugins, like the data plugin, which take up more than a single line, must enclose the plugin syntax between the MULTI_PLUGIN macros:

  ~~MULTI_PLUGIN_OPEN~~
    <Your Plugin Block> 
  ~~MULTI_PLUGIN_CLOSE~~

This preserves the line-breaks.

Geshi example

First create a code or file block, then add the geshi code word, followed by a colon, and the type of code; then, if creating a code snippet, add the file name.

Code

Result

See geshi discussion and view the video.

Removing a Code or File Block

The code drop-down menu has a Remove Block selection. Place you cursor inside the block and select Remove Block; this can also be done with the Normal selection in the Headlines drop-down menu. When you remove a block, the contents of the block remain in place.

Font Styling

A completely revised description of the new font styling features is now on a separate page. 2) If you are using font styling with tables, you must turn on the complex tables parser.

Footnotes

There is a footnote tool. But footnotes can still be created using the native Dokuwiki syntax, text enclosed in double parentheses:((footnote text here)) .

To use the footnote tool, place your cursor where you want your footnote and click the icon with the number 1 on it. A window will open. Enter your note in the text area provided; when finished, click OK. Each note created with the footnote editor will get a unique identifier which will appear as a superscript where the footnote number would normally appear, for instance this: fckgL1. If you want to edit the footnote, click on the footnote icon and enter the identifier in the space provided; click the “Load Note in Editor” button and the note will appear in the text area provided, where you can edit the note; when finished, click OK.

You can create footnotes on the same page using both the footnote tool and the native markup; they will be combined when the page is saved.

You cannot use the footnote editor to edit footnotes that have already been created and saved. The footnote editor is to be used only for initially creating footnotes and for editing them before a save.

After a file has been saved, footnotes are edited in place, in the endnotes area at the bottom of the editing window. If you are section editing, edit the section in which the note appears. The notes will appear at the bottom of the editing window and you can edit them in place. The same is true if you edit the entire page.

To delete a footnote, you must delete the footnote both in the body of the text and in trh endnotes section at the bottom of the editing window.

Nowiki, Code, and File Singletons

When <code>, <nowiki>, and <file> markup occur as singletons, i.e. without their closing tags, they will load into the CKEditor with spaces on either side of the tag-name:

 < nowiki >
 < file >
 < code >

These are removed when the file is saved. To create a singleton, you use the same technique as in the native Dokuwiki editor:

  %%<nowiki>%%
  %%<file>%%
  %%<code>%%

Another singleton is the unmatched %%. This is handled using the <nowiki> tags:

 <nowiki>%%</nowiki>

HTML BLOCKS

Note: This feature requires the htmlok Configuration Option, that is it must to be set to true, and it functions much like htmlok. Feature added 22 Apr 2015.

Ckgedit can copy and save blocks of HTML code and then re-insert them into your document when the editor is re-opened. To save a block of HTML, you place the block between two macros:

~~START_HTML_BLOCK~~
<the block to be saved>
~~CLOSE_HTML_BLOCK~~

It could be useful, for instance, to save a complex table that does not parse correctly, despite use of the complex tables setting. For instance:

You can also use this feature the other way around, that is, you can enter HTML code into the native Dokuwiki editor and place it between the HTML_BLOCK macros. The HTML will be inserted into your document when loaded into the editor. One user, for instance, wanted to insert an imagemap into a page. For example:

~~START_HTML_BLOCK~~
<map name="planetmap">
<area alt="Sun" coords="0,0,82,126" href="sun.htm" shape="rect" />
<area alt="Mercury" coords="90,58,3" href="mercur.htm" shape="circle" /> 
<area alt="Venus" coords="124,58,8" href="venus.htm" shape="circle" />
</map>
~~CLOSE_HTML_BLOCK~~

In this case, when you reload the ckgeditor, you will see only the Start and Close macros, but the html will still be there, as you can see if you use the Source button.

When an HTML Block is processed by the ckgeditor and saved to the Doukwiki file, it is saved as a code block containing the HTML. When loaded back into the editor, the HTML is extracted from the code block and inserted back into the editor. The HTML_BLOCK macros remain in place in the editor, but they do not show when the page is displayed in the browser.

Editing the toolbar

Customizing from the Configuration Manager

Current versions of ckgedit enable customizing the main CKEditor toolbar in the Dokuwiki Configuration Manager. Pre-configured items can be removed and user-defined items can be added. The relevant settings are: color_options , font_options, alt_toolbar, extra_plugins.

Customizing Directly in the CKEdtor Configuration File

The toolbar is defined in ckeditor/config.js, which is a compressed file. The uncompressed file is config.js.unc. Make your changes there and then you can compress the file using yuicompressor, which can be downloaded from github. See also: yui compressor documentation. When re-compressed, rename the file config.js.

There are three toolbars and each can be changed. The main Dokuwiki toolbar is config.toolbar_Dokuwiki. Simply remove the toolbar items from the list. For further information see the CKEditor toolbar page.

Image Drag and Drop

In some browsers, images can be dragged into the editor from the desktop. See drag_and_drop

Smileys

The Ckeditor comes with its own collection of smileys. With ckgedit you have access to these and to Dokuwiki's smileys when you click on the smiley toolbar icon. Dokuwiki has a protocol for adding your own smileys, using conf/smileys.local.conf and a local smileys directory lib/images/smileys/local. 3) Ckgedit understands this protocal and will give you access to these as well.

  1. When adding a wide smiley, like Dokuwiki's FIXME, the text abbreviation for the smiley must be all caps, just as with Dokuwiki's FIXME and DELETEME. For other examples see: Github:ckgedit #264.
  2. In addition, you cannot remove Dokuwiki's FIXME and DELETEME from the default list of smileys in conf/smileys.conf.

There is a configuration option which governs how smileys are displayed in the editor (smiley_as_text), i.e as text or as icon. if this option is set to true, they will display as text in the editor. When the page is displayed in the browser, however, they will always be displayed as icons. The CKEditor smileys are always displayed as icons, both in the editor and in the browser.

RStudio Support

There is a stand-alone plugin that supports the importation of RStudio files into the ckgeditor.

Examples

For some examples of using plugins with ckgedit and of some other features, such as line spacing, see:

Language Support

Filebrowser

There is support for labels and error messages used in the filebrowser. This includes the Link and Image dialogs.

Locate your language file in ckgedit/ckeditor/lang. It contains the CKEditor's translations for your language in the file <your_language_code>.js. There you will find, in compressed form, the following javascript object:

  CKEDITOR.lang['<your_language_code>']={} 

These are the core CKEditor language strings. The language strings specific to Dokuwiki are located in the file en.js.ckgedit. These are the English strings and are denoted by the en language code. You will have to substitue your own langauge code and your own translations for the entries in this file. They don't have to be done all at once. You can add as needed. Then you must insert your language updates into the language file identified by your language code. It goes beneath the compressed core translation string. The model for this insertion will be found in en.js.unc. The .unc extension designates an uncompressed or partially uncompressed file. See compression, below. It is also possible to uncmpress these language files, to make any other changes you want, by using and un-compressor. One is found here: http://jsbeautifier.org/.

Plugins

There are also several plugins which have been written for ckgedit, such as the Font Assist plugin described above. The language template for these is also ckgedit/ckeditor/lang/en.js.ckgedit and these are handled exactly as the filebrowser entries, for instance: CKEDITOR.lang['<your_language_code>']['fontassist'] = {}

Compression

The .unc extension stands for “uncompressed”. You can, however, compress these files using the yuicompressor. The basic documentation is found at: https://github.com/yui/yuicompressor#global-options.

Editor Window Height

The height of the editor window can be set by entering a new value in the Editor Height text box. The new height will take effect when the editor is reloaded. The value is set in pixels and the default value is 250 pixels.

Short-cut keys

CTRL + I italic
CTRL + B bold
CTRL + U underline
CTRL + Z undo
CTRL + Y redo
CTRL + L link
ALT + - numbered list
ALT + 8 bulleted list
ALT + * bulleted list
ALT + m code

The short-cut keys for inserting headers were changed form ALT+n to CTRL+n on 8/30/2013 in order to avoid conflicts with keyboards that use AltGR.

CTRL + 0 remove heading
CTRL + 1, header one
CTRL + 2, header two
CTRL + 3 header three
CTRL + 4 header four
CTRL + 5 header five

Direct Access to Dokuwiki Editor

There is a small plugin that gives immediate direct access to the Dokuwiki editor from the Dokuwiki template's tools menu. It can be installed from the Extension Manager using the following url: https://github.com/turnermm/dwedit/tarball/master. For users of the default Dokuwiki template this adds a DW Edit button to the page tools series at the right of the template. If not using the Dokuwiki template, you can add a DW Edit link to your template using the following code placed in a php block:

   tpl_toolsevent('dweditlink', array());

Dokuwiki Entities with left-hand angle brackets

If you use entities with left-hand angle brackets, for each of them you should add an entry in conf/entities.conf which substitutes &lt; for the left-hand angle bracket. For instance, for <=> you would add:

  &lt;=>

See more examples here.

Farms

There is a branch of ckgedit which accommodates farm installations. For how-to set up farms, first read the documents on farms: the basic document is at farms and more detail can be found at redirect_farm. The ckgedit farm branch handles both the virtual host and .htaccess farm techniques. There is also a version that enables the Dokuwiki media manager and link wizard. See versions below and the comments on ckgdoku above.

.htaccess method

In the ckgedit/scripts directory, you will find a version of addanimal.sh modified for use with ckgedit. Use this script in the same way as described in the farms tips page. This script will add your animals to the barn so that it is properly set up for use with ckgedit. In particular, it adds to the animal's local.php two configuration items:

     $conf['animal'] = 'your_animal';
     $conf['animal_inc'] = '/absolute/path/to/barn/your_animal/';

So, if you already have a farm set up, you will have to add these $conf items to each animals local.php.

media directories

In the farmer, you must create a media directory which your animal will access instead of the default fckeditor/userfiles directory. Every animal requires its own directory to access its media files. Like userfiles these directories will be located in the farmer's ckgedit/fckeditor. So if you have the animals cat and dog, then you will have:

  <farmer>/lib/plugins/ckgedit/fckeditor
       cat
       dog
       userfiles

In each of these new directories you must create links to their actual media directories, much the same as in the userfiles directory. You need at least three links named as follows:

   media
   image
   file

They must all point to the data/media directory created for the animal. In addition you should copy blink.jpg and the your preferred .htaccess file from the fckeditor/userfiles directory into your new directory. The web server requires limited access to the media directory.

Virtual Host method

If your farm is based on the virtual host method, you will not have a barn. Instead all of your animals must be subdirectories of the dokuwiki distribution, and ideally their names should use the full domain name. So, if your domain is example.org your animals will have the form animal.example.org, exactly as it appears in the virtual host container of your web server. To create the animals for this method. there is a second script: add_v_animals.sh. It will create your animals and set up the correct configuration options. Once the animals have been created you will create for each animal a media directory as described above for the .htaccess method.

The directory structure for the virtual host example.org will look something like this:

example_org_directory
    bin
    chicken.example.org
    conf
    cow.example.org
    data
    doku.php
    inc
    index.php
    lib
    vendor

example_org_directory is the document root of the virtual host server. example.org is the domain, and the animals are the subdomains and have the same document root as example.org. See using virtual hosts.

Video Clips

You can view various demonstrations on YouTube of how to use ckgedit:
1. ckgedit Playlist
2. listing and descriptions of individual videos

Available Versions of ckgedit

Distribution Features Docs
master Current distribution (at CKEditor 4.5.7) Accessible from Extension Manager and this page. For image drag and drop in FireFox see: drag_and_drop
pre-php5.3 alternate action/edit.php for versions of php earlier than PHP 5.3 No longer being kept up to date. Test for usability
farms-4.5.7 Upgrade from CKEditor 4.5.1 to 4.5.7. Includes upgraded file browser. (Can also be used with non-farms configurations.) Current stable version.
captcha Supports the captcha plugin. Up-to-date with current ckgedit.
ckgdoku Includes support for Dokuwiki's mediamanager and linkwiz as well as for ckgedit's own filebrowser This is kept fully up-to-date with ckgedit. Note: requires dokuwiki Elenor Of Tsort (2016-06-26) or later
ckgdoku_farms As above but with support for farms. As with the standard farms version of ckgedit, this can be used with alternate savedir settings.

Discussion

Note: For all future discussion, please use the forum or the issues section of github.

All discussion topics have been moved to separate pages. The first to be opened was: Discussion Page One. The topics on Page One include:

  • geshi code blocks
  • changing size of editing window
  • creating a new Ckeditor toolbar item
  • broken layout issues, table cell alignment.

Discussion Page One is now so full that I have opened a Second Discussion page: Discussion Page Two. Topics on Page 2 include:

  • “Indent” toolbar item
  • interwiki links
  • code blocks in lists
  • Firefox Crashes with long file
  • Multi-line plugins
  • IE issues
  • Filebrowser in Debian with alternatve save directory

Discussion Page 3

The topics on page 3 include: discussion_3

  1. Unwanted code replacement
  2. blank page while click “Broswe Server” button in image properties popup
  3. ckgedit for monobook and vector templates (skins)
  4. Importing Documents
  5. Cant Save
  6. Error with internal link
  7. Farm setup

Discussion 4

Please use Discussion Page 4. — Myron TurnerMyron Turner
turnermm

2014-12-14 01:27
The topics on Page 4 include:

  1. Switching editors
  2. Internal link built incorrectly ?
  3. URL Encoded characters in URL's being mangled
  4. A way to get the pagename in frmfolders.html ?

ckgedit can be configured to work with the data plugin. See discussion page_2: configuration_to_use_different_editors.

1)
If you have been running fckgLite (fckg) and want to test ckgedit, you must disable fckgLite.
2)
Details for font styling in versions prior to Nov 2014 are found here: old_font_styling
plugin/ckgedit.txt · Last modified: 2017-03-23 16:08 by turnermm