Home Demo Downloads Release Notes Documentation
Report Bug FAQ Screenshots Forum Archive Developers

Core Configuration Options

The following options can be specified to control the core features of Xinha.

** See the NewbieGuide for how to set configuration values in general. **

width: Set the width of the editor, allowed values ‘auto’, ‘toolbar’ or a CSS length specification (123px).
height: Set the height of the editor, allowed values ‘auto’ or a CSS length specification (123px).
resizableEditor: Boolean. Allow the user to drag-resize the editor. This only works reliably in Chrome, other browsers have various issues.
sizeIncludesBars: Boolean. include the toolbars in the size specified. Default true.
sizeIncludesPanels: Boolean. Include the panels in the size specified. Default true.
panelDimensions: Object. Specify the panel dimensions for left/right/top/bottom, pixel widths only.

  xinha_config.panel_dimensions =
  {
    left:   '200px', // Width
    right:  '200px',
    top:    '100px', // Height
    bottom: '100px'
  };

iframeWidth: Integer. If you want the iframe to be narrower than toolbar, set this to a number of pixels. Eg if you are editing a very narrow column of text and want to maintain that narrowness in the editor.
statusBar: Boolean. Enable the status bar at the bottom of the editor. Default true.
htmlareaPaste: Boolean. Intercept CTRL-V and do paste through Xinha’s processes. This probably doesn’t work at least in Gecko. Default false.
mozParaHandler: String ‘built-in’ or ‘best’. For browsers that use Xinha’s Gecko engine (primarily, Firefox and IE11), determine how the return key is handled. Default ‘best’.
getHtmlMethod: String ‘DOMwalk’ or ‘TransformInnerHTML’. Determines the algorithm for generating the HTML from the WYWISYG view. ‘DOMwalk’ may be more reliable, ‘TransformInnerHTML’ may be faster (but in modern times this is not so certain I suspect). Default ‘DOMwalk’.
undoSteps: Integer. Number of undos available. Default 20.
undoTimeout: Integer milliseconds. Interval that undo snapshots are saved. Default 500.
changeJustifyWithDirection: Boolean. When changing to right-to-left, select right justification. Default false.
fullPage: Boolean. If true then Xinha will retrieve the full HTML, starting with the <HTML> tag. Not well tested, see also FullPage plugin.
pageStyle: String. CSS definitions to apply to the edited document. See also pageStyleSheets below, and Stylist plugin.

     xinha_config.pageStyle = '  p { color:red;  }  \n' 
                            + ' li { color:blue; }';

pageStyleSheets: Array of string. An array of external stylesheets to apply to the edited document.

     xinha_config.pageStyleSheets = [ "/css/myPagesStyleSheet.css","/css/anotherOne.css" ];

