[Sommaire] [Imprimer]

   1  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2  <html>
   3  <head>
   4  <title>Customization - Creating a plugin</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 plugin</h1>
  11  </div>
  12  
  13  <div class="content">
  14      
  15  <h2>Creating your own plugins</h2>
  16  <p>
  17  Creating you own plugins 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;_template&quot; directory or one of the other core plugins and work from there. The &quot;_template&quot; directory is a tutorial plugin that shows how to create a plugin. After you copy the template you need to change the red sections marked below to the name of your plugin this is needed so that plugins don't overlap in other words it gives the plugin a unique name. Then just alter the source code as you see fit remember that your custom plugins needs to be located in tiny_mce's &quot;plugins&quot; directory. If you want you may add plugin specific options/settings but remember to namespace them in the following format &quot;&lt;your plugin&gt;_&lt;option&gt;&quot; for example &quot;yourplugin_someoption&quot;.
  18  </p>
  19  <p>
  20  The example below has three functions, these are explained in greater detail below.
  21  </p>
  22  <p>
  23  <div class="example">
  24  <pre>
  25  function TinyMCE_<span class="marked">yourplugin</span>_initInstance(inst) {
  26      // Gets executed when a editor instance is initialized
  27  }
  28  
  29  function TinyMCE_<span class="marked">yourplugin</span>_getControlHTML(control_name) {
  30      // Gets executed when a button is to be generated
  31  }
  32  
  33  function TinyMCE_<span class="marked">yourplugin</span>_handleNodeChange(editor_id, node, undo_index, undo_levels, visual_aid, any_selection) {
  34     // Gets executed when the selection changes
  35  }
  36  
  37  function TinyMCE_<span class="marked">yourplugin</span>_execCommand(editor_id, element, command, user_interface, value) {
  38     // Add your own custom commands here
  39  
  40     return false;
  41  }
  42  
  43  function TinyMCE_<span class="marked">yourplugin</span>_cleanup(type, content) {
  44      // Add your own custom cleanup here
  45  
  46      return content;
  47  }
  48  </pre>
  49  </div>
  50  </p>
  51  
  52  <div class="separator"></div>
  53  
  54  <h3>Creating popup HTML files</h3>
  55  <p>
  56  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.
  57  </p>
  58  <h3>Example of simple popup file:</h3>
  59  <div class="example">
  60  <pre>
  61  &lt;html&gt;
  62  &lt;head&gt;
  63  &lt;title&gt;{$lang_plugin_sample_title}&lt;/title&gt;
  64  &lt;script language=&quot;javascript&quot; src=&quot;../../tiny_mce_popup.js&quot;&gt;&lt;/script&gt;
  65  &lt;script language=&quot;javascript&quot;&gt;
  66       // getWindowArg returns any arguments passed to the window
  67       alert(tinyMCE.getWindowArg('some_arg'));
  68  &lt;/script&gt;
  69  &lt;body&gt;
  70       &lt;strong&gt;{$lang_plugin_sample_desc}&lt;/strong&gt;
  71  &lt;/body&gt;
  72  </pre>
  73  </div>
  74  
  75  <div class="separator"></div>
  76  
  77  <h3>The TinyMCE_&lt;plugin&gt;_initInstance function (Optional)</h3>
  78  <p>
  79      This function is called when a editor instance gets initialized.
  80  </p>
  81  <p>
  82      <table border="1" cellspacing="0" cellpadding="4">
  83      <thead>
  84          <tr>
  85              <td colspan="2">Parameters</td>
  86          </tr>
  87      </thead>
  88      <tbody>
  89          <tr>
  90              <td><strong>inst</strong></td>
  91              <td>Reference to editor instance that was initialized.</td>
  92          </tr>
  93      </tbody>
  94      </table>
  95  </p>
  96  
  97  
  98  <div class="separator"></div>
  99  
 100  <h3>The TinyMCE_&lt;plugin&gt;_handleNodeChange function (Optional)</h3>
 101  <p>
 102  This function is called when the cursor/selection of a editor instance changes. Then the currenly selected/focused node is passed to this function. This can be useful when you want to change the UI depending on what the user has selected.
 103  </p>
 104  <p>
 105  <table border="1" cellspacing="0" cellpadding="4">
 106  <thead>
 107  <tr>
 108      <td colspan="2">Parameters</td>
 109  </tr>
 110  </thead>
 111  <tbody>
 112  <tr>
 113      <td><strong>editor_id</strong></td>
 114      <td>Unique editor id, this is the same as the $editor_id variable in getEditorTemplate.</td>
 115  </tr>
 116  <tr>
 117      <td><strong>node</strong></td>
 118      <td>Reference to the Node element where the cursor is currenly located.</td>
 119  </tr>
 120  <tr>
 121      <td><strong>undo_index</strong></td>
 122      <td>Current undo index, this value is -1 if the custom undo/redo support is disabled.</td>
 123  </tr>
 124  <tr>
 125      <td><strong>undo_levels</strong></td>
 126      <td>Current number of undo levels, this value is -1 if the custom undo/redo support is disabled.</td>
 127  </tr>
 128  <tr>
 129      <td><strong>visual_aid</strong></td>
 130      <td>True/false state of visual aid/guidelines mode.</td>
 131  </tr>
 132  <tr>
 133      <td><strong>any_selection</strong></td>
 134      <td>Is any text or image selected.</td>
 135  </tr>
 136  </tbody>
 137  </table>
 138  </p>
 139  
 140  <div class="separator"></div>
 141  
 142  <h3>The TinyMCE_&lt;plugin&gt;_execCommand function (Optional)</h3>
 143  <p>
 144  This function is called when a command is executed for example &quot;bold&quot; or &quot;createlink&quot; this callback/plugin function may then intercept plugin specific commands and do custom logic. If this command returns true the command handling is terminated and the default tinyMCE command handeling never gets executed.
 145  </p>
 146  <p>
 147  <table border="1" cellspacing="0" cellpadding="4">
 148  <thead>
 149  <tr>
 150      <td colspan="2">Parameters</td>
 151  </tr>
 152  </thead>
 153  <tbody>
 154  <tr>
 155      <td><strong>editor_id</strong></td>
 156      <td>Unique editor id, this is the same as the $editor_id variable in getEditorTemplate.</td>
 157  </tr>
 158  <tr>
 159      <td><strong>element</strong></td>
 160      <td>Reference to the document DOM root element of the editor instance.</td>
 161  </tr>
 162  <tr>
 163      <td><strong>command</strong></td>
 164      <td>Command that is to be executed for example &quot;myCommand&quot;.</td>
 165  </tr>
 166  <tr>
 167      <td><strong>user_interface</strong></td>
 168      <td>true/false option if a user insterace is to be used or not.</td>
 169  </tr>
 170  <tr>
 171      <td><strong>value</strong></td>
 172      <td>Custom data value passed with command, may be any data type.</td>
 173  </tr>
 174  </tbody>
 175  </table>     
 176  </p>
 177  <p>
 178  Returns: <br />
 179  true - Command intercepted and handled do not continue with command handling.<br />
 180  false - Continue with execCommand handling, bubble.<br />
 181  </p>
 182  
 183  <div class="separator"></div>
 184  
 185  <h3>The TinyMCE_&lt;plugin&gt;_getControlHTML(control_name) function (Optional)</h3>
 186  <p>
 187  This function is called when a editor needs to render a specific control/button. This function should return the HTML template of that control or a empty string if the control_name wasn't recognized. Notice the variable {$pluginurl} gets replaced with the URL prefix for the current plugin directory.
 188  </p>
 189  <p>
 190  <table border="1" cellspacing="0" cellpadding="4">
 191  <thead>
 192  <tr>
 193      <td colspan="2">Parameters</td>
 194  </tr>
 195  </thead>
 196  <tbody>
 197  <tr>
 198      <td><strong>control_name</strong></td>
 199      <td>Control name to match against.</td>
 200  </tr>
 201  </tbody>
 202  </table>
 203  </p>
 204  <p>
 205  Returns: return the HTML template of that control or a empty string if the control_name wasn't recognized. 
 206  </p>
 207  <h3>The TinyMCE_&lt;plugin&gt;_cleanup(type, content) function (Optional)</h3>
 208  <p>
 209  This function is called when a editor does cleanup of contents. This function has the same format as the one defined in the <a href="option_cleanup_callback.html">cleanup_callback</a> option.
 210  </p>
 211  <p>
 212  <table border="1" cellspacing="0" cellpadding="4">
 213  <thead>
 214  <tr>
 215      <td colspan="2">Parameters</td>
 216  </tr>
 217  </thead>
 218  <tbody>
 219  <tr>
 220      <td><strong>type</strong></td>
 221      <td>Type of cleanup, insert_to_editor or get_from_editor. Insert to editor is passed when new content is placed within the editor and get_from_editor is when content is passed out from the editor. When dealing with the DOM representation of the same content insert_to_editor_dom or get_from_editor_dom gets passed as a type.</td>
 222  </tr>
 223  <tr>
 224      <td><strong>content</strong></td>
 225      <td>HTML contents to be cleaned up, this string contains the HTML code or with the _dom types the body DOM object gets passed instead.</td>
 226  </tr>
 227  </tbody>
 228  </table>
 229  </p>
 230  <p>
 231  Returns: return the cleaned up HTML code.
 232  </p>
 233  
 234  </div>
 235  
 236  <div class="footer">
 237      <div class="helpindexlink"><a href="index.html">Index</a></div>
 238      <div class="copyright">Copyright &copy; 2005 Moxiecode Systems AB</div>
 239      <br style="clear: both" />
 240  </div>
 241  
 242  </body>
 243  </html>