A document that models HTML. The purpose of this model is to support both browsing and editing. As a result, the structure described by an HTML document is not exactly replicated by default. The element structure that is modeled by default, is built by the class
HTMLDocument.HTMLReader
, which implements the
HTMLEditorKit.ParserCallback
protocol that the parser expects. To change the structure one can subclass
HTMLReader
, and reimplement the method
getReader(int)
to return the new reader implementation. The documentation for
HTMLReader
should be consulted for the details of the default structure created. The intent is that the document be non-lossy (although reproducing the HTML format may result in a different format).
The document models only HTML, and makes no attempt to store view attributes in it. The elements are identified by the StyleContext.NameAttribute
attribute, which should always have a value of type HTML.Tag
that identifies the kind of element. Some of the elements (such as comments) are synthesized. The HTMLFactory
uses this attribute to determine what kind of view to build.
This document supports incremental loading. The TokenThreshold
property controls how much of the parse is buffered before trying to update the element structure of the document. This property is set by the EditorKit
so that subclasses can disable it.
The Base
property determines the URL against which relative URLs are resolved. By default, this will be the Document.StreamDescriptionProperty
if the value of the property is a URL. If a <BASE> tag is encountered, the base will become the URL specified by that tag. Because the base URL is a property, it can of course be set directly.
The default content storage mechanism for this document is a gap buffer (GapContent
). Alternatives can be supplied by using the constructor that takes a Content
implementation.
Modifying HTMLDocument
In addition to the methods provided by Document and StyledDocument for mutating an HTMLDocument, HTMLDocument provides a number of convenience methods. The following methods can be used to insert HTML content into an existing document.
The following examples illustrate using these methods. Each example assumes the HTML document is initialized in the following way:
JEditorPane p = new JEditorPane();
p.setContentType("text/html");
p.setText("..."); // Document text is provided below.
HTMLDocument d = (HTMLDocument) p.getDocument();
With the following HTML content:
<html>
<head>
<title>An example HTMLDocument</title>
<style type="text/css">
div { background-color: silver; }
ul { color: blue; }
</style>
</head>
<body>
<div id="BOX">
<p>Paragraph 1</p>
<p>Paragraph 2</p>
</div>
</body>
</html>
All the methods for modifying an HTML document require an Element
. Elements can be obtained from an HTML document by using the method getElement(Element e, Object attribute, Object value)
. It returns the first descendant element that contains the specified attribute with the given value, in depth-first order. For example, d.getElement(d.getDefaultRootElement(), StyleConstants.NameAttribute, HTML.Tag.P)
returns the first paragraph element.
A convenient shortcut for locating elements is the method getElement(String)
; returns an element whose ID
attribute matches the specified value. For example, d.getElement("BOX")
returns the DIV
element.
The getIterator(HTML.Tag t)
method can also be used for finding all occurrences of the specified HTML tag in the document.
Inserting elements
Elements can be inserted before or after the existing children of any non-leaf element by using the methods insertAfterStart
and insertBeforeEnd
. For example, if e
is the DIV
element, d.insertAfterStart(e, "<ul><li>List Item</li></ul>")
inserts the list before the first paragraph, and d.insertBeforeEnd(e, "<ul><li>List Item</li></ul>")
inserts the list after the last paragraph. The DIV
block becomes the parent of the newly inserted elements.
Sibling elements can be inserted before or after any element by using the methods insertBeforeStart
and insertAfterEnd
. For example, if e
is the DIV
element, d.insertBeforeStart(e, "<ul><li>List Item</li></ul>")
inserts the list before the DIV
element, and d.insertAfterEnd(e, "<ul><li>List Item</li></ul>")
inserts the list after the DIV
element. The newly inserted elements become siblings of the DIV
element.
Replacing elements
Elements and all their descendants can be replaced by using the methods setInnerHTML
and setOuterHTML
. For example, if e
is the DIV
element, d.setInnerHTML(e, "<ul><li>List Item</li></ul>")
replaces all children paragraphs with the list, and d.setOuterHTML(e, "<ul><li>List Item</li></ul>")
replaces the DIV
element itself. In latter case the parent of the list is the BODY
element.
Summary
The following table shows the example document and the results of various methods described above.
HTML Content of example above
Example | insertAfterStart | insertBeforeEnd | insertBeforeStart | insertAfterEnd | setInnerHTML | setOuterHTML |
|
|
|
|
|
|
|
Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans has been added to the java.beans
package. Please see XMLEncoder
.