org.eclipse.mylyn.wikitext.core.parser.builder
Class HtmlDocumentBuilder

java.lang.Object
  extended by org.eclipse.mylyn.wikitext.core.parser.DocumentBuilder
      extended by org.eclipse.mylyn.wikitext.core.parser.builder.AbstractXmlDocumentBuilder
          extended by org.eclipse.mylyn.wikitext.core.parser.builder.HtmlDocumentBuilder

public class HtmlDocumentBuilder
extends AbstractXmlDocumentBuilder

A builder that produces XHTML output. The nature of the output is affected by various settings on the builder.

Since:
1.0
Author:
David Green, Matthias Kempka extensibility improvements, see bug 259089

Nested Class Summary
static class HtmlDocumentBuilder.Stylesheet
          A CSS stylesheet definition, created via one of addCssStylesheet(File) or addCssStylesheet(String).
 
Nested classes/interfaces inherited from class org.eclipse.mylyn.wikitext.core.parser.DocumentBuilder
DocumentBuilder.BlockType, DocumentBuilder.SpanType
 
Field Summary
 
Fields inherited from class org.eclipse.mylyn.wikitext.core.parser.builder.AbstractXmlDocumentBuilder
base, baseInHead, writer
 
Fields inherited from class org.eclipse.mylyn.wikitext.core.parser.DocumentBuilder
locator
 
Constructor Summary
HtmlDocumentBuilder(Writer out)
          construct the HtmlDocumentBuilder.
HtmlDocumentBuilder(Writer out, boolean formatting)
          construct the HtmlDocumentBuilder.
HtmlDocumentBuilder(XmlStreamWriter writer)
          construct the HtmlDocumentBuilder.
 
Method Summary
 void acronym(String text, String definition)
          Emit an acronym
 void addCssStylesheet(File file)
          Deprecated. use addCssStylesheet(Stylesheet) instead
 void addCssStylesheet(HtmlDocumentBuilder.Stylesheet stylesheet)
          Add a CSS stylesheet to the output document.
 void addCssStylesheet(String url)
          Deprecated. use addCssStylesheet(Stylesheet) instead
 void beginBlock(DocumentBuilder.BlockType type, Attributes attributes)
          Begin a block of the specified type.
protected  void beginBody()
          begin the body by emitting the body element.
 void beginDocument()
          Begin a document.
 void beginHeading(int level, Attributes attributes)
          Begin a heading of the specified level (usually 1-6).
 void beginLink(Attributes attributes, String hrefOrHashName)
           
 void beginSpan(DocumentBuilder.SpanType type, Attributes attributes)
          Begin a span of the specified type.
 void charactersUnescaped(String literal)
          Create unescaped characters, usually with some embedded HTML markup.
protected  void checkFileReadable(File file)
           
 void copyConfiguration(HtmlDocumentBuilder other)
          Copy the configuration of this builder to the provided one.
protected static XmlStreamWriter createFormattingXmlStreamWriter(Writer out)
           
protected  void emitAnchorHref(String href)
          emit the href attribute of an anchor.
protected  void emitHeadContents()
          emit the contents of the HTML head, excluding the head tag itself.
 void endBlock()
          End a block that was started.
protected  void endBody()
          end the body by emitting the body end element tag.
 void endDocument()
          End a document.
 void endHeading()
          End a span that was started.
 void endLink()
           
 void endSpan()
          End a span that was started.
 void entityReference(String entity)
          An XML entity reference.
 String getDefaultAbsoluteLinkTarget()
          A default target attribute for links that have absolute (not relative) urls.
 String getEncoding()
          Specify the character encoding for use in the HTML meta tag.
 String getHtmlDtd()
          The DTD to emit, if isEmitDtd() and isEmitAsDocument().
 String getHtmlNsUri()
          The XML Namespace URI of the HTML elements, only used if isEmitAsDocument().
 String getLinkRel()
          The 'rel' value for HTML links.
 String getPrependImagePrefix()
          if specified, the prefix is prepended to relative image urls.
