The editor component provides a rich text editor as a form control. Based on the FCKeditor, the editor is highly configurable (and can therefore be complicated). This component aims to keep usage simple, outsourcing most of the configuration to an optional external javascript file. The most important configurations are that of an external configuration file and the toolbars present in the editor. To support this, the editor component exposes the customConfiguration and toolbarSet parameters. In the interest of usability, the editor component will function as classic textarea element. NOTE: This component is built on the 2.x version of FCKeditor.
| Name | Type | Flags | Default | Default Prefix | Since | Description |
|---|---|---|---|---|---|---|
| customConfiguration | Asset | NOT Allow Null | prop | A custom configuration for this editor. See the FCKeditor manual for details on custom configurations. | ||
| height | String | NOT Allow Null | 300px | literal | The height of the editor. | |
| toolbarSet | String | NOT Allow Null | Default | literal | The toolbar set to be used with this editor. Default possible values are Default and Basic. Toolbar sets can be configured in a custom configuration. | |
| width | String | NOT Allow Null | 300px | literal | The width of the editor. |
Following is the simplest possible use of the editor.
You can see that it comes out of the box loaded with features... perhaps too many. We'll fix that later, but first let's look at how to use it.
public class MyPage
{
@Persist
@Property
private String _editorValue;
}
This is about as simple as it gets. We have created our page class with a
persistent property, editorValue, which will be used to store the value
accessed by the editor.
<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
<body>
<h3>Editor</h3>
<form t:type="form">
<textarea t:type="ck/editor" value="editorValue"
width="100%">This would be the textarea's content.</textarea>
<br/><input t:type="submit"/>
</form>
<h3>Content</h3>
<div style="padding: 5px; border: 1px solid #000;">
<div t:type="outputraw" value="editorValue">Output.</div>
</div>
</body>
</html>
In our template we declare a component of type ck/editor,
and we pass it values for the value and width parameters.
The important one of course is the value parameter, to which we
assign editorValue. The binding prefix for this parameter is prop:,
which means that Tapestry will look for this property in the page class. This
is the value that will be set when the containing form is submitted, and will also provide
the initial value for the editor.
Beneath our editor we created an outputraw component, in which we display the
contents of the editor after it has been submitted. The point of this is simply to show
that the editor is working much like a normal form field, and also how to correctly
display the content received from it. Note that if you do not display the content in
an outputraw component, Tapestry will replace the tags with entities so
as to not disrupt the page flow.
In this example we show how to provide the editor with a configuration file. External configurations are supported by the editor in the form of javascript files. The FCKeditor supports a myriad of configuration options, so for comprehensive documentation on them refer to the FCKeditor developer's guide.
FCKConfig.ToolbarSets["MyToolbar"] = [
['Bold','Italic']
];
As you can see this is a very simple configuration file in which we create a custom
toolbar. We named this toolbar MyToolbar, and can use it by passing this name
to the toolbarSet parameter of the editor. For our example we'll save
this file in the context root.
<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
<body>
<h3>Editor</h3>
<form t:type="form">
<textarea t:type="ck/editor" t:value="editorValue"
customConfiguration="asset:context:/myeditor.js" toolbarSet="MyToolbar"
width="100%">This would be the textarea's content.</textarea>
<br/><input t:type="submit"/>
</form>
<h3>Editor Result</h3>
<div style="padding: 5px; border: 1px solid #000;">
<div t:type="outputraw" value="editorValue">Output.</div>
</div>
</body>
</html>
This template is the same as the previous one with the addition of two parameters:
customConfiguration and toolbarSet. The customConfiguration
parameter expects an Asset,
so we pair the asset: and context: binding prefixes to
pull our configuration file in from the context as an asset.
The toolbarSet parameter accepts a simple string which should be one
of the named toolbars. Here we pass it the name of the toolbar that we defined
in our custom configuration (MyToolbar).
At its core, the Editor component is just a HTML textarea. Under a supported browser, it is transformed into a powerful rich text editor supporting configurable toolbars, templates, text styles, and many other advanced features.
The Editor component is built on the powerful FCKeditor. For information on configuring and extending the editor, refer to the developer's guide. For information on the features and general usage of teh editor, refer to the user's guide.