User Interface Components

5.4. Component Extensions

Components can have extensions which are attached to a component dynamically. Especially many add-on features are extensions.

To add an extension to a component, call the extend() method in the extension.

TextField tf = new TextField("Hello"); layout.addComponent(tf);

// Add a simple extension

new CapsLockWarning().extend(tf);

// Add an extension that requires some parameters CSValidator validator = new CSValidator(); validator.setRegExp("[0-9]*"); validator.setErrorMessage("Must be a number"); validator.extend(tf);

5.5. Label

Label is a text component that displays non-editable text. In addition to regular text, you can also display preformatted text and HTML, depending on the content mode of the label.

// A container that is 100% wide by default VerticalLayout layout = new VerticalLayout();

Label label = new Label("Labeling can be dangerous"); layout.addComponent(label);

The text will wrap around and continue on the next line if it exceeds the width of the Label. The default width is 100%, so the containing layout must also have a defined width. Some layout components have undefined width by default, such as HorizontalLayout, so you need to pay special care with them.

//A container with a defined width. The default content layout

//of Panel is VerticalLayout, which has 100% default width. Panel panel = new Panel("Panel Containing a Label"); panel.setWidth("300px");

panel.addComponent(

new Label("This is a Label inside a Panel. There is " + "enough text in the label to make the text " + "wrap when it exceeds the width of the panel."));

As the size of the Panel in the above example is fixed and the width of Label is the default 100%, the text in the Label will wrap to fit the panel, as shown in Figure 5.16, “The Label Component”.

Figure 5.16. The Label Component

Component Extensions

107

User Interface Components

Setting Label to undefined width will cause it to not wrap at the end of the line, as the width of the content defines the width. If placed inside a layout with defined width, the Label will overflow the layout horizontally and, normally, be truncated.

Even though Label is text and often used as a caption, it also has a caption, just like any other component. As with other components, the caption is managed by the containing layout.

5.5.1. Content Mode

The contents of a label are formatted depending on the content mode. By default, the text is assumed to be plain text and any contained XML-specific characters will be quoted appropriately to allow rendering the contents of a label in HTML in a web browser. The content mode can be set in the constructor or with setContentMode(), and can have the values defined in the ContentMode enumeration type in com.vaadin.shared.ui.label package:

TEXT

The default content mode where the label contains only plain text. All characters are allowed, including the special <, >, and & characters in XML or HTML, which are quoted properly in HTML while rendering the component. This is the default mode.

PREFORMATTED

Content mode where the label contains preformatted text. It will be, by default, rendered with a fixed-width typewriter font. Preformatted text can contain line breaks, written in Java with the \n escape sequence for a newline character (ASCII 0x0a), or tabulator characters written with \t (ASCII 0x08).

HTML

Content mode where the label contains (X)HTML. The content will be enclosed in a D I V e l e m e n t h a v i n g t h e n a m e s p a c e "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd".

Please note the following security and validity warnings regarding the HTML content mode.

Cross-Site Scripting Warning

Having Label in HTML content mode allows pure HTML content. If the content comes from user input, you should always carefully sanitize it to prevent cross-site scripting (XSS) attacks. Please see Section 11.8.1, “Sanitizing User Input to Prevent CrossSite Scripting”.

Also, the validity of the HTML content is not checked when rendering the component and any errors can result in an error in the browser. If the content comes from an uncertain source, you should always validate it before displaying it in the component.

The following example demonstrates the use of Label in different modes.

GridLayout labelgrid = new GridLayout (2,1);

labelgrid.addComponent (new Label ("PREFORMATTED")); labelgrid.addComponent (

new Label ("This is a preformatted label.\n"+

"The newline character \\n breaks the line.", Label.ContentMode.PREFORMATTED));

labelgrid.addComponent (new Label ("TEXT")); labelgrid.addComponent (

108	Content Mode

User Interface Components

new Label ("This is a label in (plain) text mode", Label.ContentMode.TEXT));

labelgrid.addComponent (new Label ("HTML")); labelgrid.addComponent (

new Label ("<i>This</i> is an <b>HTML</b> formatted label", Label.ContentMode.HTML));

layout.addComponent(labelgrid);

The rendering will look as follows:

Figure 5.17. Label Modes Rendered on Screen

5.5.2. Making Use of the HTML Mode

Using the HTML modes allows inclusion of, for example, images within the text flow, which is not possible with any regular layout components. The following example includes an image within the text flow, with the image coming from a class loader resource.

- This does not work at the moment -

ClassResource labelimage = new ClassResource ("labelimage.jpg"); main.addComponent(new Label("Here we have an image <img src=\"" + this.getRelativeLocation(labelimage) +

"\"/> within text.", Label.ContentMode.XHTML));

When you use a class loader resource, the image has to be included in the JAR of the web application. In this case, the labelimage.jpg needs to be in the default package. When rendered in a web browser, the output will look as follows:

Figure 5.18. Referencing An Image Resource in Label

Another solution would be to use the CustomLayout component, where you can write the component content as an HTML fragment in a theme, but such a solution may be too heavy for most cases.

5.5.3. Spacing with a Label

You can use a Label to create vertical or horizontal space in a layout. If you need a empty "line" in a vertical layout, having just a label with empty text is not enough, as it will collapse to zero

Making Use of the HTML Mode

109