fixes for tinymce install under certain conditions
[project/tinymce.git] / INSTALL.txt
1 ********************************************************************
2                      D R U P A L    M O D U L E
3 ********************************************************************
4 Name: TinyMCE module
5
6 Maintainers:  Theodore Serbinski <stanson AT gmail DOT com> and
7               Matt Westgate <drupal AT asitis DOT org> and
8               Jeff Robbins <robbins AT jjeff DOT com>
9               Richard Bennett <richard.b AT gritechnologies DOT com>
10
11            
12          
13 Dependancies:
14   This module requires the third-party TinyMCE editor and a
15   Javascript-enabled web browser.  Currently it is known to work
16   with Internet Explorer, Mozilla and Firefox and degrade gracefully
17   for Safari and Konqueror users. A browser compatibility chart is here:
18
19   http://tinymce.moxiecode.com/tinymce/docs/compatiblity_chart.html
20
21
22 INSTALLATION:
23 ********************************************************************
24
25 NOTE: During this installation process you'll be asked to also 
26       install the official TinyMCE package from 
27       tinymce.moxiecode.com.
28
29
30 1. Place the entire tinymce directory into your Drupal modules/
31    directory.
32
33    
34 2. Download TinyMCE 2.0 from
35
36      http://tinymce.moxiecode.com/
37
38    Remember to uncompress the file and make sure the folder is named
39    'tinymce'.
40
41    
42 3. Place the entire 'tinymce' engine folder inside your modules/tinymce
43    directory. So the TinyMCE engine will live in modules/tinymce/tinymce
44
45    
46 4. Enable this module by navigating to:
47
48      administer > modules
49      
50      *note - all database tables will be automatically created during this step
51
52      
53 5. Setup role based tinymce profiles via
54
55      administer > settings > tinymce
56
57      
58 6. To boost the performance of TinyMCE, download the "TinyMCE compressor" from:
59
60      http://tinymce.moxiecode.com/download.php
61
62    Place the tiny_mce_gzip.php file in 
63    
64      modules/tinymce/tinymce/jscripts/tiny_mce
65
66       
67 7. To use AJAX spell checking, download the spellchecker plugin:
68    (note: this requires TinyMCE 2.0.6+)
69    
70      http://tinymce.moxiecode.com/download.php
71    
72    Extract this file to
73      
74      modules/tinymce/tinymce/jscripts/tiny_mce/plugins/
75    
76    Then edit config.php in plugins/spellchecker/:
77    
78      Uncomment this line and comment out all other require_once's:
79    
80        require_once("classes/TinyGoogleSpell.class.php"); // Google web service
81    
82      Set this to true:  
83          
84              $spellCheckerConfig['enabled'] = true;
85           
86          Enable spellchecker in TinyMCE settings page, under "buttons and plugins"
87
88
89    
90 Create new content as a role that has TinyMCE permissions and see TinyMCE in
91 action!
92
93
94 README:
95 ********************************************************************
96 Once TinyMCE is enabled, the default behavior is that all textareas
97 will use TinyMCE for all users. The admin can change these defaults
98 at
99
100   administer > settings > tinymce
101
102 The admin can choose what theme TinyMCE should be the default and
103 user's can override this by editing their account (if they've been
104 given permissions to do so). User's also have the option of disabling
105 TinyMCE completely.
106
107 The admin can also define which pages TinyMCE should be used on.
108 This cannot be changed on a per user basis.
109
110
111 PLUGINS FOR TINYMCE:
112 ********************************************************************
113 Adding plugins to TinyMCE is very easy. By default, all TinyMCE
114 plugins are disabled, but can easily be enabled by going to:
115    
116    Administer > settings > tinymce
117    
118 And then editing a profile (make sure you create one first!) and going
119 to the Buttons & Plugins section. To enable a button or a plugin,
120 simply check a box and TinyMCE will automatically be updated. To find
121 out more info on what a specific button or plugin does, click the 
122 corresponding link (note not all buttons have help text).
123
124 If you wish to add more plugins to TinyMCE, simply extract these
125 plugins to the folder: tinymce\jscripts\tiny_mce\plugins
126
127 Then open up plugin_reg.php, found in the TinyMCE module folder.
128
129 Add the following lines:
130
131   $plugins['plugin_name'] = array();
132   $plugins['plugin_name']['theme_advanced_buttons3'] = array('icon_name');
133      // note, you can choose which row of buttons to use by changing
134      // the 3 to either 1 or 2
135   $plugins['plugin_name']['plugin_property'] = array('property_value');
136   
137 Be sure to set the 'plugin_name' to the name of the plugin (generally
138 the plugin folder name) and set the 'icon_name' and other properties
139 (properties are optional). See plugin_reg.php for more examples.
140
141 To add Drupal specific plugins, TinyMCE comes bundled with plugins
142 in the main module directory. These plugins include:
143
144   - drupalimage: works in conjunction with the img_assist Drupal
145     module
146     
147     NOTE: If you want to use img_assist with TinyMCE, you don't have to
148       install a plugin. Just enable the img_assist module and click
149       the photo icon that appears below each textarea.
150
151 Follow the directions in the README.txt for these plugins to enable them.
152
153
154 CAVEATS
155 ********************************************************************
156 By default, Drupal uses the 'Filtered HTML' input format for adding
157 content to the site and this can create conflicts with TinyMCE. It's
158 best when using this editor to use an input format that has all
159 filters disabled. What I usually do is create an input format called
160 'Rich-text editing' and set that as the default format for roles which
161 use TinyMCE exclusively. To modify your input formats go to:
162
163     Administer > input formats > configure > configure filters
164
165
166 TWEAKING THE TINYMCE THEME
167 ********************************************************************
168
169 Developers have complete control over when and how tinymce is enabled
170 for each textarea inside Drupal by creating a custom Drupal theme
171 function. The following example assumes you're using a phptemplate based theme.
172
173 Put the following function in your themes template.php file:
174
175 /**
176  * Customize a TinyMCE theme.
177  *
178  * @param init
179  *   An array of settings TinyMCE should invoke a theme. You may override any
180  *   of the TinyMCE settings. Details here:
181  *
182  *    http://tinymce.moxiecode.com/wrapper.php?url=tinymce/docs/using.htm
183  *
184  * @param textarea_name
185  *   The name of the textarea TinyMCE wants to enable.
186  *
187  * @param theme_name
188  *   The default tinymce theme name to be enabled for this textarea. The
189  *   sitewide default is 'simple', but the user may also override this.
190  *
191  * @param is_running
192  *   A boolean flag that identifies id TinyMCE is currently running for this
193  *   request life cycle. It can be ignored.
194  */
195 function theme_tinymce_theme($init, $textarea_name, $theme_name, $is_running) {
196   switch ($textarea_name) {
197     // Disable tinymce for these textareas
198     case 'log': // book and page log
199     case 'img_assist_pages':
200     case 'caption': // signature
201     case 'pages':
202     case 'access_pages': //TinyMCE profile settings.
203     case 'user_mail_welcome_body': // user config settings
204     case 'user_mail_approval_body': // user config settings
205     case 'user_mail_pass_body': // user config settings
206     case 'synonyms': // taxonomy terms
207     case 'description': // taxonomy terms
208       unset($init);
209       break;
210
211     // Force the 'simple' theme for some of the smaller textareas.
212     case 'signature':
213     case 'site_mission':
214     case 'site_footer':
215     case 'site_offline_message':
216     case 'page_help':
217     case 'user_registration_help':
218     case 'user_picture_guidelines':
219       $init['theme'] = 'simple';
220       foreach ($init as $k => $v) {
221         if (strstr($k, 'theme_advanced_')) unset($init[$k]);
222       }
223       break;
224   }
225
226   /* Example, add some extra features when using the advanced theme.
227   
228   // If $init is available, we can extend it
229   if (isset($init)) {
230     switch ($theme_name) {
231      case 'advanced':
232        $init['extended_valid_elements'] = array('a[href|target|name|title|onclick]');
233        break;
234     }
235   }
236   
237   */
238
239   // Always return $init
240   return $init;
241 }
242
243 If you study the above function you can see that tinymce can be completely
244 disabled or you can even switch themes for a given textarea.
245
246 See the TinyMCE manual for details on the parameters that can be
247 sent to TinyMCE:
248
249 http://tinymce.moxiecode.com/documentation.php
250
251
252 TINYMCE KEYBOARD SHORTCUTS
253 ********************************************************************
254 Ctrl+Z  Undo
255 Ctrl+Y  Redo
256 Ctrl+B  Bold
257 Ctrl+I  Italic
258 Ctrl+U  Underline