protected  Reader getReader(File inputFile)
           
 String getTitle()
          Set the document title, which will be emitted into the <title> element.
 void image(Attributes attributes, String url)
          Build the image with the given attributes
 void imageLink(Attributes linkAttributes, Attributes imageAttributes, String href, String imageUrl)
          Create a hyperlink whose visual representation is an image.
 boolean isEmitAsDocument()
          Indicate if the resulting HTML should be emitted as a document.
 boolean isEmitDtd()
          Indicate if the resulting HTML should include a DTD.
 boolean isSuppressBuiltInStyles()
          indicate if default built-in CSS styles should be suppressed.
 boolean isUseInlineStyles()
          Indicate if inline styles should be used when creating output such as text boxes.
 boolean isXhtmlStrict()
          indicate if the builder should attempt to conform to strict XHTML rules.
 void lineBreak()
          Create a line break (eg: br in html).
 void link(Attributes attributes, String hrefOrHashName, String text)
          Create a hyperlink to the given url.
 void setDefaultAbsoluteLinkTarget(String defaultAbsoluteLinkTarget)
          A default target attribute for links that have absolute (not relative) urls.
 void setEmitAsDocument(boolean emitAsDocument)
          Indicate if the resulting HTML should be emitted as a document.
 void setEmitDtd(boolean emitDtd)
          Indicate if the resulting HTML should include a DTD.
 void setEncoding(String encoding)
          Specify the character encoding for use in the HTML meta tag.
 void setHtmlDtd(String htmlDtd)
          The DTD to emit, if isEmitDtd() and isEmitAsDocument().
 void setHtmlNsUri(String htmlNsUri)
          The XML Namespace URI of the HTML elements, only used if isEmitAsDocument().
 void setLinkRel(String linkRel)
          The 'rel' value for HTML links.
 void setPrependImagePrefix(String prependImagePrefix)
          if specified, the prefix is prepended to relative image urls.
 void setSuppressBuiltInStyles(boolean suppressBuiltInStyles)
          indicate if default built-in CSS styles should be suppressed.
 void setTitle(String title)
          Set the document title, which will be emitted into the <title> element.
 void setUseInlineStyles(boolean useInlineStyles)
          Indicate if inline styles should be used when creating output such as text boxes.
 void setXhtmlStrict(boolean xhtmlStrict)
          indicate if the builder should attempt to conform to strict XHTML rules.
 
Methods inherited from class org.eclipse.mylyn.wikitext.core.parser.builder.AbstractXmlDocumentBuilder
characters, createXmlStreamWriter, getBase, getElementNestLevel, isBaseInHead, isExternalLink, makeUrlAbsolute, setBase, setBaseInHead
 
Methods inherited from class org.eclipse.mylyn.wikitext.core.parser.DocumentBuilder
annotation, getLocator, imageLink, imageLink, link, setLocator
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HtmlDocumentBuilder

public HtmlDocumentBuilder(Writer out)
construct the HtmlDocumentBuilder.

Parameters:
out - the writer to which content is written

HtmlDocumentBuilder

public HtmlDocumentBuilder(Writer out,
                           boolean formatting)
construct the HtmlDocumentBuilder.

Parameters:
out - the writer to which content is written
formatting - indicate if the output should be formatted

HtmlDocumentBuilder

public HtmlDocumentBuilder(XmlStreamWriter writer)
construct the HtmlDocumentBuilder.

Parameters:
writer - the writer to which content is written
Method Detail

copyConfiguration

public void copyConfiguration(HtmlDocumentBuilder other)
Copy the configuration of this builder to the provided one. After calling this method the configuration of the other builder should be the same as this one, including stylesheets. Subclasses that have configurable settings should override this method to ensure that those settings are properly copied.

Parameters:
other - the builder to which settings are copied.

createFormattingXmlStreamWriter

protected static XmlStreamWriter createFormattingXmlStreamWriter(Writer out)

getHtmlNsUri

public String getHtmlNsUri()
The XML Namespace URI of the HTML elements, only used if isEmitAsDocument(). The default value is " http://www.w3.org/1999/xhtml".


setHtmlNsUri

public void setHtmlNsUri(String htmlNsUri)
The XML Namespace URI of the HTML elements, only used if isEmitAsDocument(). The default value is " http://www.w3.org/1999/xhtml".


getHtmlDtd

public String getHtmlDtd()
The DTD to emit, if isEmitDtd() and isEmitAsDocument(). The default value is <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


setHtmlDtd

