Use cases

HTMLComponent can be used to render local or remote documents. It extends Container and as such it can be added to any Form.

HTMLComponent uses an internal parser to parse the given HTML documents. The parser is not 100% strict and can tolerate some errors in the document; however, some errors may be too fatal for the parser. It is very important to stick to the XHTML-MP1 standard. You must close all open tags in the correct hierarchical order.

Rendering rich text

The most simple use case of HTMLComponent is rendering rich text:

HTMLComponent htmlC = new HTMLComponent(null);
htmlC.setBodyText("Hello <b>bold text</b>");

The only parameter the constructor expects is a class implementing the DocumentRequestHandler interface (for the implementation, check the HTMLDemo class of LWUIT Demo example application, available in the <Nokia SDK 2.0 for Java installation directory>\plugins\lwuit\examples). This interface defines how links and external resources (such as images, CSS files) in the document are fetched.

Since the example does not use links, we can specify null instead of the document handler. In this case, if links or external resources are specified in the document body, they are disabled or ignored.

setBodyText accepts a string containing any text with XHTML-MP 1.0 tags. The text is wrapped with the HTML and BODY tags and passed on for parsing.

If the text is encoded, you can specify the encoding as follows:

setBodyText(String htmlText,String encoding)

If you have a full HTML file and not just the body text, the following can be used:

setHTML(String htmlText,String encoding,String title,boolean isFullHTML)

To make the HTMLComponent visible, add it to a form and display that form. For example:

Form form = new Form("HTML Component");
form.setLayout(new BorderLayout());
form.addComponent(BorderLayout.CENTER,htmlC);
form.show();

Figure: Rich text rendered using HTMLComponent

Reading HTML and enabling external resources

The most common use case for HTMLComponent is reading HTML files from either a local or remote source, while enabling external resources such as images and CSS files, and allowing the user to follow links.

To support this use case, you must first implement a DocumentRequestHandler interface that contains a single method:

InputStream resourceRequested(DocumentInfo docInfo)

This method is called by HTMLComponent (and other internal classes in the html package) to obtain the InputStream of the specified document. Requested documents are HTML files (followed links), referenced CSS files, and referenced images.

The requested document information is stored in a DocumentInfo object, which is populated automatically by HTMLComponent. The DocumentInfo values can be used to determine the document's path, file name, type, et cetera.

This example does not implement a DocumentRequestHandler. It uses the HttpRequestHandler (a ready-made implementation that can be found in the LWUITBrowser application) instead. LWUITBrowser be checked out from the LWUIT SVN under MIDP/applications.

HttpRequestHandler implementation supports fetching HTML documents via both HTTP and from a JAR file. It supports cookies, encoding, error handling, and caching via the Storage class (also available in LWUITBrowser).

The following sample code uses HTMLComponent and HttpRequestHandler to browse to the mobile Facebook site (tested to work on the Nokia SDK 1.1 for Java and Nokia SDK 2.0 for Java):

HttpRequestHandler handler = new HttpRequestHandler();
HTMLComponent htmlC = new HTMLComponent(handler);
htmlC.setPage("http://m.facebook.com");

The setPage method accepts a String containing the URL to be rendered. This can be a remote resource (such as http://address) or a local file in the JAR (such as file:///somepath/somefile). Alternatively it can be any kind of URL that our implementation of DocumentRequestHandler "understands".

After showing the above HTMLComponent on a form, the user can view the HTML at the specified address (including images and CSS), and follow links.