baseHref: String. Base href to apply to relative links. ** This is probably buggy. You shouldn’t need to use it. **
expandRelativeUrl: Boolean. Relative URLs will be made absolute. This is usually a good thing due to browser behaviours with regard editing images etc. Default true.
stripBaseHref: Boolean. Remove the baseHref (above if set) from urls in the edited content. Default true (if baseHref is set).
stripSelfNamedAnchors: Boolean. Remove the url part from any anchors which have ourself as an anchor. Typically a good thing (editing index.html, index.html#top becomes #top). Default true.
only7BitPrintablesInURLs: Boolean. In URLs all characters above ASCII value 127 have to be encoded using % codes. Default true.
sevenBitClean: Boolean. If you are putting the HTML written in Xinha into an email you might want it to be 7-bit characters only. This config option will convert all characters consuming more than 7bits into UNICODE decimal entity references (actually it will convert anything below (chr 20) except cr, lf and tab and above (~, chr 7E)). Default: false.
specialReplacements: Object. Display one thing in the WYSIWYG view and translate it to a different thing in the HTML view. Potential use as showing some example text in the WYSIWYG view but using a “replacement code” in the HTML generated. Default empty.

     xinha_config.specialReplacements = 
     { 
       'in_html' : 'in_wysiwyg',
       '{$Name}' : 'John Smith',
     };

tabSpanClass: String. When the user presses the tab key in the editor, Xinha will insert a span with this class and the below contents. Default ‘xinha-tab’
tabSpanContents: String. When the user presses the tab key, Xinha will insert a span with the above class and this contents. Default ‘ ’.
inwardHtml: Function accepting parameter html and returning html to use in the editor. This is called with the contents of the textarea and the result is what is inserted into the Xinha editor for editing. Default, null function.

      xinha_config.inwardHtml = function(html) { return html.replace(/how now brown cow/, 'how now yellow camel'); }

Makes <textarea>how now brown cow</textarea> edit a Xinha document with the text "how now yellow camel" instead.

outwardHtml: Function accepting parameter html and returning html to return to the textarea. This is called before putting the edited html back into the textarea.

      xinha_config.inwardHtml = function(html) { return html.replace(/how now yellow camel/, 'how now brown cow'); }

Makes the Xinha edited content "how now yellow camel" be written into the textarea as "how now brown cow".

autoFocus

Boolean. Automatically focus and activate the Xinha editor when the page is loaded. Not recommended for multiple editors on a page. Default false.

killWordOnPaste

Boolean. When pasting using the toolbar paste button, automatically kill word code in the paste. Due to browser security restrictions which prevent the toolbar paste button from being displayed, this usually is not of much use. Default true.

makeLinkShowsTarget

Boolean. Allow setting the target="" attribute in the default link creation dialog. Default true.

charSet

String. Character set to use. Default same as the character set of the page including Xinha (not necessarily the page Xinha is editing). It is highly recommended in the modern age to use UTF-8 character set for EVERYTHING on your website and in your database, if everything is always in UTF-8 you don’t have character conversion problems.

browserQuirksMode

Boolean

null. True, render the document being edited in in quirks mode. False, render the document being edited in standards mode. Null (default), render the document in the same mode as the page including Xinha.

htmlRemoveTags

RegExp

null. Set to a regular expression matching tags to remove these entirely from the edited content. Default null.

      xinha_config.htmlRemoveTags = /span|font/;

Removes all span and font tags.

preserveI

Boolean

null. If the HTML fed into Xinha includes tags, preserve these, otherwise convert them into when html is retrieved. The default, null, is that tags are not preserved unless you load the UseStrongEm plugin which means if you use the UseStrongEm plugin when you use the italic button it will insert but you can include in the code and they will be preserved ( is commonly used by designers in modern times as “icon” from a certain font). The default is typically fine, but set to true or false if you want to override.

preserveB

Boolean

null. If the HTML fed into Xinha includes tags, preserve these, otherwise convert them into when html is retrieved. The default, null, is that tags are not preserved unless you load the UseStrongEm plugin which means if you use the UseStrongEm plugin when you use the bold button it will insert but you can include in the code and they will be preserved. The default is typically fine, but set to true or false if you want to override.

flowToolbars

Boolean. Allow toolbars to flow to fit the width of the editor better. Default true.

toolbarAlign

String ‘left’

‘right’. Align the buttons left or right on the toolbar. Default ‘left’.

showFontStylesInToolbar

Boolean. ** Superceeded by the FancySelects plugin. ** Display the names of fonts in the font itself in the select drop down (browser support patchy, use FancySelects instead if you can). Default false.

showLoading

Boolean. Show a panel over the textarea indicating the loading status during the booting process of Xinha. Default false, however when using XinhaEasy.js or XinhaLoader.js this will typically be enabled anyway.

stripScripts

Boolean. Strip scripts from the HTML output - this only works with DOMwalk (see getHtmlMethod above) and is ignored if you use the PreserveScripts plugin. Default true.

convertUrlsToLinks

Boolean. When a user types in a url in the WYSIWYG view, automatically convert it to an html link. Default true.

hideObjectsBehindDialogs

Boolean. Set to true to hide media objects when a div-type dialog box is open, to prevent show-through. Default false. This probably isn’t all that relevant in the modern age since object elements are seldom used.

colorPickerCellSize

CSS length element. Size of each cell in the colour picker. Default 6px

colorPickerGranularity

Integer. Set to a higher number to allow more precise colours to be picked. Default 18.

colorPickerPosition

String. Set the position of the colour picker relative to it’s button, a strig consisting of two words from top, bottom, left and right separated by a comma. Default ‘bottom,right’.

colorPickerWebSafe

Boolean. Restrict colours to the 256 “web safe” colours. In the modern age, this is pretty redundant. Default false.

colorPickerSaveColors

Integer. Number of recent colours to remember. Default 20.

fullScreen

Boolean. Start the editor in full screen mode. Default false.

fullScreenMargins

Array [top, right, bottom, left ]. The margins in pixels to set when the editor is expanded to full screen. Default [0,0,0,0]

fullScreenSizeDownMethod

String ‘initSize’

‘restore’. When you exit full screen mode, will Xinha go back to the initial size, or the last size it was. Default ‘initSize’

toolbar

Multi Dimensional Array. See ToolBarSpecification

fontname

Object. The font families to provide in the drop-down select.

xinha_config.fontname = 
  {
    "&#8212; font &#8212;": "", // &#8212; is mdash
    "Arial"           :	'arial,helvetica,sans-serif',
    "Courier New"     :	'courier new,courier,monospace',
    "Georgia"         :	'georgia,times new roman,times,serif',
    "Tahoma"          :	'tahoma,arial,helvetica,sans-serif',
    "Times New Roman" : 'times new roman,times,serif',
    "Verdana"         :	'verdana,arial,helvetica,sans-serif',
    "Impact"          :	'impact',
    "WingDings"       : 'wingdings' 
  }

fontsize: Object. The font sizes to provide in the drop down select.

xinha_config.fontsize =
  {
    "&#8212; size &#8212;": "", // &#8212; is mdash
    "1 (8 pt)" : "1",
    "2 (10 pt)": "2",
    "3 (12 pt)": "3",
    "4 (14 pt)": "4",
    "5 (18 pt)": "5",
    "6 (24 pt)": "6",
    "7 (36 pt)": "7"
  };

formatblock: Object. The different block format types to provide in the drop down select.

xinha_config.formatblock = {
    "&#8212; format &#8212;": "", // &#8212; is mdash
    "Heading 1": "h1",
    "Heading 2": "h2",
    "Heading 3": "h3",
    "Heading 4": "h4",
    "Heading 5": "h5",
    "Heading 6": "h6",
    "Normal"   : "p",
    "Address"  : "address",
    "Formatted": "pre"
  };

formatblockDetector: Object. See https://www.coactivate.org/projects/xinha/custom-formatblock-options
dialogOptions: Object. Controls some options for dialogs.

  xinha_config.dialogOptions =
  {
    'centered' : true, //true: dialog is shown in the center the screen, false dialog is shown near the clicked toolbar button
    'greyout':true, //true: when showing modal dialogs, the page behind the dialoge is greyed-out
    'closeOnEscape':true
  };

Events: Object. Hook into some events, for example…

    xinha_config.Events.onKeyPress = function (event) 
    {
       //do something 
       return false;
    }

See EventHooks for discussion about available hooks.

debug: Boolean. Switches on some debug output. Default false.
URIs.iframe_src: String. The intial (blank) src to use on Xinha’s iframe. Default: ‘javascript:''’
bodyClass: String. A CSS class to apply to the <body> element. Default, none.
bodyID: String. An id attribute to apply to the <body> element. Default, none.