⁠10.3. <rich:editor>

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

Figure 10.3. <rich:editor>

<rich:editor> component is based on the CKEditor implementation.
When rendering a <rich:editor>, a textarea is rendered to the page and once the page is completely loaded (ready state), the textarea is enhanced using a CKEditor script and replaced with a full-featured WYSIWYG editor.

⁠10.3.1. Basic usage

Basic usage requires the value attribute to point to the expression for the current value of the component.
⁠

Example 10.5. Basic usage of <rich:editor>

​<rich:editor value="#{backingBean.editedValue}" />
​
​<h:outputText escape="false" value="#{backingBean.editedValue}" />
Note that the editor produces HTML markup and to be able to render it's output, the markup needs to be unescaped (as with <h:outputText> component in example above).
The dimensions of the editor can be managed using width and height attributes.
The readonly attribute can be used to switch the editor into a read-only mode.
The tabindex attribute specifies the position of the current element in the tabbing order for the current document.

Note

The ResourceServlet has to be registered for the url-pattern /org.richfaces.resources/* in order to serve the editor resources (JavaScript, CSS, images) correctly. Check the RichFaces Developer's Guide for further details.

Note

The <rich:editor> requires the <h:body> component to be present in the view and must be an ancestor of the editor in order for the resource dependencies to render correctly.

⁠10.3.2. Styling

There are several options to customize the style of the editor:
  • style, styleClass: customizes the style of the editor and underlying textarea
  • editorStyle, editorClass: customizes the style of the CKEditor instance
  • textareaStyle, textareaClass: customizes the style of the underlying textarea

⁠10.3.3. Editor skins

The <rich:editor> is skinnable using the JavaScript API of the CKeditor. Refer to the CKeditor documentation on installing skins for details on how to customize the look and feel of the editor component.

⁠10.3.4. Advanced configuration

The basic set of <rich:editor> attributes allows you to support common use-cases for a WYSIWYG editor. However the underlying CKEditor implementation supports many more configuration options.
Use the config attribute to define any of these advanced configuration options supported by the CKEditor. This configuration is written in JavaScript object format and its value is interpolated for EL expressions (making configuration dynamic).
There are two ways to define the configuration: the config attribute or a facet named config. The facet takes precedence over attribute when both are defined. 
​<rich:editor config="startupFocus: #{userPreferences.startupFocus}" />
​
​<rich:editor>
​    <f:facet name="config">
​        startupFocus: #{userPreferences.startupFocus}
​    </f:facet>
​</rich:editor>
In the above samples, the <rich:editor> is configured to take focus after loading the page as defined by the userPreference bean. Definitions using either attribute or facet are equivalent.

Note

For further configuration options, refer to CKEditor 4 Developer Guide and CKEditor 4 configuration reference.

⁠10.3.5. Toolbar customization

The <rich:editor> supports a toolbar attribute, which is able to change the configuration of the toolbar's button set. There are two configurations available: basic (default), full (enables all of the features).
It is also possible to define a custom toolbar using the CKEditor toolbar configuration in a config facet: 
​<rich:editor toolbar="CustomToolbar">
​    <f:facet name="config">
​        toolbar_CustomToolbar:
​        [
​        { name: 'document', items : [ 'NewPage','Preview' ] },
​        { name: 'clipboard', items : [ 'Cut','Copy','Paste','-','Undo','Redo' ] },
​        { name: 'editing', items : [ 'Find','Replace','-','SelectAll','-','Scayt' ] },
​        { name: 'insert', items : [ 'Image', 'Flash', 'Table', 'HorizontalRule', 
​                 'Smiley', 'SpecialChar', 'PageBreak', 'Iframe' ] },
​                '/',
​        { name: 'styles', items : [ 'Styles','Format' ] },
​        { name: 'basicstyles', items : [ 'Bold','Italic','Strike','-','RemoveFormat' ] },
​        { name: 'paragraph', items : [ 'NumberedList','BulletedList','-','Outdent','Indent','-','Blockquote' ] },
​        { name: 'links', items : [ 'Link','Unlink','Anchor' ] },
​        { name: 'tools', items : [ 'Maximize' ] }
​        ]
​        </f:facet>
​</rich:editor>
Note that toolbar name (CustomToolbar) needs to match the toolbar_<name> configuration option.

⁠10.3.6. Internationalization and localization

The <rich:editor> comes with a lang attribute which allows you to change the localization of the editor. For language configuration options, refer to http://www.w3.org/TR/html4/struct/dirlang.html.
The lang attribute influences following settings:
  • underlying textarea - specifies the i18n settings for received and submitted content
  • editor value - specifies the i18n settings for value edited in WYSIWYG mode
  • default settings of localization of editor controls and interface
However the interface first localized using the browser configuration (usually determined by client system settings). To force the editor to use a specific localization for the interface, you use the advanced CKEditor configuration option language, as in following sample: 
​<rich:editor lang="fr" config="language: 'fr'" />
The above sample forces the editor to use a french interface, suppressing the browser preferred settings.

⁠10.3.7. Client-side event handlers

The <rich:editor> component produces set of events for handling component specific interaction.
  • init - once the editor is initialized and ready to be handle user interaction
  • focus - once the editor is focused
  • blur - once the editor is blurred
  • change - fired on blur event when editor content has been changed after previous focus
  • dirty - fired immediately after editor content has been changed
Events can be handled either by registering a JavaScript event handler or by attaching JSF behavior: 
​<rich:editor value="#{backingBean.editorValue}">
​    <a4j:ajax event="change" render="editorOutput" />
​    <a4j:ajax event="dirty" render="editorOutput">
​        <a4j:attachQueue requestDelay="1000" />
​    </a4j:ajax>
​</rich:editor>
​
​<a4j:outputPanel id="editorOutput">
​    <h:outputText escape="false" value="#{backingBean.editorValue}" />
​</a4j:outputPanel>
The example above shows the editor and its output, which is updated every second after each instant change or immediately after user focus leaves the editor area.

⁠10.3.8. JavaScript API

The <rich:editor> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()
Get the current value of the input control.
setValue(newValue)
Set the value of the input control to the newValue string passed as a parameter.
getEditor()
Returns the CKEditor object instance associated to given <rich:editor> component.
getInput()
Returns the associated textarea.
focus()
Gives focus to this component
blur()
Removes focus from this component
isFocused()
Returns true if this component is focused
isDirty()
Returns true if editor is focused and it was edited from last focus event (reset by blur event, by using setValue(newValue) call and when component is re-rendered)
isValueChanged()
Returns true if the control's value has been changed from the default (reset by setValue(newValue) call and when component is re-rendered)
isReadonly()
Returns true if editor content is editable.
setReadonly(readonly)
When readonly is true, editor will be switched to editable state. Otherwise, it will be switched to readonly state.

⁠10.3.9. Reference data

  • component-type: org.richfaces.Editor
  • component-class: org.richfaces.component.UIEditor
  • component-family: org.richfaces.Editor
  • renderer-type: org.richfaces.EditorRenderer

⁠10.3.10. Style classes and skin parameters

⁠

Table 10.3. Style classes (selectors) and corresponding skin parameters

Class (selector) Skin Parameters Mapped CSS properties
.cke_skin_richfaces
panelBorderColor
border-color
.cke_skin_richfaces .cke_wrapper
editorMainBackgroundColor
background-color
.cke_skin_richfaces .cke_dialog_body
panelBorderColor
border-color
generalBackgroundColor
background
.cke_skin_richfaces .cke_dialog_title
headerBackgroundColor
repeat-x
headerWeightFont
font-weight
headerTextColor
color
headerFamilyFont
font-family
headerSizeFont
font-size
.cke_skin_richfaces .cke_path a, .cke_skin_richfaces .cke_path .cke_empty
editorMainTextColor
color
.cke_skin_richfaces .cke_button a.cke_on
additionalBackgroundColor
background-color
panelBorderColor
border-color
.cke_skin_richfaces .cke_button a:hover, .cke_skin_richfaces .cke_button a:focus, .cke_skin_richfaces .cke_button a:active
panelBorderColor
border-color
tabBackgroundColor
background-color
.cke_skin_richfaces .cke_rcombo a, .cke_skin_richfaces .cke_rcombo a:active, .cke_skin_richfaces .cke_rcombo a:hover
panelBorderColor
border-color
generalSizeFont
font-size
generalFamilyFont
font-family
controlTextColor
color
controlBackgroundColor
background-color
.cke_skin_richfaces .cke_rcombo .cke_openbutton
headerBackgroundColor
background-color
panelBorderColor
border-left-color