wiki:0.5/Customization
Last modified 3 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.

skinPath

WYMeditor skin (theme) path, used to load the skin.

Example: 

  skinPath: "wymeditor/skins/default/"

This value is automatically guessed, based on the basePath value.

wymPath

WYMeditor main JS file path.

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

iframeBasePath

WYMeditor iframe base path.

This value is automatically guessed, based on the basePath value.

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.

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.

How to use a custom language

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

logoHtml

The WYMeditor logo HTML. This option allows you to customize the HTML which displays the WYMeditor logo.

If you prefer to hide the WYMeditor logo, use an empty string: 

$('.wymeditor').wymeditor({ logoHtml: '' });

In such a case, please consider making a donation to the project.

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' });

Use  this example stylesheet as a reference.

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'}
  ]

Default value: 

  toolsItems: [
    {'name': 'Bold', 'title': 'Strong', 'css': 'wym_tools_strong'}, 
    {'name': 'Italic', 'title': 'Emphasis', 'css': 'wym_tools_emphasis'},
    {'name': 'Superscript', 'title': 'Superscript', 'css': 'wym_tools_superscript'},
    {'name': 'Subscript', 'title': 'Subscript', 'css': 'wym_tools_subscript'},
    {'name': 'InsertOrderedList', 'title': 'Ordered_List', 'css': 'wym_tools_ordered_list'},
    {'name': 'InsertUnorderedList', 'title': 'Unordered_List', 'css': 'wym_tools_unordered_list'},
    {'name': 'Indent', 'title': 'Indent', 'css': 'wym_tools_indent'},
    {'name': 'Outdent', 'title': 'Outdent', 'css': 'wym_tools_outdent'},
    {'name': 'Undo', 'title': 'Undo', 'css': 'wym_tools_undo'},
    {'name': 'Redo', 'title': 'Redo', 'css': 'wym_tools_redo'},
    {'name': 'CreateLink', 'title': 'Link', 'css': 'wym_tools_link'},
    {'name': 'Unlink', 'title': 'Unlink', 'css': 'wym_tools_unlink'},
    {'name': 'InsertImage', 'title': 'Image', 'css': 'wym_tools_image'},
    {'name': 'InsertTable', 'title': 'Table', 'css': 'wym_tools_table'},
    {'name': 'Paste', 'title': 'Paste_From_Word', 'css': 'wym_tools_paste'},
    {'name': 'ToggleHtml', 'title': 'HTML', 'css': 'wym_tools_html'},
    {'name': 'Preview', 'title': 'Preview', 'css': 'wym_tools_preview'}
  ]

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