wiki:0.4/Customization
Last modified 5 years ago

Customization

Since 0.4, getting started examples are integrated in WYMeditor's package. See the 'examples' directory.

$(jqexpr).wymeditor(options)

This function will be applied to elements matching a jQuery expression jqexpr.

Example: Replaces each textarea having the class wymeditor by a WYMeditor instance: 

$("textarea.wymeditor").wymeditor();

Parameters

The function accepts an optional parameter: an array of options.

Example: Initializes WYMeditor HTML content and displays an alert box when ready: 

$(".wymeditor").wymeditor({

  //options
  html: "<p>test<\/p>",
  postInit: function() {
    alert('OK');
  }
});

List of options

Check the file jquery.wymeditor.js, function $j.fn.wymeditor for the complete list of options and their default values.

html

Initializes the editor's HTML content.

Example: 

  html: "<p>Hello, World!<\/p>"

Note: in Javascript, it's a good habit to escape forward slashes, like this: <\/p>.

basePath

WYMeditor's relative/absolute base path (including the trailing slash), used while loading the iframe and the dialogs.

Example: 

  basePath: "/admin/edit/wymeditor/"

This value is automatically guessed by computeBasePath, which looks for the script element loading jquery.wymeditor.js.

cssPath

WYMeditor skin (theme) CSS path, used while loading the dialogs.

Example: 

  cssPath: "wymeditor/skins/default/screen.css"

This value is automatically guessed by computeCssPath, which looks for the link element loading wymeditor/skins/{skin name}/screen.css.

jQueryPath

jQuery JS file path.

Example: 

  jQueryPath: "/js/jquery.js"

This value is automatically guessed by computeJqueryPath, which looks for the script element loading jquery.js.

xhtmlParser

The XHTML parser JS path, relative to the main WYMeditor JS file. Default: xhtml_parser.pack.js
The parser is loaded by WYMeditor via an AJAX call.

cssParser

The CSS parser JS path, relative to the main WYMeditor JS file. Default: wym_css_parser.pack.js
The parser is loaded by WYMeditor via an AJAX call.

lang

The language to use with WYMeditor. Default is English (en). Codes are in ISO-639-1 format.
Language packs are stored in the wymeditor/lang directory.
Most common internet languages (cn, de, en, es, fr, jp), if available, are included in jquery.wymeditor.js at build time, so you don't need to load the corresponding file.

How to use a custom language

Important: call the language file before calling WYMeditor: 

...
<script type="text/javascript" src="wymeditor/lang/pl.js"></script>
<script type="text/javascript" src="wymeditor/jquery.wymeditor.js"></script>
...

Then, initialize the option: 

$('.wymeditor').wymeditor({ lang: 'pl' });

boxHtml

The editor container's HTML. This option allows you to customize the HTML containing a WYMeditor instance.

iframeHtml

The iframe (used for editing) container's HTML.

styles & stylesheet

Allows you to easily configure the editor' styles.
Advantageously replaces editorStyles, dialogStyles and classesItems.

Define the styles using the styles option OR point to an external stylesheet, using the stylesheet option.

Example, using styles: 

styles:                                                            
      '/* PARA: Date */                                                    '+
      '.date p{                                                            '+
      '  color: #ccf;                                                      '+
      '  /* background-color: #ff9; border: 2px solid #ee9; */             '+
      '}                                                                   '+
      '                                                                    '+
      '/* PARA: Hidden note */                                             '+
      '.hidden-note p /* p[@class!="important"] */ {                       '+
      '     display: none;                                                 '+
      '    /* color: #999; border: 2px solid #ccc; */                      '+
      '}                                                                   '

Example, using stylesheet: 

$('.wymeditor').wymeditor({ stylesheet: 'stylesheet.css' });

Stylesheet content:

Note: put WYMeditor' styles between /* WYMeditor */ and /* /WYMeditor */ 

/* 
  YOU CAN ADD OTHER STYLES AS USUAL ON THIS SHEET 
  
  Commented styles inside style definitions are used for visual 
  feedback when using the editor
  
  Comments before opening the style are used as caption.

  Comments after the class name and before the style declaration ({) 
    define the expression that decides wheter this 
    style should be applied or not
*/

.ignoreMe{
  
}

/* WYMeditor */

/* PARA: Date */
.date p{
  color: #ccf;
  /* background-color: #ff9; border: 2px solid #ee9; */
}

/* PARA: Hidden note */
.hidden-note p /* p[@class!="important"] */ {
     display: none;
    /* color: #999; border: 2px solid #ccc; */
}

/* PARA: Important */
.important p /* p[@class!="hidden-note"] */ {
    color: red; font-weight: bold;
    /* color: red; font-weight: bold; border: 2px solid red; */
}

.border img {
    border: 1px solid #ccc;
    /* border: 4px solid #ccc; */
}

/* LIST: Special */
.special ul,
.special ol {
    color: green;
    /** / background-color: #fc9; border: 2px solid red; /**/
}


/* /WYMeditor */


.afterThisPointRulesAreNoLongerParsedByWym{
  
}

