org.apache.maven.doxia.util
Class HtmlTools

java.lang.Object
  org.apache.maven.doxia.util.HtmlTools

public class HtmlTools
extends java.lang.Object

The HtmlTools class defines methods to HTML handling.

Since:

1.0

Version:

$Id: HtmlTools.java 747780 2009-02-25 13:55:23Z vsiveton $

Author:

Vincent Siveton

Method Summary

static java.lang.String	encodeId(java.lang.String id) Construct a valid id.
static java.lang.String	encodeURL(java.lang.String url) Encode an url
static java.lang.String	escapeHTML(java.lang.String text) Escape special HTML characters in a String in xml mode.
static java.lang.String	escapeHTML(java.lang.String text, boolean xmlMode) Escape special HTML characters in a String.
static javax.swing.text.html.HTML.Tag	getHtmlTag(java.lang.String tagName) Returns a tag for a defined HTML tag name (i.e. one of the tags defined in HtmlMarkup.
static boolean	isId(java.lang.String text) Determines if the specified text is a valid id according to the rules laid out in encodeId(String).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getHtmlTag

public static javax.swing.text.html.HTML.Tag getHtmlTag(java.lang.String tagName)

Returns a tag for a defined HTML tag name (i.e. one of the tags defined in HtmlMarkup. If the given name does not represent one of the defined tags, then null will be returned.

Parameters:

tagName - the String name requested.

Returns:

a tag constant corresponding to the tagName, or null if not found.

Since:

1.1

See Also:

http://www.w3.org/TR/html401/index/elements.html

escapeHTML

public static java.lang.String escapeHTML(java.lang.String text)

Escape special HTML characters in a String in xml mode.

Parameters:

text - the String to escape, may be null.

Returns:

The escaped text or the empty string if text == null.

See Also:

escapeHTML(String,boolean)

escapeHTML

public static final java.lang.String escapeHTML(java.lang.String text,
                                                boolean xmlMode)

Escape special HTML characters in a String.

 < becomes <
 > becomes >
 & becomes &
 " becomes "
 

If xmlMode is true, every other character than the above remains unchanged, if xmlMode is false, non-ascii characters get replaced by their hex code.

Parameters:

text - The String to escape, may be null.

xmlMode - set to false to replace non-ascii characters.

Returns:

The escaped text or the empty string if text == null.

Since:

1.1

encodeURL

public static java.lang.String encodeURL(java.lang.String url)

Encode an url

Parameters:

url - the String to encode, may be null

Returns:

the text encoded, null if null String input

encodeId

public static java.lang.String encodeId(java.lang.String id)

Construct a valid id.

According to the HTML 4.01 specification section 6.2 SGML basic types:

ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

According to XHTML 1.0 section C.8. Fragment Identifiers:

When defining fragment identifiers to be backward-compatible, only strings matching the pattern [A-Za-z][A-Za-z0-9:_.-]* should be used.

To achieve this we need to convert the id String. Two conversions are necessary and one is done to get prettier ids:

1. If the first character is not a letter, prepend the id with the letter 'a'
2. A space is replaced with an underscore '_'
3. Remove whitespace at the start and end before starting to process

For letters, the case is preserved in the conversion.

Here are some examples:

 HtmlTools.encodeId( null )        = null
 HtmlTools.encodeId( "" )          = ""
 HtmlTools.encodeId( " _ " )       = "a_"
 HtmlTools.encodeId( "1" )         = "a1"
 HtmlTools.encodeId( "1anchor" )   = "a1anchor"
 HtmlTools.encodeId( "_anchor" )   = "a_anchor"
 HtmlTools.encodeId( "a b-c123 " ) = "a_b-c123"
 HtmlTools.encodeId( "   anchor" ) = "anchor"
 HtmlTools.encodeId( "myAnchor" )  = "myAnchor"
 

Note: this method is intentionally similar to DoxiaUtils.encodeId(String).

Parameters:

id - The id to be encoded.

Returns:

The trimmed and encoded id, or null if id is null.

isId

public static boolean isId(java.lang.String text)

Determines if the specified text is a valid id according to the rules laid out in encodeId(String).

Parameters:

text - The text to be tested.

Returns:

true if the text is a valid id, otherwise false.

See Also:

encodeId(String).