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.
fckg includes a dedicated version of the fckw plugin, altered for use with 
for DokuWikiFCK.pm. Both fckw and fckg cannot both be installed at the
same time.  Similarly, if you have installed an earlier version of DokuWikiFCK
with a 'styles' plugin, you cannot run the 'styles' plugin at the same
time as fckg.  You can disable these plugins by making them unreadable and
non executable:  
            chmod a-rwx styles
            chmod a-rwx fckw  


1. INSTALLATION

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. 
   		
    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 CPAN at:

          http://search.cpan.org/search?module=HTML::WikiConverter::DokuWikiFCK

    To install, the standard instructions are:

        gzip -dc  HTML-WikiConverter-DokuWikiFCK-0.<nn>.tar.gz  | tar -xvf -
               OR
        tar -xzf HTML-WikiConverter-DokuWikiFCK-0.<nn>.tar.gz

        perl Makefile.PL
        make
        make test
        make install
  
   
If you have previously installed DokuWikiFCK, consult this README document.  If the only
change is to DokuWikiFCK.pm, you can simply replace the old version of DokuWikiFCK.pm
with this new one.  You should normally find it in the following perl5 directory:

    usr/lib/perl5/site_perl/<perl_version>/HTML/WikiConverter


c. A COMPLETELY MANUAL INSTALL

DokuWikiFCK.pm subclasses DokuWiki.pm in order to give additional
functionality to the FCK editor.  First, place DokuWikiFCK.pm in the perl5 directory,
where DokuWiki.pm is installed. This should be: 
    usr/lib/perl5/site_perl/<perl_version>/HTML/WikiConverter
Then install the fckg plugin in the DokuWiki plugins directory.

The following perl modules are required:
	HTML::WikiConverter
	HTML::WikiConverter::DokuWiki
        HTML::WikiConverter::DokuWikiFCK (included in this package)


2. SPACE-BAR POSITIONING

The FCK Editor supports positioning of text and images using the Outdent, Indent,
and Justification icons.  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.  Space-bar positioning
is on by default. 

To disable space-bar positioning, set the Perl variable $SPACEBAR_NUDGING to 0:
  my $SPACEBAR_NUDGING = 0;
This will be found at the top of the DokuWikiFCK.pm file.

In FireFox, when multiple space insertions have been made against a
non-white background, one or more '?' or medial dots may appear in the
space which has been opened up by the space-bar. These characters will
also occur when changing from IE to FireFox for editing. These are
temporary. They disappear when the the file is saved and the editor is
exited. Even if they reappear in the FCK editor, they will not appear in
the final page as displayed by the browser. 


3. INSERTING AND UPLOADING IMAGES

In the current version of fckw, 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:
	1.replace the copy of DokuWiki's mediamanager.php in tpl/<default> with 
the one included in this package. 

        2. create a userfiles directory in your document root directory.  Inside userfiles,
create a symbolic link that points to the dokuwiki media directory:
             userfiles
                image -> <dokuwiki_directory>/data/media


4. USING THE 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:

  1. for each installation create a 'userfiles' directory
  2. in each  'userfiles' create a link to the dockuwiki media directory
  3. 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/' ;
      $Config['UserFilesPath'] =  '/<path/to/>userfiles/'; 
      NOTE:  'path/to/' does not include the document root directory itself.  See 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'],
  ['Table','Rule', 'Blockquote'], ['Smiley', 'SpecialChar'], [],  
  ['Cut','Copy','Paste','PasteText', 'PasteWord', 'SpellCheck' ],   
  ['Style'], ['FontFormat','FontName','FontSize'], 
  ['Undo','Redo','RemoveFormat', '-','Find'],   
  ['TextColor','BGColor', 'Abbr'],
  ['Link','Unlink'], ['Image', 'Source'],   
  ['About']   

] ;

The tool designated as 'Abbr' is the plugin tool.  It maintains the integrity of plugin syntax.
   1. It escapes plugin syntax for plugins which use angle brackets, < and >, so that 
