Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 128 insertions, 0 deletions

diff --git a/documentation/components/components-richtextarea.asciidoc b/documentation/components/components-richtextarea.asciidoc
new file mode 100644
index 0000000000..ff354cfe8d
--- /dev/null
+++ b/documentation/components/components-richtextarea.asciidoc
@@ -0,0 +1,128 @@
+---
+title: RichTextArea
+order: 12
+layout: page
+---
+
+[[components.richtextarea]]
+= [classname]#RichTextArea#
+
+ifdef::web[]
+[.sampler]
+image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/text-input/rich-text-area]
+endif::web[]
+
+The [classname]#RichTextArea# field allows entering or editing formatted text.
+The toolbar provides all basic editing functionalities. The text content of
+[classname]#RichTextArea# is represented in HTML format.
+[classname]#RichTextArea# inherits [classname]#TextField# and does not add any
+API functionality over it. You can add new functionality by extending the
+client-side components [classname]#VRichTextArea# and
+[classname]#VRichTextToolbar#.
+
+As with [classname]#TextField#, the textual content of the rich text area is the
+[classname]#Property# of the field and can be set with [methodname]#setValue()#
+and read with [methodname]#getValue()#.
+
+
+[source, java]
+----
+// 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>");
+----
+
+.Rich Text Area Component
+image::img/richtextarea-example1.png[]
+
+Above, we used context-specific tags such as [literal]#++<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 ( [literal]#++\n++#)
+are removed from the content. For example, the value set above will be as
+follows when read from the field with [methodname]#getValue()#:
+
+
+[source, html]
+----
+<h1>Hello</h1> <p>This rich text area contains some text.</p>
+----
+
+
+[WARNING]
+.Cross-Site Scripting Warning
+====
+The user input from a [classname]#RichTextArea# is transmitted as HTML from the
+browser to server-side and is not sanitized. As the entire purpose of the
+[classname]#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
+[parameter]#style#, should pass through the sanitization.
+
+See
+<<dummy/../../../framework/advanced/advanced-security#advanced.security.sanitizing,"Sanitizing
+User Input to Prevent Cross-Site Scripting">> for more details on Cross-Site
+scripting vulnerabilities and sanitization of user input.
+
+====
+
+
+
+ifdef::web[]
+[[components.richtextarea.localization]]
+== Localizing RichTextArea Toolbars
+
+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 [classname]#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.
+
+
+[source, css]
+----
+.v-richtextarea-richtextexample .gwt-ToggleButton
+.gwt-Image {
+  background-image: url(img/richtextarea-toolbar-fi.png)
+                    !important;
+}
+----
+
+.Regular English and a Localized Rich Text Area Toolbar
+image::img/richtextarea-toolbar-whitebg.png[]
+
+endif::web[]
+
+== CSS Style Rules
+
+
+[source, css]
+----
+.v-richtextarea { }
+.v-richtextarea .gwt-RichTextToolbar { }
+.v-richtextarea .gwt-RichTextArea { }
+----
+
+The rich text area consists of two main parts: the toolbar with overall style
+[literal]#++.gwt-RichTextToolbar++# and the editor area with style
+[literal]#++.gwt-RichTextArea++#. The editor area obviously contains all the
+elements and their styles that the HTML content contains. The toolbar contains
+buttons and drop-down list boxes with the following respective style names:
+
+
+[source, css]
+----
+.gwt-ToggleButton { }
+.gwt-ListBox { }
+----
+
+
+
+