public void setHtmlDtd(String htmlDtd)
The DTD to emit, if isEmitDtd() and isEmitAsDocument().

See Also:
getHtmlDtd()

isEmitAsDocument

public boolean isEmitAsDocument()
Indicate if the resulting HTML should be emitted as a document. If false, the html and body tags are not included in the output. Default value is true.


setEmitAsDocument

public void setEmitAsDocument(boolean emitAsDocument)
Indicate if the resulting HTML should be emitted as a document. If false, the html and body tags are not included in the output. Default value is true.


isEmitDtd

public boolean isEmitDtd()
Indicate if the resulting HTML should include a DTD. Ignored unless isEmitAsDocument(). Default value is false.


setEmitDtd

public void setEmitDtd(boolean emitDtd)
Indicate if the resulting HTML should include a DTD. Ignored unless isEmitAsDocument(). Default value is false.


getEncoding

public String getEncoding()
Specify the character encoding for use in the HTML meta tag. For example, if the charset is specified as "utf-8": <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> The default is "utf-8". Ignored unless isEmitAsDocument()


setEncoding

public void setEncoding(String encoding)
Specify the character encoding for use in the HTML meta tag. For example, if the charset is specified as "utf-8": <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> The default is "utf-8".

Parameters:
encoding - the character encoding to use, or null if the HTML meta tag should not be emitted Ignored unless isEmitAsDocument()

getTitle

public String getTitle()
Set the document title, which will be emitted into the <title> element. Ignored unless isEmitAsDocument()

Returns:
the title or null if there is none

setTitle

public void setTitle(String title)
Set the document title, which will be emitted into the <title> element. Ignored unless isEmitAsDocument()

Parameters:
title - the title or null if there is none

getDefaultAbsoluteLinkTarget

public String getDefaultAbsoluteLinkTarget()
A default target attribute for links that have absolute (not relative) urls. By default this value is null. Setting this value will cause all HTML anchors to have their target attribute set if it's not explicitly specified in a LinkAttributes.


setDefaultAbsoluteLinkTarget

public void setDefaultAbsoluteLinkTarget(String defaultAbsoluteLinkTarget)
A default target attribute for links that have absolute (not relative) urls. By default this value is null. Setting this value will cause all HTML anchors to have their target attribute set if it's not explicitly specified in a LinkAttributes.


isXhtmlStrict

public boolean isXhtmlStrict()
indicate if the builder should attempt to conform to strict XHTML rules. The default is false.


setXhtmlStrict

public void setXhtmlStrict(boolean xhtmlStrict)
indicate if the builder should attempt to conform to strict XHTML rules. The default is false.


addCssStylesheet

@Deprecated
public void addCssStylesheet(String url)
Deprecated. use addCssStylesheet(Stylesheet) instead

Add a CSS stylesheet to the output document as an URL, where the CSS stylesheet is referenced as an HTML link. Calling this method after starting the document has no effect. Generates code similar to the following: <link type="text/css" rel="stylesheet" href="url"/>

Parameters:
url - the CSS url to use, which may be relative or absolute
See Also:
addCssStylesheet(File)

addCssStylesheet

@Deprecated
public void addCssStylesheet(File file)
Deprecated. use addCssStylesheet(Stylesheet) instead

Add a CSS stylesheet to the output document, where the contents of the CSS stylesheet are embedded in the HTML. Calling this method after starting the document has no effect. Generates code similar to the following:
 <code>
   <style type="text/css">
   ... contents of the file ...
   </style>
 </code>
 

Parameters:
file - the CSS file whose contents must be available
See Also:
addCssStylesheet(String)

addCssStylesheet

public void addCssStylesheet(HtmlDocumentBuilder.Stylesheet stylesheet)
Add a CSS stylesheet to the output document. Calling this method after starting the document has no effect.


checkFileReadable

protected void checkFileReadable(File file)

isUseInlineStyles

public boolean isUseInlineStyles()
Indicate if inline styles should be used when creating output such as text boxes. When disabled inline styles are suppressed and CSS classes are used instead, with the default styles emitted as a stylesheet in the document head. If disabled and isEmitAsDocument() is false, this option has the same effect as isSuppressBuiltInStyles(). The default is true.

See Also:
isSuppressBuiltInStyles()

setUseInlineStyles