/* YOU CAN ADD OTHER STYLES AS USUAL ON THIS SHEET */

editorStyles

An array of classes, applied on the editor's content, in the form of: {'name': 'value', 'css': 'value'}

Example: 

  editorStyles: [
    {'name': '.hidden-note', 'css': 'color: #999; border: 2px solid #ccc;'},
    {'name': '.border', 'css': 'border: 4px solid #ccc;'}
  ]

toolsHtml

The tools panel's HTML.

toolsItemHtml

The tools buttons' HTML template.

toolsItems

An array of tools buttons, inserted in the tools panel, in the form of: {'name': 'value', 'title': 'value', 'css': 'value'}

Example: 

  toolsItems: [
    {'name': 'Bold', 'title': 'Strong', 'css': 'wym_tools_strong'}, 
    {'name': 'Italic', 'title': 'Emphasis', 'css': 'wym_tools_emphasis'}
  ]

containersHtml

The containers panel's HTML.

containersItemHtml

The containers buttons' HTML template.

containersItems

An array of containers buttons, inserted in the containers panel, in the form of: {'name': 'value', 'title': 'value', 'css': 'value'}

Example: 

  containersItems: [
    {'name': 'P', 'title': 'Paragraph', 'css': 'wym_containers_p'},
    {'name': 'H1', 'title': 'Heading_1', 'css': 'wym_containers_h1'}
  ]

classesHtml

The classes panel's HTML.

classesItemHtml

The classes buttons' HTML template.

classesItems

An array of classes buttons, inserted in the classes panel, in the form of: {'name': 'value', 'title': 'value', 'expr': 'value'}, where expr is a jQuery expression.

Example: 

  classesItems: [
    {'name': 'date', 'title': 'PARA: Date', 'expr': 'p'},
    {'name': 'hidden-note', 'title': 'PARA: Hidden note', 'expr': 'p[@class!="important"]'}
  ]

In this example, the class 'date' can be applied on paragraphs, while the class 'hidden-note' can be applied on paragraphs without the class 'important'.

statusHtml

The status bar's HTML.

htmlHtml

The HTML box's HTML.

Selectors

WYMeditor uses jQuery to select elements of the interface. You'll need these options if you e.g. customize the panels' HTML.

  • boxSelector
  • toolsSelector
  • toolsListSelector
  • containersSelector
  • classesSelector
  • htmlSelector
  • iframeSelector
  • statusSelector
  • toolSelector
  • containerSelector
  • classSelector
  • htmlValSelector
  • hrefSelector
  • srcSelector
  • titleSelector
  • altSelector
  • textSelector
  • rowsSelector
  • colsSelector
  • captionSelector
  • submitSelector
  • cancelSelector
  • previewSelector
  • dialogLinkSelector
  • dialogImageSelector
  • dialogTableSelector
  • dialogPasteSelector
  • dialogPreviewSelector
  • updateSelector

Example: 

  classesSelector: ".wym_classes"

updateSelector & updateEvent

Allows you to update the value of the element replaced by WYMeditor (typically a textarea) by the editor's content while e.g. clicking on a button in your page.
updateSelector is a jQuery expression, updateEvent is a  jQuery event.

Example: 

  updateSelector: ".my-submit-button",
  updateEvent:    "click"

dialogFeatures

The dialogs' features.

Example: 

  dialogFeatures: "menubar=no,titlebar=no,toolbar=no,resizable=no,width=560,height=300,top=0,left=0"

dialogHtml

The dialogs' HTML template.

dialogLinkHtml

The link dialog's HTML template.

dialogImageHtml

The image dialog's HTML template.

dialogTableHtml

The table dialog's HTML template.

dialogPasteHtml

The 'Paste from Word' dialog's HTML template.

dialogPreviewHtml

The preview dialog's HTML template.

dialogStyles

An array of classes, applied to the dialogs, in the form of: {'name': 'value', 'css': 'value'}

skin

The skin you want to use.

Example: 

skin: 'custom'

stringDelimiterLeft & stringDelimiterRight

WYMeditor uses a simple function to replace strings delimited by these two strings for e.g. the l10n system.

preInit(wym)

A custom function which will be executed once, before WYMeditor's initialization.

Parameters:

  • wym: the WYMeditor instance

preBind(wym)

A custom function which will be executed once, before binding handlers on events (e.g. buttons click).

Parameters:

  • wym: the WYMeditor instance

postInit(wym)

A custom function which will be executed once, when WYMeditor is ready.

Parameters:

  • wym: the WYMeditor instance

Example: 

  postInit: function(wym) {
    //activate the 'tidy' plugin, which cleans up the HTML
    //'wym' is the WYMeditor instance
    var wymtidy = wym.tidy();
    wymtidy.init();
  }

preInitDialog(wym,wdw)

A custom function which will be executed before a dialog's initialization.

Parameters:

  • wym: the WYMeditor instance
  • wdw: the dialog's window object

postInitDialog(wym,wdw)

A custom function which will be executed when a dialog is ready.

Parameters:

  • wym: the WYMeditor instance
  • wdw: the dialog's window object