-
Notifications
You must be signed in to change notification settings - Fork 338
Configuration
Editor can be initiated either in a mode using iframe (all content edited is inside iframe) or as a plain contenteditable div. Editor can be initiated in javascript using a DOM element:
var editor = new wysihtml5.Editor(document.getElementById('editable'), options);
or a ID string of DOM element:
var editor = new wysihtml5.Editor('editable', options);
Iframe mode gives separation of user editable html from page html. Iframe mode is more secure as broken code can not escape the editable container. Also it provides some protection from user inserted scripts to execute and modify parent pages DOM. On the other hand it has the limitation of not inheriting parent page styles, especially regarding DOM context (a separate predefined stylesheet can be provided on initiation though). Iframe is not natively scaling in height too when content gets higher.
Iframe mode is initiated by binding wysihtml to <textarea> element:
<textarea id="editable" placeholder="Enter text ...">Initial content</textarea>
<script>
var editor = new wysihtml5.Editor(editable, options);
</script>
In iframe mode an <iframe> element is injected to DOM where all editing is done by user. The <textarea> element remains, but is hidden and its visual styles are mimicked by injected <iframe>. All changes in <iframe> are published to the <textarea> as cleaned html code. Thus this mode is intended for using in forms to make a <textarea> element rich-text capable, while preserving the ability to natively post the form.
Conteneditable mode makes no separation from page context. It makes the given element editable directly. Thus the editable area gets all its styles from page stylesheet. It behaves in all means as the native element, for example stretching its dimensions as content grows. Contenteditable mode is intended to be initiated on element that allows containing all flow content (<div>, etc.) elements. Initiating wysihtml on element that allows only inline content (<span>, <a>, etc) or phrasing content (<h1>, <h2>, <p>, etc.) is not supported and will cause weird behaviour at some point. It is caused by browsers trying to fix the code when it contains flow content.
Contenteditable mode is initiated by binding to <div> element:
<div id="editable" data-placeholder="Enter text ...">Initial content</div>
<script>
var editor = new wysihtml5.Editor('editable', options);
</script>
On initiation options object can be passed to editor as second argument. For example:
var editor = new wysihtml5.Editor('editable', {
parserRules: wysihtml5ParserRules,
toolbar: document.querySelector('.toolbar')
});
Following is a list of all configuration parameters with their corresponding default values.
Will set class name on the iframe and on the iframe's body. Used only in iframe mode.
Type: string, default: undefined.
Sets whether the editor should look like the textarea (by adopting styles)
Type: boolean, default: true
Sets ID of the default toolbar element or DOM node defining the element used for toolbar. It is used only for the default toolbar bundled with wysihtml-toolbar.js. If custom toolbar logic is used or no toolbar required the file wysihtml.js should be used instead to reduce code overhead.
Type: DOM node or string, default: undefined
Sets if default toolbar is displayed after initiation or only when editable area is focused.
Type: boolean, default: true
Sets if default toolbar shows dialogs in toolbar when their related text format state becomes active (click on link in text opens link dialogue).
Type: boolean, default: true
Sets whether urls, entered by the user should automatically become clickable-links
Type: boolean, default: true
Sets whether tab key should be treated as tab insertion in text or default behaviour of browser (to skip to next field).
Type: boolean, default: true
Turns on table editing events and cell selection tracking.
Type: boolean, default: true
Object which includes parser rules to apply for html for code cleanup. See parser rules section for detailed specifications. Examples can be viewed here.
Type: object, default: { tags: { br: {}, span: {}, div: {}, p: {} }, classes: {} }
Array of parserRules objects which includes parser rules when the user inserts content via copy & paste. Can be configured to detect parts of pasted content via regexp and apply appropriate ruleset. If null parserRules will be used instead. See parser rules section for detailed specifications. Example can be viewed here.
Browsers that support copied source handling will get a marking of the origin of the copied source (for determinig code cleanup rules on paste). Also copied source is based directly on selection - (very useful for webkit based browsers where copy will otherwise contain a lot of code and styles based on whatever and not actually in selection). If falsy value is passed source override is also disabled.
Type: string, default: '<meta name="copied-from" content="wysihtml5">'
Parser method to use when the user inserts content via copy & paste.
Type: function(htmlOrElement, clearInternals), default: wysihtml5.dom.parse
Object containting class names that wysihtml uses. Default:
{
// Class name which should be set on the contentEditable element in the created sandbox iframe, can be styled via the 'stylesheets' option
composer: "wysihtml5-editor",
// Class name to add to the body when the wysihtml5 editor is supported
body: "wysihtml5-supported",
// classname added to editable area element (iframe/div) on creation
sandbox: "wysihtml5-sandbox",
// class on editable area with placeholder
placeholder: "wysihtml5-placeholder",
// Classname of container that editor should not touch and pass through. Pass false to disable
uneditableContainer: "wysihtml5-uneditable-container"
}
Sets if senseless <span> elements (empty or without attributes) should be un-wrapped. Webkit browsers are very eager to add all kinds of junk <spans> around the code just for browsers internal reference. Keeping this value true will keep reduce the amount of these spans.
Type: boolean, default: true
By default wysihtml5 will insert a <br> for line breaks, set this to false to use <p>
Type: boolean, default: true
Array (or single string) of stylesheet urls to be loaded in the editor's iframe. Used only in iframe mode.
Type: array or string, default: []
Placeholder string to use. Defaults to the placeholder attribute on the <textarea> element or data-placeholder attribute on <div> element.
Type: string, default: undefined