[Summary view] [Print] [Text view]

   1  $Id: README.txt,v 1.3.2.11 2010/07/05 15:04:50 wwalc Exp $
   2  
   3  CONTENTS OF THIS FILE
   4  ---------------------
   5  
   6   * Overview
   7   * Required components
   8   * More information and license
   9   * Requirements
  10   * Installation / Configuration
  11   * Installation troubleshooting
  12   * Plugins: Teaser break and Pagebreak
  13   * Plugins: MediaEmbed
  14   * Plugins: IMCE
  15   * Uploading images and files
  16   * How to install CKFinder
  17   * Modules: Link to content (EXPERIMENTAL)
  18   * Setting up filters
  19   * Upgrading instructions
  20   * Help & Contribution
  21   * Credits
  22  
  23  Overview
  24  --------
  25  This module allows Drupal to replace textarea fields with the CKEditor.
  26  This HTML text editor brings many of the powerful functions of known
  27  desktop editors like Word to the web. It's relatively lightweight and
  28  doesn't require any kind of installation on the client computer.
  29  
  30  Required components
  31  -------------------
  32  To use CKEditor in Drupal, you will need to download the CKEditor
  33  http://ckeditor.com/
  34  
  35  More information and licence
  36  ----------------------------
  37  CKEditor - The text editor for internet
  38  Copyright (C) 2003-2010 CKSource - Frederico Knabben
  39  
  40  Licensed under the terms of the GNU Lesser General Public License:
  41      http://www.opensource.org/licenses/lgpl-license.php
  42  
  43  For further information visit:
  44      http://ckeditor.com/
  45      http://drupal.ckeditor.com
  46  
  47  Requirements
  48  ------------
  49    - Drupal 6.x
  50    - PHP 4.3.0 or greater
  51    - CKEditor 3.1 or greater (http://ckeditor.com/)
  52  
  53  Installation / Configuration
  54  -------------------
  55  Note: this instruction assumes that you install CKEditor in
  56        sites/all/modules directory (recommended).
  57  
  58     1. Unzip the files in the sites/all/modules directory. It should now
  59        contain a ckeditor directory.
  60     2. Download CKEditor from http://ckeditor.com/download. Unzip the
  61        contents of the ckeditor directory in the
  62        sites/all/modules/ckeditor/ckeditor or sites/all/libraries/ckeditor directory.
  63        Note: you can skip uploading "_samples" and "_source" folders.
  64     3. Enable the module as usual from Drupal's admin pages.
  65     4. Grant permissions for use of CKEditor in
  66        "Administer > User Management > Permissions"
  67        Note: to enable the file browser, read also the
  68              "How to enable the file browser" section.
  69     5. Under "Administer > Site configuration > CKEditor", adjust the ckeditor profiles.
  70        Profiles determine what options are available to users based on system-wide roles. 
  71        In each profile you can choose which textareas will be replaced by CKEditor, 
  72        select default toolbar and configure some more advanced settings.
  73        NOTE: User 1 must be assigned a system role that corresponds to the privileges required.
  74        If no role is assigned to User 1, they will have the privileges of "authenticated user" 
  75     6. For the Rich Text Editing to work you also need to configure your filters
  76        for the users that may access Rich Text Editing.
  77        Either grant those users Full HTML access or use the following tags:
  78        <a> <p> <span> <div> <h1> <h2> <h3> <h4> <h5> <h6> <img> <map> <area> <hr>
  79        <br> <br /> <ul> <ol> <li> <dl> <dt> <dd> <table> <tr> <td> <em> <b> <u> <i> <strong>
  80        <del> <ins> <sub> <sup> <quote> <blockquote> <pre> <address> <code>
  81        <cite> <embed> <object> <param> <strike> <caption> <tbody>
  82        Fore easier usage (copying), all tags are below in one line:
  83        <a> <p> <span> <div> <h1> <h2> <h3> <h4> <h5> <h6> <img> <map> <area> <hr> <br> <br /> <ul> <ol> <li> <dl> <dt> <dd> <table> <tr> <td> <em> <b> <u> <i> <strong> <del> <ins> <sub> <sup> <quote> <blockquote> <pre> <address> <code> <cite> <embed> <object> <param> <strike> <caption> <tbody>
  84        If you're going to use CKEditor with Filtered HTML input format,
  85        please read also "Setting up filters" section. 
  86     7. To have a better control over line breaks, you may disable Line break converter
  87        in the chosen filter (recommended).
  88     8. Modify the ckeditor.config.js file to custom your needs (optional).
  89        Configuration options are available here: 
  90        http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html
  91        Developers documentation for CKEditor:
  92        http://docs.cksource.com/CKEditor_3.x/Developers_Guide
  93        In ckeditor.config.js you may define your own toolbars with selected buttons.
  94        WARNING: clear browser's cache after you modify any of the javascript files.
  95        If you don't do this, you may notice that browser is ignoring all your changes.
  96  
  97  
  98  Installation troubleshooting
  99  ----------------------------
 100  If your CKEditor does not show you must check if all files are
 101  extracted correctly.
 102  
 103  The directory /modules/ckeditor/ckeditor/ or /libraries/ckeditor should have the following files:
 104  ckeditor.js, config.js, contents.css 
 105  and directories: "skins", "themes", "lang", "images"
 106  
 107  Alternative directory can be sites/all/libraries/ckeditor, module automatically recognize proper path to editor. Libraries directory is default path when drush is used to download editor javascript.  
 108  
 109  The correct directory structure is as follows:
 110  modules               <dir>
 111     ckeditor           <dir>
 112        ckeditor.module
 113        ckeditor.admin.inc
 114        ...
 115        ckeditor        <dir>
 116           _source      <dir>
 117           images       <dir>
 118           lang         <dir>
 119           plugins      <dir>
 120           skins        <dir>
 121           themes       <dir>
 122           COPY_HERE.txt
 123           ckeditor.js
 124           ...
 125  
 126  If you're still having problems, scroll down to the "Help & Contribution" section.
 127  
 128  Plugins: Teaser break and Pagebreak
 129  -----------------------------------
 130  By default, CKEditor module comes with two plugins that can handle
 131  teaser break (<!--break-->) and pagebreak (<!--pagebreak-->).
 132  Both plugins are automatically enabled.
 133  
 134     1. To add 'DrupalBreak' and 'DrupalPageBreak' buttons to the toolbar,
 135        open sites/all/modules/ckeditor/ckeditor.config.js and add them to the toolbar 
 136        definition (both buttons are enabled in DrupalFiltered and DrupalFull
 137        toolbars by default).
 138        The 'DrupalBreak' button will automatically disappear from the toolbar
 139        on textareas where teaser cannot be created.
 140  
 141     2. Note that the <!--pagebreak--> tag is not supported by default in Drupal.
 142        You should install the Paging module: http://drupal.org/project/paging
 143        to enable the <!--pagebreak--> tag support. Please refer to the Paging
 144        module documentation for detailed installation instructions.
 145        If you don't install Paging module, the 'DrupalPageBreak' will automatically disappear.
 146  
 147  Plugins: MediaEmbed
 148  -------------------
 149  MediaEmbed is a simple plugin that can be helpful when embedding Youtube movies (for example).
 150  To enable it, do the following:
 151  
 152     1. Open /drupal/modules/ckeditor/ckeditor.config.js
 153  
 154     2. Uncomment the following lines (remove "//") in ckeditor.config.js:
 155        // config.extraPlugins += (config.extraPlugins ? ',mediaembed' : 'mediaembed' );
 156        // CKEDITOR.plugins.addExternal('mediaembed', Drupal.settings.ckeditor.module_path + '/plugins/mediaembed/');
 157  
 158     3. Add button to the toolbar. The button name is: MediaEmbed. 
 159        For example if you have a toolbar with an array of buttons defined as follows:
 160  
 161        ['Link','Unlink','Anchor']
 162  
 163        simply add button at the end of array (or somewhere in the middle):
 164  
 165        ['Link','Unlink','MediaEmbed','Anchor']
 166  
 167        (remember about single quotes).
 168  
 169  Plugins: IMCE
 170  -------------------
 171  CKEditor comes with an IMCE plugin, that adds a button to the toolbar that opens IMCE in a new window.
 172  This might be helpful if you want to avoid having to open the Image Dialog and then clicking the "Browse Server" button
 173  and instead open IMCE with a single click. 
 174  
 175  To enable it, do the following:
 176  
 177     1. Open /drupal/modules/ckeditor/ckeditor.config.js
 178  
 179     2. Uncomment the following lines (remove "//") in ckeditor.config.js:
 180        //config.extraPlugins += (config.extraPlugins ? ',imce' : 'imce' );
 181        //CKEDITOR.plugins.addExternal('imce', Drupal.settings.ckeditor.module_path + '/plugins/imce/');
 182  
 183     3. Add button to the toolbar. The button name is: IMCE. 
 184        For example if you have a toolbar with an array of buttons defined as follows:
 185  
 186        ['Link','Image']
 187  
 188        simply add button at the end of array (or somewhere in the middle):
 189  
 190        ['Link','Image','IMCE']
 191  
 192        (remember about single quotes).
 193  
 194  Uploading images and files
 195  --------------------------
 196  
 197  There are three ways of uploading files: By using commercial file browser like CKFinder (http://ckfinder.com), 
 198  by using modules like IMCE, WebFM, Image Browser or by using the core upload module.
 199  
 200  To select preferred file browser, under "Administer > Site configuration > CKEditor", adjust 
 201  CKEditor profiles. In each profile you can choose which file browser will be used (in "File browser settings" section).
 202  Note: to choose IMCE, WebFM or Image Browser you should install an appropriate Drupal module first.
 203  
 204   How to install CKFinder
 205  ------------------------
 206  CKFinder is an AJAX based file manager created by CKEditor developers: http://ckfinder.com/.
 207  
 208     1. Download CKFinder for PHP: http://ckfinder.com/download
 209     2. Unpack CKFinder to the directory with the CKEditor module (into sites/all/modules/ckeditor/ckfinder)
 210        The correct directory structure is as follows:
 211  
 212        modules               <dir>
 213           ckeditor           <dir>
 214              ckeditor.module
 215              ckeditor.admin.inc
 216              ...
 217              ckfinder        <dir>
 218                 core         <dir>
 219                 ckfinder.php
 220                 config.php
 221                 ...
 222              ckeditor        <dir>
 223                 _source      <dir>
 224                 images       <dir>
 225                 ckeditor.js
 226                 ...
 227  
 228     3. Grant "allow CKFinder file uploads" permission in "Administer > User Management > Permissions"
 229        Note: if you don't see such permission then it means that CKEditor didn't find CKFinder
 230        and you have probably uploaded CKFinder into wrong directory.
 231     4. Open CKFinder configuration file (sites/all/modules/ckeditor/ckfinder/config.php) and do the following:
 232  
 233        I) remove the CheckAuthentication() function:
 234          (don't worry, this function is defined in filemanager.config.php, see below)
 235  
 236          function CheckAuthentication()       <- remove it
 237          {                                    <- remove it
 238             //WARNING : DO NOT simply...      <- remove it
 239             ...                               <- remove it
 240             return false;                     <- remove it
 241          }                                    <- remove it
 242  
 243        II) add:
 244  
 245          require_once '../../../../includes/filemanager.config.php';
 246  
 247          straight below the following line:
 248  
 249          $baseDir = resolveUrl($baseUrl);
 250  
 251     5. Select CKFinder as preferred file browser in "Administer > Site configuration > CKEditor" 
 252        (in selected CKEditor profile scroll down to "File browser settings" section).
 253        In the "File browser settings" section you may also change destination folders for files uploaded with CKFinder.
 254  
 255     6. Locate file named settings.php inside your drupal directory
 256        (usually sites/default/settings.php) and set $cookie_domain variable to the
 257        appropiate domain (remember to uncomment that line). If you don't do this,
 258        CKFinder may show an information that the connector is disabled. 
 259        As of Drupal 6.17 also the $base_url variable must be set.
 260  
 261  Modules: Link to content (EXPERIMENTAL)
 262  ---------------------------------------
 263  Link to content module can be integrated with CKEditor.
 264  ATTENTION: this module is not yet compatible with CKEditor :(
 265  
 266  The unofficial version of Link to content module compatible with CKEditor can be downloaded here:
 267       http://drupal.ckeditor.com/download/linktocontent-ckeditor-6.x-2.x-dev.zip
 268  
 269  Installation:
 270  Follow the instruction from INSTALL.txt attached to the linktocontent module.
 271  Then do the following steps to add Linktocontent button to the CKEditor toolbar:
 272  
 273     1. Open /drupal/modules/ckeditor/ckeditor.config.js
 274  
 275     2. Add buttons to the toolbar. The button names are: LinkToNode, LinkToMenu. 
 276        For example if you have a toolbar with an array of buttons defined as follows:
 277  
 278        ['Link','Unlink','Anchor']
 279  
 280        simply add those two buttons at the end of array (or somewhere in the middle):
 281  
 282        ['Link','Unlink','LinkToNode','LinkToMenu','Anchor']
 283  
 284        (remember about single quotes).
 285  
 286        Both buttons are enabled in DrupalFiltered and DrupalFull toolbars by default.
 287        If you don't install linktocontent module, both buttons will automatically disappear from the toolbar. 
 288  
 289  Setting up filters
 290  ------------------
 291  In "Administer -> Input formats", Filtered HTML is the default filter. 
 292  Due to security reasons, enabling Full HTML is only an option for trusted users.
 293  To take the full advantage of using CKEditor you can extend the list of allowed tags in 
 294  HTML filter that is enabled in Filtered HTML input format.
 295  If you not do this, you may notice that created page looks different after saving it.
 296  
 297  Unfortunately, even if you extend the list of allowed tags, there is still one problem: 
 298  Filtered HTML not only strips disallowed tags, but also strips inline style definitions. 
 299  Basically, it means that you are unable to apply different font color, size, family, align images etc. 
 300  using CKEditor out of the box. You can solve this problem by creating another input format, 
 301  that will work in a similar way like Filtered HTML (will only allow specific tags), 
 302  but in a much better way - i.e. it will not strip inline styles that CKEditor is using when 
 303  formatting text or images after the page is saved 
 304  To create such input format, you'll need a so-called filter. Below are listed three 
 305  the most popular modules that provide HTML filter: 
 306  
 307   - WYSIWYG Filter - seems to be the easiest to install, does not require third-party libraries
 308     http://drupal.org/project/wysiwyg_filter
 309   - HTML Purifier - the most popular and powerful, although some people claim that it might be a bit slow
 310     http://drupal.org/project/htmlpurifier
 311   - htmLawed - another alternative, less popular than both modules above
 312     http://drupal.org/project/htmLawed
 313  
 314  It's up to you which one you decide to use. Just make sure that you'll allow to use only proper 
 315  inline styles, tags and attributes.
 316  See also http://drupal.ckeditor.com/filters for the latest version of this instruction.
 317  
 318  Upgrading instructions (migration from FCKeditor)
 319  -------------------------------------------------
 320     During the installation, CKEditor will check for the existence of FCKeditor module and 
 321     copy all FCKeditor settings, profiles etc. (to save your time, just disable FCKeditor module 
 322     during CKEditor installation, if you uninstall FCKeditor module before installing CKEditor, 
 323     all FCKeditor settings will be deleted from the database and CKEditor will not copy them).
 324     After installing CKEditor you may uninstall FCKeditor module.
 325  
 326     If both modules are enabled (CKEditor and FCKeditor) you may get javascript errors, if both editors
 327     will try to attach to the same textarea, be sure that's not a problem if you have problems after upgrading.
 328  
 329     Apart from the information above, installing CKEditor is just like installing a new module,
 330     so be sure to follow the installation instruction.
 331  
 332  Upgrading instructions (CKEditor)
 333  ---------------------------------
 334  This instruction assumes that you are upgrading CKEditor module [M] and CKEditor (the editor)[E] at the same time. 
 335  Instructions specific for module upgrades are tagged with [M], steps that must be taken when upgrading CKEditor (the editor) are marked with [E].
 336  
 337     1. [M] Download the latest version of CKEditor module from http://drupal.org/project/ckeditor (it is advised to read release notes before going further).
 338     2. [E] Download the latest version of CKEditor from http://ckeditor.com/download (it is advised to read "what's new" before going further: http://ckeditor.com/whatsnew).
 339     3. [M] Back up your database.
 340     4. [EM] Place the site in "Off-line" mode, to let the database updates run without interruption and avoid displaying errors to end users of the site.
 341     5. [E] If you are using CKFinder, make sure you'll not delete it, move it into a safe place.
 342     6. [E] If you have made any changes inside of sites/all/modules/ckeditor/ckeditor.config.js (or sites/all/modules/ckeditor/ckeditor/config.js), write down your changes and add them again after uploading new files (e.g. own toolbar definitions etc.). 
 343            Try to not make any changes to CKEditor's config.js and add everything to ckeditor.config.js.
 344     7. Delete old files:
 345        [EM]* Simply remove modules/ckeditor directory if upgrading both, the editor and the module. 
 346        [M] If you are upgrading module only, remember to leave the modules/ckeditor/ckeditor directory. 
 347        [E] When upgrading the editor, remove contents of modules/ckeditor/ckeditor directory only.
 348        WARNING: if you don't remove old files and just rename ckeditor directory instead e.g. to ckeditor_old, Drupal may use module from the ckeditor_old directory.
 349     8. [M] Upload CKEditor module (extracted files and folders) to sites/all/modules directory.
 350     9. [E] Upload CKEditor (extracted files and folders from the ckeditor directory) to sites/modules/ckeditor/ckeditor (i.e. where COPY HERE.txt file exists)
 351     10. [E] Copy back CKFinder (see step 5)
 352     11. [E] Apply your modifications to default configuration in ckeditor.config.js file (see step 6).
 353     12. [M] Run update.php.
 354     13. [EM] Put the site back online.
 355     
 356  Help & Contribution
 357  -------------------
 358  If you are looking for more information, have any troubles in configuration or if
 359  you found an issue, please visit the official project page:
 360    http://drupal.org/project/ckeditor
 361  
 362  Having problems? Take a look at the list of common problems when installing CKEditor:
 363    http://drupal.ckeditor.com/troubleshooting
 364  You might also check TROUBLESHOOTING.txt attached to this module, however 
 365  the online version is always up to date.
 366  
 367  How to tune up CKEditor to your theme and configure spell checker:
 368    http://drupal.ckeditor.com/tricks
 369  
 370  We would like to encourage you to join our team if you can help in any way.
 371  If you can translate CKEditor module, please use ckeditor.pot file as a template
 372  (located in "translations" directory) and send us the translated file so that we could attach it.
 373  Any help is appreciated.
 374  
 375  Credits
 376  -------
 377   - CKEditor for Drupal is currently maintained by CKEditor team and Jorrit Schippers.
 378       http://ckeditor.com/
 379  
 380   - CKEditor - The text editor for internet
 381       Copyright (C) 2003-2009 CKSource - Frederico Knabben
 382       http://cksource.com/