README Table of Contents 1. INSTALLATION a. FIRST-TIME INSTALLATION b. SUBSEQUENT OR MANUAL INSTALLATION c. A COMPLETELY MANUAL INSTALL 2. SPACE-BAR POSITIONING 3. INSERTING AND UPLOADING IMAGES 4. MEDIA MANAGER IN MULTIPLE DOKUWIKI INSTALLATIONS 5. FCKEDITOR TOOLBAR DokuWikiFCK Tools and Toolbar Extensions 6. LOCK TIME OUT AND AUTO-DRAFT SYSTEM 1. INSTALLATION HTML::WikiConverter::DokuWikiFCK This package includes DokuWikiFCK.pm, a perl extension to DokuWik.pm and fckg, a plugin which supports the new syntax created by DokuWikiFCK.pm. a. FIRST-TIME INSTALLATION A first-time installation is best done using CPAN: perl -MCPAN -e 'install HTML::WikiConverter::DokuWikiFCK' This will install all of the Perl dependencies you need as well as the fckg DokuWiki plugin. Please Note: You should be prepared to provide the installer with the full path to your DokuWiki plugins, for instance: /var/www/html/dokuwiki/lib/plugins The fckg plugin will then be installed in your plugins directory. You will also be asked if you would like to replace the DokuWiki mediamanager with a revised version which is needed for the FCKeditor The revised version is entirely compatible with DokuWiki. Your original DokuWiki mediamanager.php will be backed up. b. SUBSEQUENT OR MANUAL INSTALLATION The DokuWikiFCK package can be downloaded from this web site or from CPAN at: http://search.cpan.org/search?module=HTML::WikiConverter::DokuWikiFCK To install, the standard instructions are: gzip -dc HTML-WikiConverter-DokuWikiFCK-0..tar.gz | tar -xvf - OR tar -xzf HTML-WikiConverter-DokuWikiFCK-0.XX.tar.gz perl Makefile.PL make make test make install c. A COMPLETELY MANUAL INSTALL DokuWikiFCK.pm subclasses DokuWiki.pm in order to give additional functionality to the FCK editor. First, place DokuWikiFCK.pm and DokuWikiFCKN.pm in the perl5 directory, where DokuWiki.pm is installed. This should be: usr/lib/perl5/site_perlHTML/WikiConverter. Then install the fckg plugin in the DokuWiki plugins directory. The following perl dependencies are required: HTML::WikiConverter HTML::WikiConverter::DokuWiki 2. SPACE-BAR POSITIONING The FCKeditor supports positioning of text and images using the Outdent, Indent, and Justification toolbar items. Justification is left, right, and center. Outdent and Indent position elments at 40 pixel intervals. DokuWikiFCK has extended this functionality to enable positioning by use of the space-bar. The editor's toolbar functions have priority over space-bar positioning. Until version 3.0.1 of Firefox, Firefox ignored spaces when switching from the FCKeditor the browser; that is, it collapsed runs of contiguous spaces to a single space. Presumably, it treated spaces found in the editor like spaces in an HTML document instead of as non-breaking spaces, which have a width set by the current font and font-size. This meant, for example, that if you pushed something over from the left margin, using the space-bar, when you switched over to the browser it would be back at the left margin. To compensate, DokuWikiFCK saved runs of three or more spaces as medial dots. This required a great deal of “book-keeping”. First, since the middot is a printable character, DokuWikiFCK had to make sure that it didn't display; then it had to convert the middot to a non-breaking space when displaying in the browser; and it had to keep track of whether it was in IE or in Firefox, since the problem didn't exist in IE. Finally, it was not an ideal solution, because the middot is not the same width as a space character and since in non-Latin alaphabets the middot may have a valid orthographical use. Because of the changes in Firefox 3.0.1, this work-around is no long needed. Therefore, as of version 24 of DokuWikiFCK, the middot workaround is no longer supported. However, version 24 of DokuWikiFCK recognizes that there may still be users of DokuWiki who have not upgraded to Firefox 3 or who might be using browsers incompatible with the changes to version 24. The administrator can assign these users to a special DokuWiki group (or groups) using the Configuration Manager. The default name for this group is middot. Users assigned to this goup will use DokuiWikiFCKN instead of DokuWikiFCK. DokuWikiFCKN retains the middot protocol. In version 24, DokuWikiFCK and DokuWikiFCKN are as much as possible homogenous, and there should be little if any difference between documents edited using either of these modules when the documents are displayed in the browser. However, there is no guarantee that DokuWikFCKN will keep up with changes to DokuWikiFCK. One hopes that users will upgrade to compatible browsers. Version 24 of DokuWikiFCK has been tested on IE6 and 7, Firefox 3.0.1, Safari 3.1.2 (Windows). 3. INSERTING AND UPLOADING IMAGES The DokuWiki media manager is used for uploading files and the FCKEditor media manager is used for inserting files in the FCK editor's editing space. To implement inserting and uploading of images: a. replace the copy of DokuWiki's mediamanager.php in tpl/ with the one included in this package. b. create a userfiles directory in your document root directory. Inside userfiles, create a symbolic link that points to the dokuwiki media directory: userfiles image -> /data/media 4. MEDIA MANAGER IN MULTIPLE DOKUWIKI INSTALLATIONS If you are running more than one dokuwiki on your server,each using DokuWikiFCK, and if each has its own media directory, you will have to create a 'userfiles' directory for each installation, and each 'userfiles' will need an 'image' link to its own media directory. The way to do this is as follows: a. for each installation create a 'userfiles' directory b. in each 'userfiles' create a link to its media directory b. go to fckg/fckeditor/editor/filemanager/connectors/php.config.php and in config.php make the following edits: ADD: $UserFilesRealPath = /absolute/path/to/userfiles/'; CHANGE: Path to user files relative to the document root: $Config['UserFilesPath'] = '/userfiles/'; Note: 'path/to' does not include the document root directory itself! See the example below. //$Config['UserFilesAbsolutePath'] = ”” $Config['UserFilesAbsolutePath'] = $UserFilesRealPath; EXAMPLE: Your absolute path is: /var/www/html/dw_1/userfiles Your document root is: /html/ $UserFilesRealPath = '/var/www/html/dw_1/userfiles/'; $Config['UserFilesPath'] = '/dw_1/userfiles/'; $Config['UserFilesAbsolutePath'] = $UserFilesRealPath; The rest follows the instructions for a single userfiles directory in 3 above. 5. FCKEDITOR TOOLBAR The following FCKEditor Toolbar items are supported: FCKConfig.ToolbarSets["Dokuwiki"] = [ ['Bold','Italic','Underline','StrikeThrough','-','Subscript','Superscript'], ['OrderedList','UnorderedList'], ['Outdent','Indent'], ['JustifyCenter','JustifyLeft','JustifyRight'], ['Rule', 'Block_Q'], ['Smiley', 'SpecialChar'], [], ['Cut','Copy','Paste','PasteText', 'PasteWord', 'SpellCheck', 'Find'], ['Style'], ['FontFormat','FontName','FontSize'], ['Undo','Redo','RemoveFormat', '-','Table','Format_Table'], ['TextColor','BGColor', 'Plugin_Tool', 'Trim_Spaces','Delete_P'], ['Link','Unlink'], ['Image', 'Source' ], ['About'] ] ; The Quick Reference to the Standard toolbar items shows the toolbar icons of the tools supported by DokuWikiFCK, and it briefly describes the use of each tool. The toolbar can be customized. See the documentation on the FCKeditor site. DOKUWIKIFCK TOOLS AND TOOLBAR EXTENSIONS DokuWikiFCK implements a number of tools of its own and extensions to the standard toolbar items. These are all described fully on the features page. More briefly, they are: The plugin tool ('Plugin_Tool') a. This tool maintains the integrity of syntax plugins. b. It escapes plugin markup for plugins which use angle brackets, so that the brackets will not be mistaken for HTML syntax. c. It guarantees that plugin syntax which produces output will not be replaced by that output. This is essential for plugins that refresh their output when the page is refreshed. d. It guarantees that javascript scripts needed for the plugins will be sent to the browser. See the features page for details. The Table Formatting tool ('Format_Table') This tool supports an extended set of options for formatting tables. See the features page section on formatting tables. There is also a 'Styles' option which implements the creation of standard DokuWiki table headers. See table headers on the features page. The BlockQuote Tool ('Block_Q') This is an extended version of the Blockquote toolbar item that comes standard with the FCKEditor. Our extension supports border styles and colors, font selection and background colors. The Paragraph to LineBreak Tool ('Delete_P') The FCKeditor uses paragraphs as its basic unit of separation between text blocks. This tool will convert paragraphs to line-breaks, making it possible to create sequences of short single-spaced lines, as in I.b. above. Otherwise, single-spacing would happen only within paragraphs, and sequences of short lines would be double spaced (i.e. each it own paragraph). The ony other way in DokuWiki to get sequences of single-spaced lines is in lists. The Trim Spaces Tool ('Trim_Spaces') The FCKeditor often populates a page with blank paragraphs. This tool eliminates them. It was developed before the appearance of Firefox 3 when unnecessary inserted spaces also found their way into documents. The 'spaces' mode of this tool is operable only with the older protocol governing runs of spaces (see 2. above). 6. LOCK TIME OUT AND AUTO-DRAFT SYSTEM With version 24 of DokuWikiFCK, the FCKeditor is fully tied into DokuWiki's auto-draft and file locking systems. Until this tie-in, DokuWiki was unable to monitor the FCKeditor editing space for keyboard activity. Unable to detect evidence of editing activity, it would not save drafts and would would issue a lock time out warning every 14 minutes. Version 23 of DokuWikiFCK dealt with the latter by disabling the time out warning, because users found the warnings a nuisance. With version 24, this is no longer necessary; time out warnings and the auto-drafts work as they should. Issues: 1. Because making this tie-in took a bit of technological legerdemain, DokuWikiFCK provides for the possibility that it might fail in untested browsers or under certain browser conditions. If so, a check box will appear with the following label : Disable editor time-out messsages. Administrators may not want to allow all users to have the privilege; therefore, there is a setting in the Configuration Manager which enables the administrator to set a group which has this privilege. The default setting for this group is ANY, which means that all users have this privilege should they need it; there is no need to create a group called ANY . 2. In cases where a draft file is recovered, the draft is not in DokuWiki format but in HTML, which is how the FCKeditor sees it. 3. There is a Refresh button, which enables the user to renew the lock wthout having to Save or switch to Preview. See: http://www.dokuwiki.org/draft http://www.dokuwiki.org/locking