lib/editor/neweditor_readme.txt

   1 editorObject README
   2 ===================
   3
   4 Quick specs
   5 ===========
   6
   7 Quick specs for new editor integration class.
   8 This new integration method lets user choose which editor to use if
   9 user chooses to use WYSIWYG editor (HTMLArea or TinyMCE).
  10
  11 There are legacy code for backward compatibilty in case that modules are not
  12 upgraded for both editors. In such case only HTMLArea is available.
  13 Structure implemented with factory design pattern:
  14
  15     * /lib
  16           o editorlib.php
  17     * /lib/editor
  18           o htmlarea
  19                 + htmlarea.class.php
  20           o tinymce
  21                 + tinymce.class.php
  22
  23 Usage:
  24
  25 Editor scripts must be loaded before print_header() function call and
  26 only required variable is course id. To load editor you can use wrapper
  27 function located in moodlelib.php called loadeditor().
  28
  29     if ( $usehtmleditor = can_use_html_editor() ) {
  30         $editor = loadeditor($course->id);
  31     }
  32
  33 This will push needed scripts to global $CFG->editorsrc array which will be
  34 printed out in /lib/javascript.php.
  35 And at the bottom of the page before print_footer() function,
  36 we'll startup the editor almost as usual:
  37
  38     if ( $usehtmleditor ) {
  39         $editor->use_html_editor();
  40     }
  41
  42 After $editor->use_html_editor() -method is called $CFG->editorsrc array is cleared,
  43 so these scripts are loaded only when necessary.
  44
  45 Special usage
  46 =============
  47
  48 In some rare cases programmer needs to force certain settings. If you don't want to
  49 take care of both editor's settings you can force your module to use one editor only.
  50 In that case you'll have to pass an associative array as an argument
  51 for loadeditor function:
  52
  53
  54     $args = array('courseid' => $course->id, 'name' => 'tinymce');
  55     $editor = loadeditor($args);
  56
  57 Then you can define settings for the editor that you wish to use. For setting up new
  58 settings use setconfig() method:
  59
  60     Tiny example1:
  61
  62     $editor->setconfig('mode','exact');
  63     $editor->setconfig('elements','mytextarea');
  64     $editor->setconfig('plugins','advhr,table,flash');
  65
  66     // Merge config to defaults and startup the editor.
  67     $editor->starteditor('merge');
  68
  69     Tiny example2:
  70
  71     $args['mode'] = 'exact';
  72     $args['elements'] = 'mytextarea';
  73
  74     $args['plugins'] = 'advhr,table,flash';
  75
  76     // merge config to defaults and startup the editor.
  77     $editor->starteditor('merge');
  78
  79     HTMLArea example1:
  80
  81     $toolbar = array(
  82                 array("fontname","fontsize","separator","undo","redo"),
  83                 array("cut","copy","paste","separator","fullscreen")
  84                );
  85     $editor->setconfig('toolbar', $toolbar);
  86     $editor->setconfig('killWordOnPaste', false);
  87     $editor->starteditor('merge');
  88
  89     HTMLArea example2:
  90
  91     $args['toolbar'] = array(
  92                            array("fontname","fontsize","separator","undo","redo"),
  93                            array("cut","copy","paste","separator","fullscreen")
  94                        );
  95     $args['killWordOnPaste'] = false;
  96     $args['pageStyle'] = "body { font-family: Verdana; font-size: 10pt; }";
  97
  98     $editor->setconfig($args);
  99
 100     // Print only these settings and start up the editor.
 101     $editor->starteditor();
 102
 103 There are three possible arguments for starteditor method. Which are:
 104 append, merge and default.
 105
 106  append: Leave default values untouched if overlapping settings are found.
 107   merge: Override default values if same configuration settings are found.
 108 default: Use only default settings.
 109
 110 If none of these options is present then only those settings are used what
 111 you've set with setsetting method.
 112
 113
 114
 115 TinyMCE configuration options
 116 =============================
 117
 118 You can find full list of configuration options and possible values
 119 at http://tinymce.moxiecode.com/tinymce/docs/reference_configuration.html
 120
 121 HTMLArea configuration options
 122 ==============================
 123
 124 Possible configuration options for HTMLArea are:
 125
 126  width (string)
 127  **************
 128  Width of the editor as a string. Example: "100%" or "250px".
 129
 130  height (string)
 131  ***************
 132  Height of the editor as a string. Example: "100%" or "150px".
 133
 134  statusBar (boolean)
 135  *******************
 136  Print out statusbar or not. Example: true or false.
 137
 138  undoSteps (integer)
 139  *******************
 140  Amount of undo steps to hold in memory. Default is 20.
 141
 142  undoTimeout (integer)
 143  *********************
 144  The time interval at which undo samples are taken. Default 500 (1/2 sec).
 145
 146  sizeIncludesToolbar (boolean)
 147  *****************************
 148  Specifies whether the toolbar should be included in the size or not.
 149  Default is true.
 150
 151  fullPage (boolean)
 152  ******************
 153  If true then HTMLArea will retrieve the full HTML, starting with the
 154  <HTML> tag. Default is false.
 155
 156  pageStyle (string)
 157  ******************
 158  Style included in the iframe document.
 159  Example: "body { background-color: #fff; font-family: 'Times New Roman', Times; }".
 160
 161  killWordOnPaste (boolean)
 162  *************************
 163  Set to true if you want Word code to be cleaned upon Paste. Default is true.
 164
 165  toolbar (array of arrays)
 166  *************************
 167  Buttons to print in toolbar. Must be array of arrays.
 168  Example: array(array("Fontname","fontsize"), array("cut","copy","paste"));
 169  Will print toolbar with two rows.
 170
 171  fontname (associative array)
 172  ****************************
 173  Fontlist for fontname drowdown list.
 174  Example: array("Arial" => "arial, sans-serif", "Tahoma", "tahoma,sans-serif");
 175
 176  fontsize (associative array)
 177  ****************************
 178  Fontsizes for fontsize dropdown list.
 179  Example: array("1 (8pt)" => "1", "2 (10pt)" => "2");
 180
 181  formatblock (associative array)
 182  *******************************
 183  An associative array of formatting options for formatblock dropdown list.
 184  Example: array("Heading 1" => "h1", "Heading 2" => "h2");
 185
 186
 187 To be continue...
 188
 189 $Id$