public void setUseInlineStyles(boolean useInlineStyles)
Indicate if inline styles should be used when creating output such as text boxes. When disabled inline styles are suppressed and CSS classes are used instead, with the default styles emitted as a stylesheet in the document head. If disabled and isEmitAsDocument() is false, this option has the same effect as isSuppressBuiltInStyles(). The default is true.


isSuppressBuiltInStyles

public boolean isSuppressBuiltInStyles()
indicate if default built-in CSS styles should be suppressed. Built-in styles are styles that are emitted by this builder to create the desired visual effect when rendering certain types of elements, such as warnings or infos. the default is false.

See Also:
isUseInlineStyles()

setSuppressBuiltInStyles

public void setSuppressBuiltInStyles(boolean suppressBuiltInStyles)
indicate if default built-in CSS styles should be suppressed. Built-in styles are styles that are emitted by this builder to create the desired visual effect when rendering certain types of elements, such as warnings or infos. the default is false.


getLinkRel

public String getLinkRel()
The 'rel' value for HTML links. If specified the value is applied to all links generated by the builder. The default value is null. Setting this value to "nofollow" is recommended for rendering HTML in areas where users may add links, for example in a blog comment. See http://en.wikipedia.org/wiki/Nofollow for more information.

Returns:
the rel or null if there is none.
See Also:
LinkAttributes.getRel()

setLinkRel

public void setLinkRel(String linkRel)
The 'rel' value for HTML links. If specified the value is applied to all links generated by the builder. The default value is null. Setting this value to "nofollow" is recommended for rendering HTML in areas where users may add links, for example in a blog comment. See http://en.wikipedia.org/wiki/Nofollow for more information.

Parameters:
linkRel - the rel or null if there is none.
See Also:
LinkAttributes.getRel()

beginDocument

public void beginDocument()
Description copied from class: DocumentBuilder
Begin a document. Calling this method is optional for some builders, however if called then it must be matched by a corresponding call to DocumentBuilder.endDocument().

Specified by:
beginDocument in class DocumentBuilder
See Also:
DocumentBuilder.endDocument()

emitHeadContents

protected void emitHeadContents()
emit the contents of the HTML head, excluding the head tag itself. Subclasses may override to change the contents of the head. Subclasses should consider calling super.emitHeadContents() in order to preserve features such as emitting the base, title and stylesheets.


endDocument

public void endDocument()
Description copied from class: DocumentBuilder
End a document.

Specified by:
endDocument in class DocumentBuilder
See Also:
DocumentBuilder.endDocument()

beginBody

protected void beginBody()
begin the body by emitting the body element. Overriding methods should call super.beginBody().

See Also:
endBody()

endBody

protected void endBody()
end the body by emitting the body end element tag. Overriding methods should call super.endBody().

See Also:
beginBody()

entityReference

public void entityReference(String entity)
Description copied from class: DocumentBuilder
An XML entity reference.

Specified by:
entityReference in class DocumentBuilder
Parameters:
entity - the entity

acronym

public void acronym(String text,
                    String definition)
Description copied from class: DocumentBuilder
Emit an acronym

Specified by:
acronym in class DocumentBuilder
Parameters:
text - the acronym to emit
definition - the definition of the acronym, which is typically displayed on mouse hover

link

public void link(Attributes attributes,
                 String hrefOrHashName,
                 String text)
Description copied from class: DocumentBuilder
Create a hyperlink to the given url. If LinkAttributes are used, the attributes must not have the href attribute set.

Specified by:
link in class DocumentBuilder
Parameters:
attributes - the attributes of the link
hrefOrHashName - the url (which may be internal to the page if prefixed with a hash '#')
text - the text of the hyperlink

beginLink

public void beginLink(Attributes attributes,
                      String hrefOrHashName)
Overrides:
beginLink in class DocumentBuilder

endLink

public void endLink()
Overrides:
endLink in class DocumentBuilder

beginBlock

public void beginBlock(DocumentBuilder.BlockType type,
                       Attributes attributes)
Description copied from class: DocumentBuilder
Begin a block of the specified type. Builder implementations may do a best-effort application of the provided attributes. Note that the provided attributes *may* be a subclass of the Attributes class, in which case the builder may attempt to apply the attributes specified. Builders may choose to ignore attributes, and should fail silently if the given attributes are not as expected. Each call to this method must be matched by a corresponding call to DocumentBuilder.endBlock().