the brackets will not be mistaken for HTML syntax.
   2. It guarantees that plugin syntax which produces output will not be replaced by that
output.     
   3. It guarantees that javascript scripts needed for the plugins will be sent to
the browser.      


6.  LOCK TIME OUT

DokuWiki normally issues its time out warning after 15 minutes of keyboard
inactivity.  But the FCKEditor interferes with this monitoring, so DokuWiki believes that
there is no keyboard activity even when there is and so issues time out warnings.  
DokuWikiFCK disables the lock timer and hence the warning pop-ups. The lock timer is
tied into DokuWiki's automatic draft back-up system,but because DW is not aware of the
FCKeditor, it can't back up its contents.  We hope to remedy this in a future 
release.

7. DokuWiki SYNTAX PLUGIN SUPPORT
There is a toolbar item which enables the user to buffer syntax plugin syntax, so that the
syntax behavors correctly.  The toolbar icon is an electric plug.  Use the mouse to
select the plugin's syntax and the click on the plugin icon.  A small dialog will appear
asking for the name of the plugin.  Enter the name and click OK. DokuWikiFCK will 
identify the plugin from its syntax;it uses the same code as DokuWiki uses to
identify plugins.  DokuWikiFCK will use the name you give in the dialogue only as a
last resort. 

When adding data for a text-based plugin, on subsequent occasions, you must re-set the plugin by
again highlighting the plugin syntax and its enclosed data.  This insures that the plugin is
correctly formatted to be recognized by DokuWikiFCK and deletes potentially code-breaking HTML markup
that the GUI inserts into the plugin data.

If you have previously used the plugin tool to identify a plugin, you can remove the plugin
by re-selecting the plugin syntax, clicking on the plugin tool,leaving the dialog box empty,
and clicking OK.  The plugin--and all its contained data--will be removed when the page is saved.  

The plugin tool does not always work with versions of PHP prior to version 5.  

8. EDITOR SUPPORT
DokuWikiFCK now has a transparent facility for switching between the FCKeditor and the DokuWiki editor.
There are always buttons on screen which enable the user to switch to the other editor.  When switching
from the FCKeditor to the DokuWiki editor, you are given the option of backing up the FCK file and
starting the DokuWiki session with a clean file of the same name. It is also possible to
choose to convert the FCK syntax to native DokuWiki syntax.

This means that the user can choose which editor to use for a particular project.  One scenario
might be to start with basic DokuWiki text editing and then switch to FCK for layout and design.

9. TABLE HEADERS
Table headers can be created by selecting the text in the header cell and then selecting "Create TH"
from the drop-down "Style" menu.  Initially, the selected text will appear against the standard
DokuWiki gray-blue TH background color.  After the file has been saved, the cell will have been
converted to a standard DokuWiki TH cell and the entire cell will have the gray-blue background color.
To convert a TH back to a TD, select the TH text and choose "Remove TH" from the "Style" menu.   	

10.  TABLE FORMATTING TOOL
As of version 23, there is a toolbar item for formatting tables.  Its appearance is a blue, white and gray
checkerboard, representing the cells of a table.

This tools supports both structural and 'cosmetic' formatting features:

	        background colors for cells, rows, and columns 
	        horizontal text alignment for cells, rows, and columns 
	        setting of cell width and column spans
                deleting individual cells 
	        inserting, deleting and moving entire columns and rows 

Clicking on the tool button opens up a dialog panel which contains complete instructions for use
of all supported fomatting features.

The TABLE HEADERS feature itemized in 9 above is still supported and remains the way to create
standard DokuWiki table headers.  Background colors cannot be reset for DokuWiki-style table headers,
since their background colors are pre-set by DokuWiki style sheets.  To set background colors for these
cells using the TABLE FORMATTING TOOL, they have to first be set back to regular TD's, as described
in item 9. 

Myron Turner
turnermm02@shaw.ca