Rich text

Rich text behavior is attempting to parse certain markup tags in the text as line control characters or instructions for rendering nested text. You can enable rich text behavior for <label> and derived components. For most of these components, the behavior is enabled only if attribute richText="true". For the <textView> component; however, the behavior is enabled by default and attribute richText must be set to false to disable it.

To use rich-text markup, the rich text must be well-formed XML (except that no top-level node is required), where XML elements specify markup, and text nodes in the XML specify actual text. For instance:

Well hello, world, welcome to a brand new line.

specifies that the text should appear as

Well hello, world,
welcome to a brand new line.

This is a valid rich text specification, because any opening tag such as  is matched by a following closing tag (like ) at the same level of tag nesting. If rich text behavior is specified and the text is not well-formed XML, rich text behavior is disabled and the entire text is rendered as plain text. For instance,

Well hello, </j> world, welcome to a brand new line.

would appear as it appears here, brackets and all.

Specifying Text

For most label-derived components, text is specified with the text attribute:

<button text="press me"/><textField text="type here"/>

For the textArea and textView components, text is specified by nested text within the textArea or textView tag, for instance:<textView>The textView's text</textView> In either case, special care is required when the text contains rich text tags. < and > in an attribute must be escaped, for example: <button richText="true" text="press me"/>. Note that the attribute richText is set to true. For textView this attribute is on by default. For all other text labels it should be specified. For example, to put rich text in a textView:

<textView>
    &lt;p&gt;Paragraph 1&lt;/p&gt;&lt;p&gt;Paragraph 2&lt;/p&gt;
</textView>

In the textView case, it easiest to use CDATA syntax. Text between <![CDATA[ and ]]> is not escaped, so the above can be more readably written:

<textView>
<![CDATA[
    <p>Paragraph 1.</p><p>Paragraph 2.</p>
]]>
</textView>

To display the tags ">" and "<" they must be "doubly escaped" (or singly escaped within a CDATA section. For example to display "<" the correct text in an attribute would be "&lt;", and

<button richText="true" text="&lt;your name&gt; here"/> would appear as

richText Supported Tags

The following table provides a list and description of the tags supported in richText:

Tag	Description	Attributes	Example
<font>	Renders enclosed text in a font.	color: should be the same form as fontColor size: should be the same form as fontSize face: should be the same form as fontName	<font color="red">red</font> unred
<i>	Makes enclosed text italic.	N/A	<i>tilted</i>
<b>	Makes enclosed text bold.	N/A	<b>bold</b>
<u>	Makes enclosed text underlined.	N/A	<u>underlined</u>
<br>	Inserts a line break.	N/A	Text.<br/>Text on new line.
<hr>	Inserts a horizontal line.	N/A	Text.<hr/>Text following line.
<p>	Skips a line.	align: left, center, or right	Text.<p/>New paragraph.
<img>	Inserts an in-line image.	src: A reference to a GIF-format or JPEG-format image document, in the form "/" plus a web-application-relative partial URL.	cool <img src="/folder/cool.gif"/> graphic
<link>	Defines an onCommand action or a tooltip for enclosed text.	onCommand: Specification of type text-event-attribute-type of event to be invoked when enclosed text is clicked. tooltip: Specified tooltip for enclosed text.	<link onCommand="moreInfo.jsp">click for more info</link>

Rich Text and Editing

User Editing

Usually textField, passwordField and textArea are used for editing plain text. However textArea and textField can be used with rich text as well. The Nexaweb client attempts to maintain well-formedness of the text through insertion, deletion, and replacement by ensuring pairs of opening and closing tags are not broken up.

Editing Attribute "API"

In addition to reading and setting attribute text (or the text child of a textArea), the dynamic attributes: cursorIndex,endSelectIndex, selectedText, and selectedStyle can be read and set. Collectively these dynamic attributes form an "API" for changing text or selection without replacing the entire text. Note that selectedText returns only plain text from the current selection, whereas text represents text and markup together. Setting selectedText removes matched pairs of markup tags as well as plain text in any selection before inserting the new text. Setting selectedStyle adds and removes markup as necessary to effect the passed text style over the current selection. See the UI schema for more discussion of these dynamic editing attributes.

Rich Text and Automatic Line Wrapping

When a <label>-derived component's autoWrap attribute is set true, lines are automatically broken into multiple lines so each fits in the width of the component. (For best results, a component's width should be fixed in one way or another when using automatic wrapping.) autoWrap behavior is true by default for textArea and textView. Additionally, setting richText=true enablesautoWrap behavior unless autoWrap is specifically set to false.