rich:editor component

Overview

 

The editor component (“editor” or “the component” in the text below) will provide possibility to use tinyMCE editor widget as JSF component. It also should implement missed tineMCE features or features which are not available as free .

 

The component supports SeamText format by default using pluggable built in converter.

 

The component will be presented with the rich:editor tag. 

 

The component is fully based on TinyMCE widget code so this document covers only specific points of usage of the component itself and the features which doesn't present in original widget.

 

Editor page definition

 

In difference with original plugin rich:editor encodes its own text area. Thus all the properties of tinyMCE which are used for target text area selection will be ignored. (editor_deselector, editor_selector, elements, mode)

 

Hence in difference with original widget usage the next simple page definition will be used:

 

 

<rich:editor value="#{bean.editorValue}"/>

 

Editor Options Redefinition

Editor properties could be customized using the following three ways:

  • Most important properties are moved to the component level as attributes.
  • f:param component could be used in order to redefine properties which aren't present as attributes
  • Config files feature is implemented

Attributes

Here is a list of properties which are available as component attributes (descriptions for these attributes could be found http://wiki.moxiecode.com/index.php/TinyMCE:Configuration)

General tinyMCE options attributes:

  • width
  • height
  • theme
  • plugins
  • autoResize
  • readonly
  • language
  • tabindex (instead of tabfocus)


Event Attributes:

 

  • onchange(onchange_callback)
  • oninit
  • onsave (save_callback)
  • onsetup(setup)

 

Standard input component attributes:

 

  • rendered
  • binding
  • immediate
  • required
  • validator
  • valueChangeListener
  • converter
  • value

 

Special attributes (This attributes are described in usage sections below):

  • useSeamText
  • plugins
  • configuration

 

f:param usage

 

As it was mentioned all the properties which aren't available as attributes could be redefined using f:param tag. Example:

<rich:editor theme="advanced">
    <f:param name="theme_advanced_resizing" value="true"/>
</rich:editor>

Configuration Files usage

This feature is implemented in order to allow the developers to define a common configuration for all the editors. It should be used in the next way:

  1. Create config property file and put to the classpath folder
  2. Define all needed properties in this file in pairs name - value
  3. Define configuration file name in "configuration" attribute

 

Example:

file editorconfig.properties:

Values of the properties should be defined respectively to the type of the value. Strings should be wrapped with quote signs.

width=100
height=200
theme_advanced_resizing = true
theme_advanced_buttons1 = "separator,insertdate,inserttime,preview,zoom,separator,forecolor,backcolor"
theme_advanced_buttons2 = "bullist,numlist,separator,outdent,indent,separator,undo,redo,separator"
theme_advanced_buttons3 = "hr,removeformat,visualaid,separator,sub,sup,separator,charmap"
...

page code:

<rich:editor theme="advanced" configuration="editorconfig">

 

EL-bindings are also supported using configuration attribute. Thus using this feature developers could define a few configuration to be used and change them on the fly.

 

Custom Plugins addition

Custom plugins could be created in the same way that described in http://wiki.moxiecode.com/index.php/TinyMCE:Creating_Plugin.

 

These plugins should be put to Web Content folder and should be additionally registered on the component. Plugins registering is similar to configuration properties files definition.

1) properties file with plugin names and paths to them should be created

2) the file name should be defined in customPlugins attribute

3) then plugins should be added to plugins attribute and corresponding theme properties as usual.


Example:

 

file editorCusomPlugins.properties:

 

myplugin1=/mytinymceplugins/myplugin1/editor_plugin.js
myplugin2=/mytinymceplugins/myplugin2/editor_plugin.js

page code

<rich:editor theme="advanced" customPlugins="editorCusomPlugins" plugins="myplugin1, myplugin1">

NOTE: some plugins which already available for download could have some dependencies to tinyMCE scripts. (for example using dialog popups requires tiny_mce_popup.js) Taking into consideration that developer will not plug our custom plugins to the RF jar with editor component (as opposite to standard tinyMCE plugins creation, which means that plugins will be put into tinyMCE corersponding directory) - the developer should manually add needed tinyMCE scripts to some folder and correct the js includes.

 

WYSIWYG mode disablement

tinyMCE WYSIWYG should be possible to be disabled using viewmode attribute which could have the next values: visual(default) and source

Seam Text Usage

rich:editor provides built-in converter which converts HTML generated with tiny plugin into seam text. Hence in order to store the value of the editor as seam text a developer will need just to defined useSeamText attribute as true.