wiki:Documentation/NewbieGuide

Version 2 (modified by gogo, 5 months ago) (diff)

--

This is the New Newbie Guide, for versions of Xinha prior 1.0, please see the OldNewbieGuide


Newbie Guide, or, How To Put Xinha On Your Page

Including 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> !

One Line To Xinha

Assuming 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.

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js"></script>

Optionally Convert Only Certain <textarea>

You muight want to be a bit more picky about which textareas get converted, some simple configuration will see to it,

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      xinha_editors:  'textarea.some-css-class'
    }
  </script>

now 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.

Optionally Set the Language and Skin

We can easily set the language and skin to your desire with some more options

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class'
    }
  </script>

The options for 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.

The options for Skins are those here, use the folder name as the skin name.

Optionally Specify Some Plugins

Xinha uses a system of 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...

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class',
      xinha_plugins:  [ 'minimal', 'TableOperations' ]
    }
  </script>

here we have specified that in addition to the 'minimal' set of plugins, we also want TableOperations which provides more complete table editing functions.

Optionally Specify A Toolbar

The 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).

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class',
      xinha_plugins:  'minimal',
      xinha_toolbar:  'supermini'
    }
  </script>

Here we have specified this is going to be an extremely minimal editor indeed!

Optionally Specify A Stylesheet

To 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...

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class',
      xinha_plugins:  'minimal',
      xinha_toolbar:  'supermini',
      xinha_stylesheet: '/path/to/your/styles.css'
    }
  </script>

Optionally Provide Some Configuration

Xinha 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...

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class',
      xinha_plugins:  'minimal',
      xinha_toolbar:  'supermini',
      xinha_stylesheet: '/path/to/your/styles.css',

      xinha_config:   function(xinha_config)
      {
        xinha_config.resizableEditor = true;
      }
    }
  </script>

here 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).

Optionally Provide Different Configuration For A Specific Editor

There might be times when you want to give a different configuration to certain editors than to certain others, we can do that no problem...

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class',
      xinha_plugins:  'minimal',
      xinha_toolbar:  'supermini',
      xinha_stylesheet: '/path/to/your/styles.css',

      xinha_config:   function(xinha_config)
      {
        xinha_config.resizableEditor = true;
      },

      xinha_config_specific:   function(xinha_config, textarea)
      {
        if(textarea.className.match(/for-email/))
        {
          xinha_config.sevenBitClean = false;
        }
      }
    }
  </script>

here 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).

Optionally Disable Some Plugins For A Specific Editor

It might be the case that you want certain editors not to have some plugins, we can sort that out...

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class',
      xinha_plugins:  ['minimal', 'TableOperations'],
      xinha_toolbar:  'supermini',
      xinha_stylesheet: '/path/to/your/styles.css',

      xinha_config:   function(xinha_config)
      {
        xinha_config.resizableEditor = true;
      },

      xinha_config_specific:   function(xinha_config, textarea)
      {
        if(textarea.className.match(/for-email/))
        {
          xinha_config.sevenBitClean = false;
        }
      },

      xinha_plugins_specific:   function(xinha_plugins, textarea)
      {
        if(textarea.className.match(/for-email/))
        {
          xinha_plugins.remove('TableOperations'); 
        }
      }
    }
  </script>

here we have removed TableOperations? from the for-email editor.

Optionally Set The Toolbar For A Specific Editor

It 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...

  <script type="text/javascript" src="//s3-us-west-1.amazonaws.com/xinha/xinha-1.5-beta1/XinhaEasy.js">
    xinha_options =
    {
      _editor_lang:   'fr',
      _editor_skin:   'blue-look',
      xinha_editors:  'textarea.some-css-class',
      xinha_plugins:  ['minimal', 'TableOperations'],
      xinha_toolbar:  'supermini',
      xinha_stylesheet: '/path/to/your/styles.css',

      xinha_config:   function(xinha_config)
      {
        xinha_config.resizableEditor = true;
      },

      xinha_config_specific:   function(xinha_config, textarea)
      {
        if(textarea.className.match(/for-email/))
        {
          xinha_config.sevenBitClean = false;
        }

        if(textarea.className.match(/full-tools/))
        {
          xinha_config.setToolbar('default');
        }
      },

      xinha_plugins_specific:   function(xinha_plugins, textarea)
      {
        if(textarea.className.match(/for-email/))
        {
          xinha_plugins.remove('TableOperations'); 
        }
      }
    }
  </script>

here we have decided that the texarea with 'full-tools' class name should get the default toolbar.