Recipe 8.10 Displaying HTML-Formatted Text

8.10.1 Problem

You want to display HTML content in a text field.

8.10.2 Solution

Set the text field's html property to true, and set the htmlText property to the value of the HTML content to display.

8.10.3 Discussion

Text fields can interpret and display basic HTML tags, if properly configured. Using HTML in a text field is a convenient way to add links and simple formatting, such as font color and bold text.

Text fields display plain text by default. To enable HTML formatting, set the field's html property to true:

myTextField.html = true;

Once the html property is set to true, the value of the object's htmlText property will be interpreted as HTML:

myTextField.htmlText = "<u>this will display as underlined text</u>";

Set the html property to true before setting the htmlText property; otherwise, the value of htmlText will not be interpreted as HTML.

When the html property is false (which is the default), the htmlText property value is rendered as regular text. But when html is set to true, the htmlText property is rendered as HTML complete with <p> and <font> markup tags:

myTextField.html = false; myTextField.htmlText = "test"; trace(myTextField.htmlText); /* Output window displays: test */ myTextField.html = true; myTextField.htmlText = "test"; trace(myTextField.htmlText); /* Output window displays: <P ALIGN="LEFT"><FONT FACE="Times New Roman"      SIZE="12" COLOR="#000000">test</FONT></P> */

No matter what, the text property of a text field is rendered as plain text. This means that even if the html property is true, if the text property is set to <u>test</u>, the object will display <u>test</u> instead of test.

Despite the fact that they appear to be two properties, text and htmlText are linked such that when one is altered, the other is as well. This means that you should not try to assign different values to each. Whatever value is assigned to text is also assigned to htmlText (with additional HTML flourish if the html property is set to true), and vice versa. You can test this for yourself, as follows:

myTextField.html = true; myTextField.htmlText = "htmlText value"; trace(myTextField.text); trace(myTextField.htmlText); myTextField.text = "text value"; trace(myTextField.text); trace(myTextField.htmlText); /* Output window displays: htmlText value <P ALIGN="LEFT"><FONT FACE="Times New Roman"     SIZE="12" COLOR="#000000">htmlText value</FONT></P> text value <P ALIGN="LEFT"><FONT FACE="Times New Roman"     SIZE="12" COLOR="#000000">text value</FONT></P> */

The htmlText property is a little quirky. Each time you append a new value to the htmlText property, the appended value is wrapped in a <p> element. Therefore, if you assign a value to an object's htmlText property and then append another value to htmlText, the two values will be displayed on two different lines even if no line-breaking tags were specified:

myTextField.html = true; myTextField.htmlText = "a"; myTextField.htmlText += "b"; trace(myTextField.htmlText); /* Output window displays: <P ALIGN="LEFT"><FONT FACE="_sans" SIZE="12"     COLOR="#000000">a</FONT></P> <P ALIGN="LEFT"><FONT FACE="_sans" SIZE="12"     COLOR="#000000">b</FONT></P> */

A simple solution to this problem is to append the values to a string variable and then assign that variable's value to the htmlText property in a single assignment statement:

myTextField.html = true; var htmlTextVal = "a"; htmlTextVal += "b"; myTextField.htmlText = htmlTextVal; trace(myTextField.htmlText); /* Output window displays: <P ALIGN="LEFT"><FONT FACE="_sans" SIZE="12" COLOR="#000000">ab</FONT></P> */

If you want to display HTML code in its unrendered format, set the html property to false and assign the HTML value to the text property of the text field, as follows:

myTextField.html = false; myTextField.text = "<u>underlined text</u>"; /* Text field displays: <u>underlined text</u> */

This can be a useful technique if, for example, you want to show both the rendered HTML and the HTML source code in side-by-side text fields:

htmlCode = "<i>italicized text</i>"; sourceHTML.html = false; sourceHTML.text = htmlCode; renderedHTML.html = true; renderedHTML.htmlText = htmlCode;

You cannot display both rendered and unrendered HTML in the same text field. If you try to do so, you will end up with unreliable results.

Additionally, you cannot toggle between the viewing of rendered and unrendered HTML in a text field. For example, if you set a text field's html property to true, add HTML content, and set the html property to false, the displayed text appears as rendered HTML, not as HTML source code.

The set of HTML tags supported by Flash 5 text fields includes: <B>, <I>, <U>, <FONT> (with FACE, SIZE, and COLOR attributes), <P>, <BR>, and <A>. Flash 6 adds support for <LI> and <TEXTFORMAT> (with LEFTMARGIN, RIGHTMARGIN, BLOCKINDENT, INDENT, LEADING, and TABSTOPS attributes corresponding to the TextFormat class's properties of the same names).

8.10.4 See Also

Appendix E of ActionScript for Flash MX: The Definitive Guide gives full details on Flash's support for HTML tags.