* Give a link to the 1.44 TinyMCE version.
[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 Authors: Matt Westgate <drupal at asitis dot org> and
6          Richard Bennett <richard.b@gritechnologies.com>
7 Dependancies:
8   This module requires the third-party TinyMCE editor and a
9   Javascript-enabled web browser.  Currently it is known to work
10   with Internet Explorer, Mozilla and Firefox and degrade gracefully
11   for Safari and Konqueror users. A browser compatibility chart is here:
12
13   http://tinymce.moxiecode.com/wrapper.php?url=tinymce/docs/compatiblity.htm
14
15 INSTALLATION:
16 ********************************************************************
17 1. Place the entire tinymce directory into your Drupal modules/
18    directory.
19
20 2. Download TinyMCE 1.44 from
21
22      http://prdownloads.sourceforge.net/tinymce/tinymce_1_44.zip
23
24    Remember to uncompress the file and make sure the folder is named
25    'tinymce'.
26
27 3. Place the entire 'tinymce' folder inside your modules/tinymce directory.
28
29 4. Load the database definition file (tinymce.mysql) using the
30    tool of your choice (e.g. phpmyadmin). For mysql and command line
31    access use:
32
33      mysql -u user -p drupal < tinymce.mysql
34
35    Replace 'user' with the MySQL username, and 'drupal' with the
36    database being used.
37
38 4. Enable this module by navigating to:
39
40      administer > modules
41
42 5. Optionally, setup role based tinymce profiles via
43
44      administer > settings > tinymce
45
46 Create new content and see TinyMCE in action!
47
48 README:
49 ********************************************************************
50 Once TinyMCE is enabled, the default behavior is that all textareas
51 will use TinyMCE for all users. The admin can change these defaults
52 at
53
54   administer > settings > tinymce
55
56 For example, the default theme TinyMCE will use is called 'simple'.
57 Themes control the functionality TinyMCE makes visible. It comes
58 with 3 themes:
59
60   1) Simple - basic formatting
61   2) Default - basic formatting with lists and hyperlinks
62   3) Advanced - many many features. See a demo at
63         http://tinymce.moxiecode.com/example_advanced.php?example=true
64
65 The admin can choose what theme TinyMCE should be the default and
66 user's can override this by editing their account (if they've been
67 given permissions to do so). User's also have the option of disabling
68 TinyMCE completely.
69
70 The admin can also define which pages TinyMCE should be used on.
71 This cannot be changed on a per user basis.
72
73 DRUPAL PLUGINS FOR TINYMCE:
74 ********************************************************************
75 NOTE: If you want to use img_assist with TinyMCE, you don't have to
76       install a plugin. Just enable the img_assist module and click
77       the photo icon that appears below each textarea.
78
79 Located in the plugins directory are Drupal specific plugins for
80 TinyMCE. Once you've downloaded and installed the TinyMCE engine,
81 copy this plugins over the directory of TinyMCE
82 (tinymce/jscripts/tiny_mce/). Most of these plugins will already be
83 active if you use the 'advanced' theme for tinymce. See the
84 documentation in each plugin folder for more details.
85
86 CAVEATS
87 ********************************************************************
88 By default, Drupal uses the 'Filtered HTML' input format for adding
89 content to the site and this can create conflicts with TinyMCE. It's
90 best when using this editor to use an input format that has all
91 filters disabled. What I usually do is create an input format called
92 'Rich-text editing' and set that as the default format for roles which
93 use TinyMCE exclusively. To modify your input formats go to:
94
95     Administer > input formats > configure > configure filters
96
97 TWEAKING THE TINYMCE THEME
98 ********************************************************************
99
100 Developers have complete control over when and how tinymce is enabled
101 for each textarea inside Drupal by creating a custom Drupal theme
102 function. The following example assumes you're using a phptemplate based theme.
103
104 Put the following function in your themes template.php file:
105
106 /**
107  * Customize a TinyMCE theme.
108  *
109  * @param init
110  *   An array of settings TinyMCE should invoke a theme. You may override any
111  *   of the TinyMCE settings. Details here:
112  *
113  *    http://tinymce.moxiecode.com/wrapper.php?url=tinymce/docs/using.htm
114  *
115  * @param textarea_name
116  *   The name of the textarea TinyMCE wants to enable.
117  *
118  * @param theme_name
119  *   The default tinymce theme name to be enabled for this textarea. The
120  *   sitewide default is 'simple', but the user may also override this.
121  *
122  * @param is_running
123  *   A boolean flag that identifies id TinyMCE is currently running for this
124  *   request life cycle. It can be ignored.
125  */
126 function phptemplate_tinymce_theme($init, $textarea_name, $theme_name, $is_running) {
127   switch ($textarea_name) {
128     // Disable tinymce for these textareas
129     case 'log':
130     case 'img_assist_pages':
131     case 'caption':
132       unset($init);
133       break;
134
135     // Force the 'simple' theme for some of the smaller textareas.
136     case 'signature':
137     case 'site_mission':
138     case 'site_footer':
139     case 'settings][access_pages':
140       $init['theme'] = 'simple';
141       unset($init['theme_advanced_toolbar_location']);
142       unset($init['theme_advanced_toolbar_align']);
143       unset($init['theme_advanced_path_location']);
144       unset($init['theme_advanced_blockformats']);
145       unset($init['theme_advanced_styles']);
146       break;
147   }
148
149   // Add some extra features when using the advanced theme.
150   switch ($theme_name) {
151     case 'advanced':
152       $init['extended_valid_elements'] = 'a[href|target|name|title|onclick]';
153       $init['theme_advanced_buttons3_add_before'] = 'tablecontrols,separator';
154       $init['plugins'] = file_exists(drupal_get_path('module', 'tinymce'). '/tinymce/jscripts/tiny_mce/plugins/drupalimage') ? 'drupalimage,table,emotions,print' : 'table,emotions,print';
155       $init['theme_advanced_buttons3_add'] = 'drupalimage,emotions,separator,print';
156       break;
157   }
158
159   // Always return $init; !!
160   return $init;
161 }
162
163 If you study the above function you can see that tinymce can be completely
164 disabled or you can even switch themes for a given textarea.
165
166 See the TinyMCE manual for details on the parameters that can be
167 sent to TinyMCE:
168
169 http://tinymce.moxiecode.com/wrapper.php?url=tinymce/docs/index.htm