Changes between Version 1 and Version 2 of Documentation/NewbieGuide


Ignore:
Timestamp:
02/23/18 00:53:13 (14 months ago)
Author:
gogo
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/NewbieGuide

    v1 v2  
    11This is the New Newbie Guide, for versions of Xinha prior 1.0, please see the OldNewbieGuide 
    22 
     3 
     4---- 
     5 
     6 
     7== Newbie Guide, or, How To Put Xinha On Your Page == 
     8 
     9Including one or more Xinha areas on your page has been made very easy, in fact for defaults it's as simple as adding one line to your `<head>` ! 
     10 
     11=== One Line To Xinha === 
     12 
     13Assuming that your page contains one or more `<textarea>` that you wish to turn into Xinha areas, and you just want default options, then this is all you need. 
     14 
     15{{{ 
     16  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"></script> 
     17}}} 
     18 
     19=== Optionally Convert Only Certain `<textarea>` === 
     20 
     21You muight want to be a bit more picky about which textareas get converted, some simple configuration will see to it, 
     22 
     23{{{ 
     24  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     25    xinha_options = 
     26    { 
     27      xinha_editors:  'textarea.some-css-class' 
     28    } 
     29  </script> 
     30}}} 
     31 
     32now only `<textarea class="some-css-class"></textarea>` will be converted.  You can use multiple and full CSS selectors as you desire, just like you would for writing CSS rulesets. 
     33 
     34=== Optionally Set the Language and Skin === 
     35 
     36We can easily set the language and skin to your desire with some more options 
     37 
     38{{{ 
     39  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     40    xinha_options = 
     41    { 
     42      _editor_lang:   'fr', 
     43      _editor_skin:   'blue-look', 
     44      xinha_editors:  'textarea.some-css-class' 
     45    } 
     46  </script> 
     47}}} 
     48 
     49The options for [[/browser/trunk/lang|Languages are those provided by the lang files here]] - for example for French use 'fr' - note that Languages other than English ('en', the default) may be in various states of completeness, untranslated things will revert to English, if you would like to help with translating DownloadXinha and see the READEME_TRANSLATORS.TXT file. 
     50 
     51The options for [[/browser/trunk/skins|Skins are those here]], use the folder name as the skin name. 
     52 
     53=== Optionally Specify Some Plugins === 
     54 
     55Xinha uses a system of [[/browser/trunk/plugins|Plugins]] to provide extra functionality.  The default is to use a set of those plugins which are most commonly useful, but you can also specify a list of plugins, or the set names 'minimal', 'common', and 'loaded' (which means use a whole bunch more plugins that might be less useful commonly) or a combination there-of with a simple option... 
     56 
     57 
     58{{{ 
     59  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     60    xinha_options = 
     61    { 
     62      _editor_lang:   'fr', 
     63      _editor_skin:   'blue-look', 
     64      xinha_editors:  'textarea.some-css-class', 
     65      xinha_plugins:  [ 'minimal', 'TableOperations' ] 
     66    } 
     67  </script> 
     68}}} 
     69 
     70here we have specified that in addition to the 'minimal' set of plugins, we also want `TableOperations` which provides more complete table editing functions. 
     71 
     72=== Optionally Specify A Toolbar === 
     73 
     74The toolbar (buttons and drop-down selectors) can be customised easily using the `xinha_toolbar` option, it accepts either one of the keywords `default`, `minimal`, `minimal+fonts`, `supermini` (it can also accept a toolbar structure but we will leave that for another time). 
     75 
     76{{{ 
     77  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     78    xinha_options = 
     79    { 
     80      _editor_lang:   'fr', 
     81      _editor_skin:   'blue-look', 
     82      xinha_editors:  'textarea.some-css-class', 
     83      xinha_plugins:  'minimal', 
     84      xinha_toolbar:  'supermini' 
     85    } 
     86  </script> 
     87}}} 
     88 
     89Here we have specified this is going to be an extremely minimal editor indeed! 
     90 
     91=== Optionally Specify A Stylesheet === 
     92 
     93To make Xinha a real WYSIWYG editor you should also load a stylesheet into it that will give your users the "look" of what they are typing as it would appear on the website, again it's just an option away... 
     94 
     95{{{ 
     96  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     97    xinha_options = 
     98    { 
     99      _editor_lang:   'fr', 
     100      _editor_skin:   'blue-look', 
     101      xinha_editors:  'textarea.some-css-class', 
     102      xinha_plugins:  'minimal', 
     103      xinha_toolbar:  'supermini', 
     104      xinha_stylesheet: '/path/to/your/styles.css' 
     105    } 
     106  </script> 
     107}}} 
     108 
     109 
     110=== Optionally Provide Some Configuration === 
     111 
     112Xinha and it's plugins have lots of scope to configure them as you require, we won't cover all the configuration settings here but this is how you can do it... 
     113 
     114 
     115{{{ 
     116  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     117    xinha_options = 
     118    { 
     119      _editor_lang:   'fr', 
     120      _editor_skin:   'blue-look', 
     121      xinha_editors:  'textarea.some-css-class', 
     122      xinha_plugins:  'minimal', 
     123      xinha_toolbar:  'supermini', 
     124      xinha_stylesheet: '/path/to/your/styles.css', 
     125 
     126      xinha_config:   function(xinha_config) 
     127      { 
     128        xinha_config.resizableEditor = true; 
     129      } 
     130    } 
     131  </script> 
     132}}} 
     133 
     134here we have turned on the ability for the user to click-drag resize the editor (note that this only works well in Chrome and Safari). 
     135 
     136=== Optionally Provide Different Configuration For A Specific Editor === 
     137 
     138There might be times when you want to give a different configuration to certain editors than to certain others, we can do that no problem... 
     139 
     140{{{ 
     141  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     142    xinha_options = 
     143    { 
     144      _editor_lang:   'fr', 
     145      _editor_skin:   'blue-look', 
     146      xinha_editors:  'textarea.some-css-class', 
     147      xinha_plugins:  'minimal', 
     148      xinha_toolbar:  'supermini', 
     149      xinha_stylesheet: '/path/to/your/styles.css', 
     150 
     151      xinha_config:   function(xinha_config) 
     152      { 
     153        xinha_config.resizableEditor = true; 
     154      }, 
     155 
     156      xinha_config_specific:   function(xinha_config, textarea) 
     157      { 
     158        if(textarea.className.match(/for-email/)) 
     159        { 
     160          xinha_config.sevenBitClean = false; 
     161        } 
     162      } 
     163    } 
     164  </script> 
     165}}} 
     166 
     167here we have decided that any textarera with class "for-email" (which also has "some-css-class" in the first place causing it to be selected for conversion) should be configured as "sevenBitClean" (which means that only 7 bit characters are used in the output). 
     168 
     169=== Optionally Disable Some Plugins For A Specific Editor === 
     170 
     171It might be the case that you want certain editors not to have some plugins, we can sort that out... 
     172 
     173{{{ 
     174  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     175    xinha_options = 
     176    { 
     177      _editor_lang:   'fr', 
     178      _editor_skin:   'blue-look', 
     179      xinha_editors:  'textarea.some-css-class', 
     180      xinha_plugins:  ['minimal', 'TableOperations'], 
     181      xinha_toolbar:  'supermini', 
     182      xinha_stylesheet: '/path/to/your/styles.css', 
     183 
     184      xinha_config:   function(xinha_config) 
     185      { 
     186        xinha_config.resizableEditor = true; 
     187      }, 
     188 
     189      xinha_config_specific:   function(xinha_config, textarea) 
     190      { 
     191        if(textarea.className.match(/for-email/)) 
     192        { 
     193          xinha_config.sevenBitClean = false; 
     194        } 
     195      }, 
     196 
     197      xinha_plugins_specific:   function(xinha_plugins, textarea) 
     198      { 
     199        if(textarea.className.match(/for-email/)) 
     200        { 
     201          xinha_plugins.remove('TableOperations');  
     202        } 
     203      } 
     204    } 
     205  </script> 
     206}}} 
     207 
     208here we have removed TableOperations from the for-email editor. 
     209 
     210=== Optionally Set The Toolbar For A Specific Editor === 
     211 
     212It might be the case that you want some editor to have a differnet toolbar than others, we can do this by adjusting that editor's configuration... 
     213 
     214{{{ 
     215  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"> 
     216    xinha_options = 
     217    { 
     218      _editor_lang:   'fr', 
     219      _editor_skin:   'blue-look', 
     220      xinha_editors:  'textarea.some-css-class', 
     221      xinha_plugins:  ['minimal', 'TableOperations'], 
     222      xinha_toolbar:  'supermini', 
     223      xinha_stylesheet: '/path/to/your/styles.css', 
     224 
     225      xinha_config:   function(xinha_config) 
     226      { 
     227        xinha_config.resizableEditor = true; 
     228      }, 
     229 
     230      xinha_config_specific:   function(xinha_config, textarea) 
     231      { 
     232        if(textarea.className.match(/for-email/)) 
     233        { 
     234          xinha_config.sevenBitClean = false; 
     235        } 
     236 
     237        if(textarea.className.match(/full-tools/)) 
     238        { 
     239          xinha_config.setToolbar('default'); 
     240        } 
     241      }, 
     242 
     243      xinha_plugins_specific:   function(xinha_plugins, textarea) 
     244      { 
     245        if(textarea.className.match(/for-email/)) 
     246        { 
     247          xinha_plugins.remove('TableOperations');  
     248        } 
     249      } 
     250    } 
     251  </script> 
     252}}} 
     253 
     254here we have decided that the texarea with 'full-tools' class name should get the default toolbar.