Specified by:
beginBlock in class DocumentBuilder
attributes - the attributes to apply to the block. Callers may choose to specify a more specialized set of attributes by providing a subclass instance.
See Also:
DocumentBuilder.endBlock()

beginHeading

public void beginHeading(int level,
                         Attributes attributes)
Description copied from class: DocumentBuilder
Begin a heading of the specified level (usually 1-6). Builder implementations may do a best-effort application of the provided attributes. Each call to this method must be matched by a corresponding call to DocumentBuilder.endHeading().

Specified by:
beginHeading in class DocumentBuilder
Parameters:
level - the level of the heading, usually 1-6
attributes - the attributes to apply to the heading
See Also:
DocumentBuilder.endHeading()

beginSpan

public void beginSpan(DocumentBuilder.SpanType type,
                      Attributes attributes)
Description copied from class: DocumentBuilder
Begin a span of the specified type. Builder implementations may do a best-effort application of the provided attributes. Each call to this method must be matched by a corresponding call to DocumentBuilder.endSpan().

Specified by:
beginSpan in class DocumentBuilder
attributes - the attributes to apply to the span
See Also:
DocumentBuilder.endSpan()

endBlock

public void endBlock()
Description copied from class: DocumentBuilder
End a block that was started.

Specified by:
endBlock in class DocumentBuilder

endHeading

public void endHeading()
Description copied from class: DocumentBuilder
End a span that was started.

Specified by:
endHeading in class DocumentBuilder
See Also:
DocumentBuilder.beginHeading(int, Attributes)

endSpan

public void endSpan()
Description copied from class: DocumentBuilder
End a span that was started.

Specified by:
endSpan in class DocumentBuilder
See Also:
#beginSpan(org.eclipse.mylyn.wikitext.parser.DocumentBuilder.SpanType, Attributes)

image

public void image(Attributes attributes,
                  String url)
Description copied from class: DocumentBuilder
Build the image with the given attributes

Specified by:
image in class DocumentBuilder
Parameters:
attributes - the attributes, which may be an ImageAttributes.
url - the URL to the image, possibly relative

imageLink

public void imageLink(Attributes linkAttributes,
                      Attributes imageAttributes,
                      String href,
                      String imageUrl)
Description copied from class: DocumentBuilder
Create a hyperlink whose visual representation is an image. Implementations must apply the attributes to the image tag. For example, if the builder constructs HTML, the builder would emit <a href="..."><img src="..."/></a>. In this case if the attributes define a css class then the resulting HTML should look like this: <a href="..."><img src="..." class="..."/></a>

Specified by:
imageLink in class DocumentBuilder
Parameters:
linkAttributes - the attributes of the link, which may be LinkAttributes
imageAttributes - the attributes of the image , which may be ImageAttributes
href - the url (which may be internal to the page if prefixed with a hash '#')
imageUrl - the url of the image, which may be relative

emitAnchorHref

protected void emitAnchorHref(String href)
emit the href attribute of an anchor. Subclasses may override to alter the default href or to add other attributes such as onclick. Overriding classes should pass the href to AbstractXmlDocumentBuilder.makeUrlAbsolute(String) prior to writing it to the writer.

Parameters:
href - the url for the href attribute

lineBreak

public void lineBreak()
Description copied from class: DocumentBuilder
Create a line break (eg: br in html). Not all builders need support line breaks.

Specified by:
lineBreak in class DocumentBuilder

charactersUnescaped

public void charactersUnescaped(String literal)
Description copied from class: DocumentBuilder
Create unescaped characters, usually with some embedded HTML markup. Note that using this method causes the output to be HTML-centric

Specified by:
charactersUnescaped in class DocumentBuilder
Parameters:
literal - the literal characters to emit

getReader

protected Reader getReader(File inputFile)
                    throws FileNotFoundException
Throws:
FileNotFoundException

setPrependImagePrefix

public void setPrependImagePrefix(String prependImagePrefix)
if specified, the prefix is prepended to relative image urls.


getPrependImagePrefix

public String getPrependImagePrefix()
if specified, the prefix is prepended to relative image urls.



Copyright © 2011 FuseSource, Corp.. All Rights Reserved.