Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.11.4.  < rich:editor > available since 3.3.0

The <rich:editor> component is used for creating a WYSIWYG editor on a page.


The <rich:editor> is fully based on TinyMCE web based Javascript HTML WYSIWYG editor control and supports all of the features it has. The <rich:editor> adapts the TinyMCE editor for JSF environment and adds some functional capabilities.

The easiest way to place the <rich:editor> on a page is as follows:

Example:


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

Implementation of <rich:editor> provides three ways to define the properties of the component:

The three methods are described in details in the chapter.

The most important properties are implemented as attributes and you can define them as any other attribute. The attributes of the <rich:editor> component match the corresponding properties of TinyMCE editor.

For example, a theme for the editor can be defined using the "theme" attribute like this:

Example:



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

Setting a different skin for the editor can be done using the "skin" attribute.

Another useful property that is implemented at attribute level is "viewMode" . The attribute switches between "visual" and "source" modes, toggling between modes is performed setting the attribute to "visual" and "source" respectively. Implementation of <rich:editor> also implies that you can change the modes dynamically setting the value of the "viewMode" attribute using EL-expression.

Example:


...  
<rich:editor value="#{editor.submit}" theme="advanced" viewMode="#{editor.viewMode}" >
    ...
    <h:selectOneRadio value="#{editor.viewMode}" onchange="submit();">
        <f:selectItem itemValue="visual" itemLabel="visual" />
        <f:selectItem itemValue="source" itemLabel="source" />
    </h:selectOneRadio>
    ...
</rich:editor>
...

Most configuration options that TinyMCE provides can be applied using <f:param> JSF tag. The syntax is quite simple: the "name" attribute should contain the option, the "value" attribute assigns some value to the option.

For example, this code adds some buttons to the editor and positions the toolbar.

Example:


...
<rich:editor value="#{bean.editorValue}" theme="advanced" plugins="save,paste" >
          <f:param name="theme_advanced_buttons1" value="bold,italic,underline, cut,copy,paste,pasteword"/>
          <f:param name="theme_advanced_toolbar_location" value="top"/>                               
          <f:param name="theme_advanced_toolbar_align" value="left"/>
</rich:editor>
...

This is what you get as a result:


The third way to configure the <rich:editor> is to use configuration file (.properties)

This method eases your life if you need to configure multiple instances of the <rich:editor> : you configure the editor once and in one spot and the configuration properties can be applied to any <rich:editor> in your application.

To implement this type of configuration you need to take a few steps:

  • Create a configuration file (.properties) in the classpath folder and add some properties to it. Use standard syntax for the .properties files: parameter=value. Here is an example of configuration file:

    Example:

    
    theme="advanced"
    plugins="save,paste"
    theme_advanced_buttons1="bold,italic,underline, cut,copy,paste,pasteword"
    theme_advanced_toolbar_location="top"
    theme_advanced_toolbar_align="left"
  • The properties stored in configuration file are passed to the <rich:editor> via "configuration" attribute which takes the name of the configuration file as a value (with out .properties extension).

    For example, if you named the configuration file "editorconfig", you would address it as follows:

    Example:

    
    ...
    <rich:editor value="#{bean.editorValue}" configuration="editorconfig"/>
    ...
  • Alternately, you can use a EL-expression to define a configuration file. This way you can dynamically change the sets of configuration properties.

    For example, you have two configuration files "configurationAdvanced" and "configurationSimple" and you want them to be applied under some condition.

    To do this you need to bind "configuration" attribute to the appropriate bean property like this.

    Example:

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

    Your Java file should look like this.

    ...
    
    String configuration;
    if(some condition){//defines some condition
            configuration = "configurationAdvanced"; //the name on the file with advanced properties    
    }
    else{
            configuration= "configurationSimple"; //the name on the file with simplified properties 
    }
    ...

You also might want to add some custom plug-ins to your editor. You can read about how to create a plugin in TinyMCE Wiki article.

Adding a custom plugin also requires a few steps to take. Though, the procedure is very similar to adding a configuration file.

This is what you need to add a plugin:

  • Create a .properties file and put the name of the plug-in and a path to it into the file. The file can contain multiple plug-in declarations. Your .properties file should be like this.

    Example:

    
    ...
    pluginName=/mytinymceplugins/plugin1Name/editor_plugin.js
    ...
  • Use the "customPlugins" attribute to specify the .properties file with a plugin name and a path to it.

    If your .properties file is named "myPlugins", then your will have this code on the page.

    Example:

    
    ...
    <rich:editor theme="advanced" customPlugins="myPlugins" plugins="pluginName" /> 
    ...

Note:

