User Interface Components

TextChangeEventMode.LAZY (default)

An event is triggered when there is a pause in editing the text. The length of the pause can be modified with setInputEventTimeout(). As with the TIMEOUT mode, a text change event is forced before a possible ValueChangeEvent, even if the user did not keep a pause while entering the text.

This is the default mode.

TextChangeEventMode.TIMEOUT

A text change in the user interface causes the event to be communicated to the application after a timeout period. If more changes are made during this period, the event sent to the server-side includes the changes made up to the last change. The length of the timeout can be set with setInputEventTimeout().

If a ValueChangeEvent would occur before the timeout period, a TextChangeEvent is triggered before it, on the condition that the text content has changed since the previous TextChangeEvent.

TextChangeEventMode.EAGER

An event is triggered immediately for every change in the text content, typically caused by a key press. The requests are separate and are processed sequentially one after another. Change events are nevertheless communicated asynchronously to the server, so further input can be typed while event requests are being processed.

5.7.5. CSS Style Rules

.v-textfield { }

The HTML structure of TextField is extremely simple, consisting only of an element with v-textfield style.

For example, the following custom style uses dashed border:

.v-textfield-dashing { border: thin dashed;

background: white; /* Has shading image by default */

}

The result is shown in Figure 5.25, “Styling TextField with CSS”.

Figure 5.25. Styling TextField with CSS

The style name for TextField is also used in several components that contain a text input field, even if the text input is not an actual TextField. This ensures that the style of different text input boxes is similar.

5.8. TextArea

TextArea is a multi-line version of the TextField component described in Section 5.7, “TextField”.

The following example creates a simple text area:

116	CSS Style Rules

User Interface Components

// Create the area

TextArea area = new TextArea("Big Area");

// Put some content in it area.setValue("A row\n"+

"Another row\n"+ "Yet another row");

The result is shown in Figure 5.26, “TextArea Example”.

Figure 5.26. TextArea Example

You can set the number of visible rows with setRows() or use the regular setHeight() to define the height in other units. If the actual number of rows exceeds the number, a vertical scrollbar will appear. Setting the height with setRows() leaves space for a horizontal scrollbar, so the actual number of visible rows may be one higher if the scrollbar is not visible.

You can set the width with the regular setWidth() method. Setting the size with the em unit, which is relative to the used font size, is recommended.

Word Wrap

The setWordwrap() sets whether long lines are wrapped (true - default) when the line length reaches the width of the writing area. If the word wrap is disabled (false), a vertical scrollbar will appear instead.The word wrap is only a visual feature and wrapping a long line does not insert line break characters in the field value; shortening a wrapped line will undo the wrapping.

TextArea area1 = new TextArea("Wrapping"); area1.setWordwrap(true); // The default

area1.setValue("A quick brown fox jumps over the lazy dog");

TextArea area2 = new TextArea("Nonwrapping"); area2.setWordwrap(false);

area2.setValue("Victor jagt zwölf Boxkämpfer quer "+ "über den Sylter Deich");

The result is shown in Figure 5.27, “Word Wrap in TextArea”.

Figure 5.27. Word Wrap in TextArea

Word Wrap

117

User Interface Components

CSS Style Rules

.v-textarea { }

The HTML structure of TextArea is extremely simple, consisting only of an element with v-textarea style.

5.9. PasswordField

The PasswordField is a variant of TextField that hides the typed input from visual inspection.

PasswordField tf = new PasswordField("Keep it secret");

The result is shown in Figure 5.28, “PasswordField”.

Figure 5.28. PasswordField

You should note that the PasswordField hides the input only from "over the shoulder" visual observation. Unless the server connection is encrypted with a secure connection, such as HTTPS, the input is transmitted in clear text and may be intercepted by anyone with low-level access to the network. Also phishing attacks that intercept the input in the browser may be possible by exploiting JavaScript execution security holes in the browser.

CSS Style Rules

.v-textfield { }

The PasswordField does not have its own CSS style name but uses the same v-textfield style as the regular TextField. See Section 5.7.5, “CSS Style Rules” for information on styling it.

5.10. RichTextArea

The RichTextArea field allows entering or editing formatted text. The toolbar provides all basic editing functionalities. The text content of RichTextArea is represented in HTML format. RichTextArea inherits TextField and does not add any API functionality over it. You can add new functionality by extending the client-side components VRichTextArea and VRichTextToolbar.

As with TextField, the textual content of the rich text area is the Property of the field and can be set with setValue() and read with getValue().

// Create a rich text area

final RichTextArea rtarea = new RichTextArea(); rtarea.setCaption("My Rich Text Area");

// Set initial content as HTML rtarea.setValue("<h1>Hello</h1>\n" +

"<p>This rich text area contains some text.</p>");

118	CSS Style Rules

User Interface Components

Figure 5.29. Rich Text Area Component

Above, we used context-specific tags such as <h1> in the initial HTML content. The rich text area component does not allow creating such tags, only formatting tags, but it does preserve them unless the user edits them away. Any non-visible whitespace such as the new line character (\n) are removed from the content. For example, the value set above will be as follows when read from the field with getValue():

<h1>Hello</h1> <p>This rich text area contains some text.</p>

The rich text area is one of the few components in Vaadin that contain textual labels.The selection boxes in the toolbar are in English and currently can not be localized in any other way than by inheriting or reimplementing the client-side VRichTextToolbar widget.The buttons can be localized simply with CSS by downloading a copy of the toolbar background image, editing it, and replacing the default toolbar. The toolbar is a single image file from which the individual button icons are picked, so the order of the icons is different from the rendered. The image file depends on the client-side implementation of the toolbar.

.v-richtextarea-richtextexample .gwt-ToggleButton

.gwt-Image {

background-image: url(img/richtextarea-toolbar-fi.png) !important;

}

Figure 5.30. Regular English and a Localized Rich Text Area Toolbar

Cross-Site Scripting with RichTextArea

The user input from a RichTextArea is transmitted as XHTML from the browser to server-side and is not sanitized. As the entire purpose of the RichTextArea component is to allow input of formatted text, you can not sanitize it just by removing all HTML tags. Also many attributes, such as style, should pass through the sanitization.

See Section 11.8.1, “Sanitizing User Input to Prevent Cross-Site Scripting” for more details on Cross-Site scripting vulnerabilities and sanitization of user input.

Cross-Site Scripting with RichTextArea

119