[Summary view] [Print] [Text view]

   1  $Id: TROUBLESHOOTING.txt,v 1.2.2.3 2010/07/05 15:04:50 wwalc Exp $
   2  
   3  Note: the HTML version of this file (always up-to-date) is available online: http://drupal.ckeditor.com/troubleshooting
   4  
   5  CONTENTS OF THIS FILE
   6  ---------------------
   7  
   8   * CKEditor doesn't work in xxx theme
   9   * Known module incompatibilities
  10   * Images aren't shown when submitted
  11   * I followed the instruction, but CKEditor doesn't show up (+ debugging instructions)
  12   * Selected toolbar does not show for user 1
  13   * The CKEditor component is not installed correctly
  14   * CKEditor doesn't work after upgrading
  15   * Text alignment doesn't work
  16   * Line breaks removed when editing content previously authored without using CKEditor
  17   * I successfully uploaded an image, but cannot see it in the file browser
  18   * Quote symbols being changed to quote entities
  19  
  20  CKEditor doesn't work in xxx theme
  21  ----------------------------------------------------
  22  
  23  Your theme may be missing:
  24  
  25  <?php print $scripts; ?>
  26  
  27  Add that line of code in the head section of your theme.
  28  The other possibility may be that:
  29  
  30  <?php print $closure; ?>
  31  
  32  is missing in your theme (solution similar as above, add that line of code to your theme at the end).
  33  You can also use a different theme.
  34  
  35  Known module incompatibilities
  36  ------------------------------
  37  
  38  At this moment, CKEditor will not show up, when the following modules are enabled:
  39  
  40      * Theme developer (http://drupal.org/node/318941)
  41      * Theme Builder (http://drupal.org/node/271032)
  42  
  43  Images aren't shown when submitted
  44  -------------------------------------------
  45  
  46  You probably must configure properly the input format. Either set it to Full HTML or add <img> tag to Filtered HTML. 
  47  The full list of tags, which should be allowed, is available in README.txt file.
  48  Make sure that you have read "Setting up filters" in README.txt or this page: http://drupal.ckeditor.com/filters
  49  
  50  I followed the instruction, but CKEditor doesn't show up
  51  --------------------------------------------------------------------------
  52  
  53  First of all make sure, that CKEditor is enabled on this specific page. 
  54  Take a look into source code of your page and search for something similar to:
  55    "ckeditor": { "module_path":
  56  
  57  If you can't find similar code, then it means that CKEditor is disabled on that page/field. 
  58  Make sure that you have the right permissions to use CKEditor and check your CKEditor profile (include/exclude settings, minimum rows value).
  59  
  60  If CKEditor is enabled, but it doesn't show up, try the following steps:
  61  
  62     1. Switch to default theme (Garland), if CKEditor appears, read the "CKEditor don't work in xxx theme" instructions. 
  63        If your theme already has "closure" and "scripts" statements, read below.
  64     2. Make sure that you're using browser compatible with CKEditor.
  65     3. On some occasions, other installed modules may cause that CKEditor will not show up (although if you look at page source, you'll see CKEditor code).
  66        Instead of CKEditor you may see a very small textarea. 
  67        This mostly happens, when some other module cause a javascript error and CKEditor can't load because of this. 
  68        To check this:
  69         - write down the list of currently installed modules
  70         - disable all additional modules
  71         - if CKEditor showed up, start enabling all those modules that you disabled in previous step and find out which module is incompatible with CKEditor.
  72           Use the project's site to report a new bug, provide the following details: 
  73             * Drupal version
  74             * CKEditor module version
  75             * CKEditor version
  76             * the name and version of incompatible module. 
  77             * if additional steps are required to reproduce this issue, like creating a new special content or configuring this additional module in a special way, then provide a detailed list of steps to follow.
  78         - if the step above didn't help, disable all additional modules and switch to Garland theme, clear browser's cache. 
  79           If CKEditor still doesn't work then it means that it may be corrupted. 
  80           Reupload CKEditor using a FTP client that warns you when files are truncated or corrupted.
  81         - if CKEditor is working only in Garland theme with all modules enabled, but it doesn't work in your theme with all modules disabled, then your theme is a problem. 
  82           Use the project's site to report a new bug, provide the following details: 
  83              * Drupal version
  84              * CKEditor module version
  85              * CKEditor version
  86              * the name and version of incompatible theme.
  87     4. Finally, if nothing helped, to find out where exactly error occured, you may use Firefox with Firebug extension. 
  88        Use the project's site to create a new support request providing as much information as possible, including the exact javascript error message that you got.
  89  
  90  Selected toolbar does not show for user 1
  91  -----------------------------------------
  92  
  93  There are two reasons why you're seeing a different toolbar (or don't see CKEditor at all):
  94  
  95   - If "Allow users to customize CKEditor appearance" is enabled then each
  96    user may override the profile settings in "Rich text editor settings" in admin/user/N/edit 
  97    ("My Account" -> "Edit")
  98  
  99   - A different profile is used for user 1 that you expect.
 100    User 1 must be assigned a system role that corresponds to the privileges required.
 101    If no role is assigned to User 1, they will have the privileges of "authenticated user" 
 102    (usually it is the "Advanced" profile).
 103  
 104  The CKEditor component is not installed correctly
 105  ---------------------------------------------------------------------------
 106  
 107  Please remember that installing CKEditor module is a two step process. You have to download and unpack:
 108  CKEditor module, that integrates the CKEditor with Drupal
 109  CKEditor, the HTML editor
 110  
 111  If your CKEditor does not show you must check if all files are extracted correctly. 
 112  The directory /modules/ckeditor/ckeditor/ should have the following files:
 113  ckeditor.js, config.js, contents.css and directories named "skins", "themes", "lang", "images"
 114  
 115  The correct directory structure is as follows:
 116  modules               <dir>
 117     ckeditor           <dir>
 118        ckeditor.module
 119        ckeditor.admin.inc
 120        ...
 121        ckeditor        <dir>
 122           _source      <dir>
 123           images       <dir>
 124           lang         <dir>
 125           plugins      <dir>
 126           skins        <dir>
 127           themes       <dir>
 128           COPY_HERE.txt
 129           ckeditor.js
 130           ...
 131  
 132  CKEditor doesn't work after upgrading
 133  -----------------------------------------------
 134  
 135  This may be caused by the browser's cache. Clear your browser's cache, restart the browser if it didn't help.
 136  If you upgraded CKEditor module, make sure that all roles with "access ckeditor" permissions are assigned to at least one CKEditor profile.
 137  
 138  Text alignment doesn't work
 139  ------------------------------------
 140  
 141  In ckeditor.config.js (located in ckeditor module directory), the following classes are defined to provide text alignment functionality:
 142  config.justifyClasses = [ 'rteleft', 'rtecenter', 'rteright', 'rtejustify' ];
 143  
 144  Unfortunately, some themes may override those styles and text alignment may not work as expected.
 145  If you're using Full HTML input format, you may simply comment out this line:
 146  //config.justifyClasses = [ 'rteleft', 'rtecenter', 'rteright', 'rtejustify' ];
 147  
 148  and CKEditor will use inline styles instead: <p style="text-align: right;">sample text</p>. 
 149  The problem is that inline styles may be used only with Full HTML. 
 150  Filtered HTML will strip that code, so don't use this solution with Filtered HTML input format. 
 151  
 152  For Filtered HTML things are a bit more complicated. For example if your theme defines such CSS style:
 153  
 154  .content p {  text-align: left; }
 155  
 156  text-align property set in .rteright class will not work. 
 157  To align <p> tag, you will have to edit modules/ckeditor/ckeditor.css file and create a style, that will be applied to <p> tag:
 158  
 159  .content p.rteleft {
 160    text-align: left;
 161  }
 162  .content p.rteright {
 163    text-align: right;
 164  }
 165  .content p.rtecenter {
 166    text-align: center;
 167  }
 168  .content p.rtejustify {
 169    text-align: justify;
 170  }
 171  
 172  Use DOM inspector (in Firefox) to check why alignment doesn't work and to correct CSS styles. 
 173  There is no universal workaround for this.
 174  
 175  Line breaks removed when editing content previously authored without using CKEditor
 176  ---------------------------------------------------------------------------------------------
 177  
 178  The problems is in the way how did you configure your input filters. 
 179  Before you enabled CKEditor, you probably had Line break converter enabled.
 180  
 181  Now you're trying to edit the same content with Line break converter disabled, thus your linebreaks are removed.
 182  
 183  Possible workarounds:
 184   * Enable Line break converter (not recommended).
 185   * Create new input format with Line break converter enabled. Use it just for old articles (recommended).
 186   * Start with CKEditor disabled by default, replace all new line characters manually with <br> tag, then use toggle to switch to WYSIWYG mode.
 187  
 188   If you're a PHP programmer, you may try the approach proposed by BakerQ in drupal.org/node/240633
 189  
 190  Quote symbols being changed to quote entities
 191  ------------------------------------------------------
 192  
 193  Some modules like Typogrify or SmartyPants require special handling of HTML entities. 
 194  For example, by default, CKEditor will convert double quote (") to &quot;. 
 195  To disable processing HTML entities, add the following line to modules/ckeditor/ckeditor.config.js:
 196  
 197  config.entities = false;
 198  
 199  It is also possible to disable processing HTML entities for selected CKEditor profile, by adding this line in "Advanced Options" -> "Custom javascript configuration":
 200  
 201  entities = false ;