Some plug-ins which available for download might have some dependencies on TinyMCE scripts. For example, dialog pop-ups require tiny_mce_popup.js script file. Assuming that you will not plug custom plugins to the RF jar with editor component (standard TinyMCE plugins creation implies that plugins are put into TinyMCE's corresponding directory) you should manually add required TinyMCE scripts to some project folder and correct the js includes.

The implementation of the <rich:editor> component has two methods for handling events.

The attributes take some function name as a value with is triggered on the appropriate event. You need to use standard JavaScript function calling syntax.

  • Using attributes ( "onchange" , "oninit" , "onsave" , "onsetup" )

    Example:

    
    ...
    <rich:editor value="#{bean.editorValue}" onchange="myCustomOnChangeHandler()" />
    ...
  • Using <f:param> as a child element defining the "name" attribute with one of the TinyMCE's callbacks and the "value" attribute takes the function name you want to be called on the corresponding event as the value. Note, that the syntax in this case is a bit different: parentheses are not required.

    Example:

    
    ...
    <rich:editor value="#{bean.editorValue}">
            <f:param name="onchange" value="myCustomOnChangeHandler" />
    </rich:editor>
    ...

The <rich:editor> component has a build-in converter that renders HTML code generated by the editor to Seam text (you can read more on Seam in Seam guide.), it also interprets Seam text passed to the <rich:editor> and renders it to HTML. The converter can be enable with the "useSeamText" attribute.

Example:

This HTML code generated by editor


...
<p><a href="http://mysite.com">Lorem ipsum</a> <i>dolor sit</i> amet, ea <u>commodo</u> consequat.</p>
...

will be parsed to the following Seam text:


...
[Lorem ipsum=>http://mysite.com] *dolor sit* amet, ea _commodo_ consequat.
...

Accordingly, if the Seam text is passed to the component it will be parsed to HTML code.

Table of <rich:editor> attributes.


Table 6.176. Style classes (selectors) with the corresponding skin parameters

Class (selector) nameDescriptionSkin ParameterCSS properties mapped
.richfacesSkin a:hover, .richfacesSkin a:link, .richfacesSkin a:visited, .richfacesSkin a:activeDefines styles for links stategeneralTextColorcolor
.richfacesSkin tableDefines styles for the wrapper <table> element of the editoradditionalBackgroundColorbackground
.richfacesSkin iframeDefines styles for the editor text areatableBackgroundColorbackground
.richfacesSkin .mceExternalToolbarDefines styles for the toolbarpanelBorderColorborder-color
.richfacesSkin table.mceLayoutDefines styles for the table layoutpanelBorderColorborder-left-color, border-right-color
.richfacesSkin table.mceLayout tr.mceFirst tdDefines styles for the toolbar elementspanelBorderColorborder-top-color
.richfacesSkin table.mceLayout tr.mceLast tdDefines styles for the editor windowpanelBorderColorborder-bottom-color
.richfacesSkin .mceIframeContainerDefines styles for the editor containerpanelBorderColorborder-top-color, border-bottom-color
.richfacesSkin .mceStatusbarDefines styles for the status bargeneralFamilyFontfont-family
generalTextColorcolor
.richfacesSkin a.mceButtonEnabled:hoverDefines styles for the editor buttons hoveredheaderBackgroundColorbackground-color
.richfacesSkin span.mceButtonLabelDefines styles for the editor buttons labelsgeneralFamilyFontfont-family
.richfacesSkin .mceListBox .mceTextDefines styles for the list boxgeneralFamilyFontfont-family
panelBorderColorborder-color
tableBackgroundColorbackground
.richfacesSkin table.mceListBoxEnabled:hover .mceText, .richfacesSkin .mceListBoxSelected .mceTextDefine styles for the list box hovered, selected respectivelytableBackgroundColorbackground
.richfacesSkin div.mceColorSplitMenu tableDefines styles for the wrapper <table> element of the popup element for color selectingtableBackgroundColorbackground
panelBorderColorborder-color
.richfacesSkin .mceColorSplitMenu aDefines styles for the items in the popup element for color selectingpanelBorderColorborder-color
.richfacesSkin .mceColorSplitMenu a.mceMoreColorsDefines styles for the "More Colors" buttonpanelBorderColorborder-color
generalFamilyFontfont-family
.richfacesSkin .mceColorSplitMenu a.mceMoreColors:hoverDefines styles for the "More Colors" button hoveredpanelBorderColorborder-color
additionalBackgroundColorbackground-color
.richfacesSkin a.mceMoreColors:hoverDefines styles for the "More Colors" button hoveredheaderBackgroundColorborder-color
.richfacesSkin .mceColorPreviewDefines styles for the color previewtableBorderColorbackground
.richfacesSkin .mceMenuDefines styles for the menuspanelBorderColorborder-color
.richfacesSkin .mceMenu tableDefines styles for the wrapper <table> element of the menutableBackgroundColorbackground
.richfacesSkin .mceMenu .mceTextDefines styles for the menus labelsgeneralFamilyFontfont-family
generalTextColorcolor
.richfacesSkin .mceMenu .mceMenuItemActiveDefines styles for the active menu itemsadditionalBackgroundColorbackground-color
.richfacesSkin .mceMenu .mceMenuItemEnabled a:hoverDefines styles for the enabled menu items hoveredadditionalBackgroundColorbackground-color
.richfacesSkin td.mceMenuItemSeparatorDefines styles for the menu items separatorpanelBorderColorbackground
.richfacesSkin .mceMenuItemTitle aDefines styles for the titles of the menu itemsadditionalBackgroundColorbackground
panelBorderColorborder-bottom-color
.richfacesSkin .mceMenuItemDisabled .mceTextDefines styles for the disabled menu itemstabDisabledTextColorcolor
.richfacesSkin .mceBlockerDefines styles for the editor blockertableBackgroundColorbackground
.richfacesSkin .mcePlaceHolderDefines styles for the editor place holdertableBorderColorborder-color


You can find all necessary information about style classes redefinition in Definition of Custom Style Classes section.

The <rich:editor> is based on TinyMCE editor and supports almost all its features and properties some of which are not described here since you can find more detailed documentation on them on the official web site.

On RichFaces LiveDemo page you can see an example of <rich:editor> usage and sources for the given example.