_tinymce/docs/customization_themes.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <title>Customization - Creating a theme</title>
   5 <link href="css/screen.css" rel="stylesheet" type="text/css" />
   6 </head>
   7 <body>
   8
   9 <div class="header">
  10         <h1>Customization - Creating a theme</h1>
  11 </div>
  12
  13 <div class="content">
  14 <h2>Creating your own Themes</h2>
  15 <p>
  16 Creating you own themes for the TinyMCE application is fairly easy if you know the basics of HTML, CSS and Javascript. The most easy way is to copy the &quot;simple&quot; or the &quot;advanced&quot; template and rename it as your own name to for example &quot;mytheme&quot;. After you copy the template you need to change the red sections marked below to &quot;mytheme&quot; this is needed so that themes don't overlap in other words it gives the theme a unique name. Then just alter the HTML code as you see fit but notice some elements needs to be there so check the docs below on each function also remember that your custom themes needs to be located in tiny_mce's &quot;themes&quot; directory. If you want you may add theme specific options/settings but remember to namespace them in the following format &quot;theme_&lt;your theme&gt;_&lt;option&gt;&quot;.
  17 </p>
  18 <div class="separator"></div>
  19 <h3>Theme directory structure</h3>
  20 <p>
  21 <table class="btable">
  22 <thead>
  23         <th>File/Directory</td>
  24         <th>Description</td>
  25 </thead>
  26 <tbody>
  27         <tr><td>css</td><td>Theme specific CSS files</td></tr>
  28         <tr><td>docs</td><td>Theme specific documentation</td></tr>
  29         <tr><td>images</td><td>Theme specific images</td></tr>
  30         <tr><td>jscripts</td><td>Theme specific jscripts for HTML dialogs</td></tr>
  31         <tr><td>langs</td><td>Theme specific language files</td></tr>
  32         <tr><td>editor_template.js</td><td>Editor theme template file (compressed).</td></tr>
  33         <tr><td>editor_template_src.js</td><td>Editor theme template file (source).</td></tr>
  34         <tr><td>somedialog.htm</td><td>Theme specific dialog HTML file.</td></tr>
  35 </table>
  36 </p>
  37 <div class="separator"></div>
  38 <h3>Theme example source</h3>
  39 <p>
  40 The example below shows a simple empty theme and all possible callbacks.
  41 </p>
  42 <p>
  43 <div class="example">
  44 <pre>
  45 var TinyMCE_<span class="marked">SomeName</span>Theme = {
  46         /**
  47          * Returns information about the theme as a name/value array.
  48          * The current keys are longname, author, authorurl, infourl and version.
  49          *
  50          * @returns Name/value array containing information about the theme.
  51          * @type Array
  52          */
  53         getInfo : function() {
  54                 return {
  55                         longname : 'Your Theme',
  56                         author : 'Your name',
  57                         authorurl : 'http://www.yoursite.com',
  58                         infourl : 'http://www.yoursite.com/docs/template.html',
  59                         version : "1.0"
  60                 };
  61         },
  62
  63         /**
  64          * Gets executed when a TinyMCE editor instance is initialized.
  65          *
  66          * @param {TinyMCE_Control} Initialized TinyMCE editor control instance.
  67          */
  68         initInstance : function(inst) {
  69                 // You can take out theme specific parameters
  70                 alert("Initialization parameter:" + tinyMCE.getParam("<span class="marked">somename</span>_someparam", false));
  71
  72                 // Register custom keyboard shortcut
  73                 inst.addShortcut('ctrl', 't', 'lang_<span class="marked">somename</span>_desc', 'mceSomeCommand');
  74         },
  75
  76         /**
  77          * Returns the HTML code for a specific control or empty string if this theme doesn't have that control.
  78          * A control can be a button, select list or any other HTML item to present in the TinyMCE user interface.
  79          * The variable {$editor_id} will be replaced with the current editor instance id and {$themeurl} will be replaced
  80          * with the URL of the theme. Language variables such as {$lang_somekey} will also be replaced with contents from
  81          * the language packs.
  82          *
  83          * @param {string} cn Editor control/button name to get HTML for.
  84          * @return HTML code for a specific control or empty string.
  85          * @type string
  86          */
  87         getControlHTML : function(cn) {
  88                 switch (cn) {
  89                         case "<span class="marked">SomeControl</span>":
  90                                 return tinyMCE.getButtonHTML(cn, 'lang_<span class="marked">sometheme</span>_<span class="marked">button</span>_desc', '{$themeurl}/images/<span class="marked">someimage</span>.gif', '<span class="marked">mceSomeCommand</span>');
  91                 }
  92
  93                 return "";
  94         },
  95
  96         /**
  97          * Returns the HTML code that should be inserted for a specific editor instance.
  98          * This function should return a name/value array with three items html, delta_width, delta_height.
  99          * The html item should contain the HTML code to insert as a editor instance.
 100          * The variable {$editor_id} will be replaced with the current editor instance id and {$themeurl} will be replaced
 101          * with the URL of the theme. Language variables such as {$lang_somekey} will also be replaced with contents from
 102          * the language packs. Any element with the id {$editor_id} will be replaced with the editor iframe element.
 103          * The {$width} and {$height} variables will be replaced with the editors outside dimension values.
 104          * The delta_width/height is the relative width/height in pixels to add or remove from the iframe dimensions.
 105          *
 106          * @param {Array} settings Name/Value array instance settings.
 107          * @param {string} editor_id TinMYCE editor control instance id.
 108          * @return Name/Value array of editor template data.
 109          * @type Array
 110          */
 111         getEditorTemplate : function(settings, editor_id) {
 112                 var html = "";
 113
 114                 // Build toolbar and editor instance
 115                 html += "..";
 116
 117                 return {
 118                         html : html,
 119                         delta_width : 0,
 120                         delta_height : 0
 121                 };
 122         },
 123
 124         /**
 125          * Executes a specific command, this function handles theme commands.
 126          *
 127          * @param {string} editor_id TinyMCE editor instance id that issued the command.
 128          * @param {HTMLElement} element Body or root element for the editor instance.
 129          * @param {string} command Command name to be executed.
 130          * @param {string} user_interface True/false if a user interface should be presented.
 131          * @param {mixed} value Custom value argument, can be anything.
 132          * @return true/false if the command was executed by this theme or not.
 133          * @type
 134          */
 135         execCommand : function(editor_id, element, command, user_interface, value) {
 136                 // Handle commands
 137                 switch (command) {
 138                         // Remember to have the "mce" prefix for commands so they don't intersect with built in ones in the browser.
 139                         case "mce<span class="marked">SomeCommand</span>":
 140                                 // Do your custom command logic here.
 141
 142                                 return true;
 143                 }
 144
 145                 // Pass to next handler in chain
 146                 return false;
 147         },
 148
 149         /**
 150          * Gets called ones the cursor/selection in a TinyMCE instance changes. This is useful to enable/disable
 151          * button controls depending on where the user are and what they have selected. This method gets executed
 152          * alot and should be as performance tuned as possible.
 153          *
 154          * @param {string} editor_id TinyMCE editor instance id that was changed.
 155          * @param {HTMLNode} node Current node location, where the cursor is in the DOM tree.
 156          * @param {int} undo_index The current undo index, if this is -1 custom undo/redo is disabled.
 157          * @param {int} undo_levels The current undo levels, if this is -1 custom undo/redo is disabled.
 158          * @param {boolean} visual_aid Is visual aids enabled/disabled ex: dotted lines on tables.
 159          * @param {boolean} any_selection Is there any selection at all or is there only a cursor.
 160          */
 161         handleNodeChange : function(editor_id, node, undo_index, undo_levels, visual_aid, any_selection) {
 162         },
 163
 164         /**
 165          * Gets called when a TinyMCE editor instance gets filled with content on startup.
 166          *
 167          * @param {string} editor_id TinyMCE editor instance id that was filled with content.
 168          * @param {HTMLElement} body HTML body element of editor instance.
 169          * @param {HTMLDocument} doc HTML document instance.
 170          */
 171         setupContent : function(editor_id, body, doc) {
 172         },
 173
 174         /**
 175          * Gets called when the contents of a TinyMCE area is modified, in other words when a undo level is
 176          * added.
 177          *
 178          * @param {TinyMCE_Control} inst TinyMCE editor area control instance that got modified.
 179          */
 180         onChange : function(inst) {
 181         },
 182
 183         /**
 184          * Gets called when TinyMCE handles events such as keydown, mousedown etc. TinyMCE
 185          * doesn't listen on all types of events so custom event handling may be required for
 186          * some purposes.
 187          *
 188          * @param {Event} e HTML editor event reference.
 189          * @return true - pass to next handler in chain, false - stop chain execution
 190          * @type boolean
 191          */
 192         handleEvent : function(e) {
 193                 return true;
 194         },
 195
 196         /**
 197          * Gets called when HTML contents is inserted or retrived from a TinyMCE editor instance.
 198          * The type parameter contains what type of event that was performed and what format the content is in.
 199          * Possible valuses for type is get_from_editor, insert_to_editor, get_from_editor_dom, insert_to_editor_dom.
 200          *
 201          * @param {string} type Cleanup event type.
 202          * @param {mixed} content Editor contents that gets inserted/extracted can be a string or DOM element.
 203          * @param {TinyMCE_Control} inst TinyMCE editor instance control that performes the cleanup.
 204          * @return New content or the input content depending on action.
 205          * @type string
 206          */
 207         cleanup : function(type, content, inst) {
 208                 return content;
 209         },
 210
 211         // Private theme internal methods
 212
 213         /**
 214          * This is just a internal theme method, prefix all internal methods with a _ character.
 215          * The prefix is needed so they doesn't collide with future TinyMCE callback functions.
 216          *
 217          * @param {string} a Some arg1.
 218          * @param {string} b Some arg2.
 219          * @return Some return.
 220          * @type string
 221          */
 222         _someInternalFunction : function(a, b) {
 223                 return 1;
 224         }
 225 };
 226
 227 // Adds the theme class to the list of available TinyMCE themes
 228 tinyMCE.addTheme("<span class="marked">sometheme</span>", TinyMCE_<span class="marked">SomeTheme</span>Theme);
 229 </pre>
 230 </div>
 231 </p>
 232 <div class="separator"></div>
 233
 234 <h3>Creating popup HTML files</h3>
 235 <p>
 236 When creating a popup you need to include the &quot;tiny_mce_popup.js&quot; this enables you to retrive the tinyMCE global instance in all popup windows. All variables and language definitions gets replaced in the page when it loads. So language variables such as {$lang_something} can be places in the HTML code, if you need to get a language string in JavaScript simply use the tinyMCE.getLang function.
 237 </p>
 238 <h3>Example of simple popup file:</h3>
 239 <div class="example">
 240 <pre>
 241 &lt;html&gt;
 242 &lt;head&gt;
 243 &lt;title&gt;{$lang_theme_sample_title}&lt;/title&gt;
 244 &lt;script language=&quot;javascript&quot; src=&quot;../../tiny_mce_popup.js&quot;&gt;&lt;/script&gt;
 245 &lt;script language=&quot;javascript&quot;&gt;
 246      // getWindowArg returns any arguments passed to the window
 247      alert(tinyMCE.getWindowArg('some_arg'));
 248 &lt;/script&gt;
 249 &lt;body&gt;
 250      &lt;strong&gt;{$lang_theme_sample_desc}&lt;/strong&gt;
 251 &lt;/body&gt;
 252 </pre>
 253 </div>
 254
 255 <div class="footer">
 256         <div class="helpindexlink"><a href="index.html">Index</a></div>
 257         <div class="copyright">Copyright &copy; 2003-2006 <a href="http://www.moxiecode.com">Moxiecode Systems AB</a></div>
 258         <br style="clear: both" />
 259 </div>
 260
 261 </body>
 262 </html>