updated install docs with how to enable AJAX spell checking
[project/tinymce.git] / INSTALL.txt
index d0d0719..df71dff 100644 (file)
@@ -2,38 +2,94 @@
                      D R U P A L    M O D U L E
 ********************************************************************
 Name: TinyMCE module
-Authors: Matt Westgate <drupal at asitis dot org> and
-         Richard Bennett <richard.b@gritechnologies.com>
+
+Maintainers:  Theodore Serbinski <stanson AT gmail DOT com> and
+              Matt Westgate <drupal AT asitis DOT org> and
+              Jeff Robbins <robbins AT jjeff DOT com>
+              Richard Bennett <richard.b AT gritechnologies DOT com>
+
+           
+         
 Dependancies:
   This module requires the third-party TinyMCE editor and a
   Javascript-enabled web browser.  Currently it is known to work
   with Internet Explorer, Mozilla and Firefox and degrade gracefully
   for Safari and Konqueror users. A browser compatibility chart is here:
 
-  http://tinymce.moxiecode.com/wrapper.php?url=tinymce/docs/compatiblity.htm
+  http://tinymce.moxiecode.com/tinymce/docs/compatiblity_chart.html
+
 
 INSTALLATION:
 ********************************************************************
+
+NOTE: During this installation process you'll be asked to also 
+      install the official TinyMCE package from 
+      tinymce.moxiecode.com.
+
+
 1. Place the entire tinymce directory into your Drupal modules/
    directory.
 
-2. Download TinyMCE 1.43 from:
+   
+2. Download TinyMCE 2.0 from
 
-     http://tinymce.moxiecode.com/download.php
+     http://tinymce.moxiecode.com/
 
-   Uncompress the file and make sure it's named 'tinymce'.
+   Remember to uncompress the file and make sure the folder is named
+   'tinymce'.
 
-3. Place the entire tinymce folder inside your modules/tinymce directory.
+   
+3. Place the entire 'tinymce' engine folder inside your modules/tinymce
+   directory. So the TinyMCE engine will live in modules/tinymce/tinymce
 
+   
 4. Enable this module by navigating to:
 
      administer > modules
+     
+     *note - all database tables will be automatically created during this step
 
-4. Optionally, fine tune how this module operates by navigating to:
+     
+5. Setup role based tinymce profiles via
 
      administer > settings > tinymce
 
-Create new content and see TinyMCE in action!
+     
+6. To boost the performance of TinyMCE, download the "TinyMCE compressor" from:
+
+     http://tinymce.moxiecode.com/download.php
+
+   Place the tiny_mce_gzip.php file in 
+   
+     modules/tinymce/tinymce/jscripts/tiny_mce
+
+      
+7. To use AJAX spell checking, download the spellchecker plugin:
+   (note: this requires TinyMCE 2.0.6+)
+   
+     http://tinymce.moxiecode.com/download.php
+   
+   Extract this file to
+     
+     modules/tinymce/tinymce/jscripts/tiny_mce/plugins/
+   
+   Then edit config.php in plugins/spellchecker/:
+   
+     Uncomment this line and comment out all other require_once's:
+   
+       require_once("classes/TinyGoogleSpell.class.php"); // Google web service
+   
+     Set this to true: 
+        
+            $spellCheckerConfig['enabled'] = true;
+         
+        Enable spellchecker in TinyMCE settings page, under "buttons and plugins"
+
+
+   
+Create new content as a role that has TinyMCE permissions and see TinyMCE in
+action!
+
 
 README:
 ********************************************************************
@@ -43,28 +99,78 @@ at
 
   administer > settings > tinymce
 
-For example, the default theme TinyMCE will use is called 'simple'.
-Themes control the functionality TinyMCE makes visible. It comes
-with 3 themes:
-
-  1) Simple - basic formatting
-  2) Default - basic formatting with tables
-  3) Advanced - many many features. See a demo at
-        http://tinymce.moxiecode.com/example_advanced.php?example=true
-
 The admin can choose what theme TinyMCE should be the default and
-user's can override this by editing their account. User's also have
-the option of disabling TinyMCE completely.
+user's can override this by editing their account (if they've been
+given permissions to do so). User's also have the option of disabling
+TinyMCE completely.
 
 The admin can also define which pages TinyMCE should be used on.
 This cannot be changed on a per user basis.
 
-Tweaking a theme
------------------
 
