Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 311 insertions, 0 deletions

diff --git a/documentation/components/components-label.asciidoc b/documentation/components/components-label.asciidoc
new file mode 100644
index 0000000000..115de5b376
--- /dev/null
+++ b/documentation/components/components-label.asciidoc
@@ -0,0 +1,311 @@
+---
+title: Label
+order: 7
+layout: page
+---
+
+[[components.label]]
+= [classname]#Label#
+
+ifdef::web[]
+[.sampler]
+image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-presentation/label]
+endif::web[]
+
+[classname]#Label# component displays non-editable text. This text can be used
+for short simple labels or for displaying long text, such as paragraphs. The
+text can be formatted in HTML or as preformatted text, depending on the
+__content mode__ of the label.
+
+You can give the label text most conviniently in the constructor, as is done in
+the following. Label has 100% default width, so the containing layout must also
+have defined width.
+
+
+[source, java]
+----
+// A container that is 100% wide by default
+VerticalLayout layout = new VerticalLayout();
+
+Label label = new Label("Labeling can be dangerous");
+layout.addComponent(label);
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"].
+
+[classname]#Label# implements the [interfacename]#Property# interface to allow
+accessing the text value, so you can get and set the text with
+[methodname]#getValue()# and [methodname]#setValue()#.
+
+
+[source, java]
+----
+// Get the label's text to initialize a field
+TextField editor = new TextField(null, // No caption
+                                 label.getValue());
+        
+// Change the label's text
+editor.addValueChangeListener(event -> // Java 8
+    label.setValue(editor.getValue()));
+editor.setImmediate(true); // Send on Enter
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"].
+
+Label also supports data binding to a property data source, as described later
+in <<components.label.databinding>>. However, in that case the value can not be
+set through the label, as [classname]#Label# is not a
+[interfacename]#Property.Editor# and is not allowed to write to a bound
+property.
+
+Even though [classname]#Label# is text and is often used as a caption, it is a
+normal component and therefore also has a caption that you can set with
+[methodname]#setCaption()#. As with most other components, the caption is
+managed by the containing layout.
+
+[[components.label.wrap]]
+== Text Width and Wrapping
+
+[classname]#Label# has 100% default width, so the containing layout must also
+have a defined width. If the width of the label's text exceeds the width of the
+label, the text will wrap around and continue on the next line. Some layout
+components have undefined width by default, such as
+[classname]#HorizontalLayout#, so you need to pay special care with them.
+
+
+[source, java]
+----
+// A container with a defined width.
+Panel panel = new Panel("Panel Containing a Label");
+panel.setWidth("300px");
+
+panel.setContent(
+    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."));
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.wrap[on-line example, window="_blank"].
+
+As the size of the [classname]#Panel# in the above example is fixed and the
+width of [classname]#Label# is the default 100%, the text in the
+[classname]#Label# will wrap to fit the panel, as shown in
+<<figure.components.label>>.
+
+[[figure.components.label]]
+.The Label Component
+image::img/label-example1.png[]
+
+Setting [classname]#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 [classname]#Label# will overflow the layout
+horizontally and, normally, be truncated.
+
+
+[[components.label.content-mode]]
+== Content Mode
+
+The content of a label is formatted depending on a __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
+[methodname]#setContentMode()#, and can have the values defined in the
+[classname]#ContentMode# enumeration type in
+[package]#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 [literal]#++<++#,
+[literal]#++>++#, and [literal]#++&++# 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 [literal]#++\n++# escape sequence for a newline
+character (ASCII 0x0a), or tabulator characters written with [literal]#++\t++#
+(ASCII 0x09).
+
+HTML:: Content mode where the label contains HTML.
+
++
+Please note the following security and validity warnings regarding the HTML
+content mode.
+
+
+
+
+[WARNING]
+.Cross-Site Scripting Warning
+====
+Having [classname]#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
+<<dummy/../../../framework/advanced/advanced-security#advanced.security.sanitizing,"Sanitizing
+User Input to Prevent Cross-Site 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 [classname]#Label# in different
+modes.
+
+
+[source, java]
+----
+Label textLabel = new Label(
+    "Text where formatting characters, such as \\n, " +
+    "and HTML, such as <b>here</b>, are quoted.",
+    ContentMode.TEXT);
+
+Label preLabel = new Label(
+    "Preformatted text is shown in an HTML <pre> tag.\n" +
+    "Formatting such as\n" +
+    "  * newlines\n" + 
+    "  * whitespace\n" +
+    "and such are preserved. HTML tags, \n"+
+    "such as <b>bold</b>, are quoted.",
+    ContentMode.PREFORMATTED);
+
+Label htmlLabel = new Label(
+    "In HTML mode, all HTML formatting tags, such as \n" +
+    "<ul>"+
+    "  <li><b>bold</b></li>"+
+    "  <li>itemized lists</li>"+
+    "  <li>etc.</li>"+
+    "</ul> "+
+    "are preserved.",
+    ContentMode.HTML);
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.content-modes.contentmodes[on-line example, window="_blank"].
+
+The rendering will look as shown in <<figure.components.label.content-mode>>.
+
+[[figure.components.label.content-mode]]
+.Label Content Modes
+image::img/label-modes.png[]
+
+
+ifdef::web[]
+[[components.label.spacing]]
+== Spacing with a [classname]#Label#
+
+You can use a [classname]#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 height. The same goes
+for a label with only whitespace as the label text. You need to use a
+non-breaking space character, either [literal]#++&nbsp;++# or
+[literal]#++&#160;++#:
+
+
+[source, java]
+----
+layout.addComponent(new Label("&nbsp;", ContentMode.HTML));
+----
+
+Using the [parameter]#ContentMode.PREFORMATTED# mode has the same effect;
+preformatted spaces do not collapse in a vertical layout. In a
+[classname]#HorizontalLayout#, the width of a space character may be
+unpredictable if the label font is proportional, so you can use the preformatted
+mode to add em-width wide spaces.
+
+If you want a gap that has adjustable width or height, you can use an empty
+label if you specify a height or width for it. For example, to create vertical
+space in a [classname]#VerticalLayout#:
+
+
+[source, java]
+----
+Label gap = new Label();
+gap.setHeight("1em");
+verticalLayout.addComponent(gap);
+----
+
+You can make a flexible expanding spacer by having a relatively sized empty
+label with [literal]#++100%++# height or width and setting the label as
+expanding in the layout.
+
+
+[source, java]
+----
+// A wide component bar
+HorizontalLayout horizontal = new HorizontalLayout();
+horizontal.setWidth("100%");
+
+// Have a component before the gap (a collapsing cell)
+Button button1 = new Button("I'm on the left");
+horizontal.addComponent(button1);
+
+// An expanding gap spacer
+Label expandingGap = new Label();
+expandingGap.setWidth("100%");
+horizontal.addComponent(expandingGap);
+horizontal.setExpandRatio(expandingGap, 1.0f);
+
+// A component after the gap (a collapsing cell)
+Button button2 = new Button("I'm on the right");
+horizontal.addComponent(button2);
+----
+
+endif::web[]
+
+[[components.label.databinding]]
+== Data Binding
+
+While [classname]#Label# is not a field component, it is a
+[interfacename]#Property.Viewer# and can be bound to a property data source,
+described in
+<<dummy/../../../framework/datamodel/datamodel-properties#datamodel.properties,"Properties">>.
+You can specify the data source either in the constructor or by the
+[methodname]#setPropertyDataSource()# method.
+
+
+[source, java]
+----
+// Some property
+ObjectProperty<String> property =
+    new ObjectProperty<String>("some value");
+        
+// Label that is bound to the property
+Label label = new Label(property);
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.binding[on-line example, window="_blank"].
+
+Further, as [classname]#Label# is a [interfacename]#Property#, you can edit its
+value with a property editor, such as a field:
+
+
+[source, java]
+----
+Label label = new Label("some value");
+TextField editor = new TextField();
+editor.setPropertyDataSource(label);
+editor.setImmediate(true);
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.delegation[on-line example, window="_blank"].
+
+However, [classname]#Label# is __not__ a [interfacename]#Property.Editor#, so it
+is read-only when bound to a data source. Therefore, you can not use
+[methodname]#setValue()# to set the value of a connected data source through a
+[classname]#Label# nor bind the label to an editor field, in which case writes
+would be delegated through the label.
+
+
+[[components.label.css]]
+== CSS Style Rules
+
+
+[source, css]
+----
+.v-label { }
+  pre { } /* In PREFORMATTED content mode */
+----
+
+The [classname]#Label# component has a [literal]#++v-label++# overall style. In
+the [parameter]#PREFORMATTED# content mode, the text is wrapped inside a
+[literal]#++<pre>++# element.
+
+
+
+