-Developers have complete control over the arguments which invoke a
-TinyMCE theme by creating a custom Drupal theme function.  In your
-Drupal theme file create a new function called tinymce_theme:
+PLUGINS FOR TINYMCE:
+********************************************************************
+Adding plugins to TinyMCE is very easy. By default, all TinyMCE
+plugins are disabled, but can easily be enabled by going to:
+   
+   Administer > settings > tinymce
+   
+And then editing a profile (make sure you create one first!) and going
+to the Buttons & Plugins section. To enable a button or a plugin,
+simply check a box and TinyMCE will automatically be updated. To find
+out more info on what a specific button or plugin does, click the 
+corresponding link (note not all buttons have help text).
+
+If you wish to add more plugins to TinyMCE, simply extract these
+plugins to the folder: tinymce\jscripts\tiny_mce\plugins
+
+Then open up plugin_reg.php, found in the TinyMCE module folder.
+
+Add the following lines:
+
+  $plugins['plugin_name'] = array();
+  $plugins['plugin_name']['theme_advanced_buttons3'] = array('icon_name');
+     // note, you can choose which row of buttons to use by changing
+     // the 3 to either 1 or 2
+  $plugins['plugin_name']['plugin_property'] = array('property_value');
+  
+Be sure to set the 'plugin_name' to the name of the plugin (generally
+the plugin folder name) and set the 'icon_name' and other properties
+(properties are optional). See plugin_reg.php for more examples.
+
+To add Drupal specific plugins, TinyMCE comes bundled with plugins
+in the main module directory. These plugins include:
+
+  - drupalimage: works in conjunction with the img_assist Drupal
+    module
+    
+    NOTE: If you want to use img_assist with TinyMCE, you don't have to
+      install a plugin. Just enable the img_assist module and click
+      the photo icon that appears below each textarea.
+
+Follow the directions in the README.txt for these plugins to enable them.
+
+
+CAVEATS
+********************************************************************
+By default, Drupal uses the 'Filtered HTML' input format for adding
+content to the site and this can create conflicts with TinyMCE. It's
+best when using this editor to use an input format that has all
+filters disabled. What I usually do is create an input format called
+'Rich-text editing' and set that as the default format for roles which
+use TinyMCE exclusively. To modify your input formats go to:
+
+    Administer > input formats > configure > configure filters
+
+
+TWEAKING THE TINYMCE THEME
+********************************************************************
+
+Developers have complete control over when and how tinymce is enabled
+for each textarea inside Drupal by creating a custom Drupal theme
+function. The following example assumes you're using a phptemplate based theme.
+
+Put the following function in your themes template.php file:
 
 /**
  * Customize a TinyMCE theme.
@@ -79,30 +185,74 @@ Drupal theme file create a new function called tinymce_theme:
  *   The name of the textarea TinyMCE wants to enable.
  *
  * @param theme_name
- *   The default theme name to be enabled for this textarea. The sitewide
- *   default is 'simple', but the user may also override this.
+ *   The default tinymce theme name to be enabled for this textarea. The
+ *   sitewide default is 'simple', but the user may also override this.
+ *
+ * @param is_running
+ *   A boolean flag that identifies id TinyMCE is currently running for this
+ *   request life cycle. It can be ignored.
  */
-function tinymce_theme($init, $textarea_name, $theme_name) {
-  switch ($theme_name) {
-    case 'advanced':
-      $init['extended_valid_elements'] = 'a[href|target|name]';
-      $init['plugins'] = 'table,emotions,iespell, print';
-      $init['theme_advanced_buttons3_add_before'] = 'tablecontrols,separator';
-      $init['theme_advanced_buttons3_add'] = 'emotions,iespell,separator,print';
-      return $init;
+function theme_tinymce_theme($init, $textarea_name, $theme_name, $is_running) {
+  switch ($textarea_name) {
+    // Disable tinymce for these textareas
+    case 'log': // book and page log
+    case 'img_assist_pages':
+    case 'caption': // signature
+    case 'pages':
+    case 'access_pages': //TinyMCE profile settings.
+    case 'user_mail_welcome_body': // user config settings
+    case 'user_mail_approval_body': // user config settings
+    case 'user_mail_pass_body': // user config settings
+    case 'synonyms': // taxonomy terms
+    case 'description': // taxonomy terms
+      unset($init);
+      break;
+
+    // Force the 'simple' theme for some of the smaller textareas.
+    case 'signature':
+    case 'site_mission':
+    case 'site_footer':
+    case 'site_offline_message':
+    case 'page_help':
+    case 'user_registration_help':
+    case 'user_picture_guidelines':
+      $init['theme'] = 'simple';
+      foreach ($init as $k => $v) {
+        if (strstr($k, 'theme_advanced_')) unset($init[$k]);
+      }
+      break;
   }
-}
 
-The above function would add tables, emotions, spellchecking
-(IE only) and a print button to the 'advanced' theme.  There are
-many ways this function can be used. For example you could make
-comment textareas use the 'simple' theme while node forms use
-'advanced' by inspecting the name of the textarea ($textarea_name).
+  /* Example, add some extra features when using the advanced theme.
+  
+  // If $init is available, we can extend it
+  if (isset($init)) {
+    switch ($theme_name) {
+     case 'advanced':
+       $init['extended_valid_elements'] = array('a[href|target|name|title|onclick]');
+       break;
+    }
+  }
+  
+  */
+
+  // Always return $init
+  return $init;
+}
 
-Note that the way you build the theme function depends on the theme
-engine you're using.
+If you study the above function you can see that tinymce can be completely
+disabled or you can even switch themes for a given textarea.
 
 See the TinyMCE manual for details on the parameters that can be
 sent to TinyMCE:
 
-http://tinymce.moxiecode.com/wrapper.php?url=tinymce/docs/index.htm
+http://tinymce.moxiecode.com/documentation.php
+
+
+TINYMCE KEYBOARD SHORTCUTS
+********************************************************************
+Ctrl+Z  Undo
+Ctrl+Y  Redo
+Ctrl+B  Bold
+Ctrl+I  Italic
+Ctrl+U  Underline