| Parses JSPWiki-style "augmented" link markup into a Link object
containing the link text, link reference, and any optional link
attributes (as JDOM Attributes).
The parser recognizes three link forms:
- [Text]
- [Text | Link]
- [Text | Link | attributes]
where the attributes are space-delimited, each in the form of
name1='value1' name2='value2' name3='value3' (etc.)
If the attribute parsing fails, the parser will still return the
basic link, writing a warning to the log.
Permitted Attributes
Attributes that aren't declared on <a> or those that
permit scripting in HTML (as this is a security risk) are ignored
and have no effect on parsing, nor show up in the resulting attribute
list). The 'href' and 'name' attributes are also ignored as spurious.
The permitted list is: 'accesskey', 'charset', 'class', 'hreflang',
'id', 'lang', 'dir', 'rel', 'rev', 'style' , 'tabindex', 'target' ,
'title', and 'type'. The declared attributes that will be ignored
are: 'href', 'name', 'shape', 'coords', 'onfocus', 'onblur', or any
of the other 'on*' event attributes.
The permitted attributes and target attribute values are static
String arrays (
LinkParser.PERMITTED_ATTRIBUTES and
LinkParser.PERMITTED_TARGET_VALUES resp.) that could be compile-time
modified (i.e., predeclared).
Permitted Values on Target Attribute
The following target names are reserved in HTML 4 and have special
meanings. These are the only values permitted by the parser.
- _blank
- The user agent should load the designated document in a new,
unnamed window.
- _self
- The user agent should load the document in the same frame as
the element that refers to this target.
- _parent
- The user agent should load the document into the immediate
FRAMESET parent of the current frame. This value is equivalent to
_self if the current frame has no parent.
- _top
- The user agent should load the document into the full,
original window (thus canceling all other frames). This value is
equivalent to _self if the current frame has no parent.
Returned Value
This returns a Link object, a public inner class with methods:
- getText() returns the link text.
- getReference() returns the link reference value.
- attributeCount() returns the number of declared attributes.
- getAttributes() returns an iterator over any validated
XHTML-compliant attributes, returned as JDOM Attributes.
The attributeCount() method can be used to circumvent calling
getAttributes(), which will create an empty Iterator rather
than return a null.
Example: Link Form 1
From an incoming wikitext link of:
[Acme]
returns:
getText(): "Acme"
getReference(): "Acme"
attributeCount(): 0
getAttributes(): an empty Iterator
Example: Link Form 2
From an incoming wikitext link of:
[Acme | http://www.acme.com/]
returns:
getText(): "Acme"
getReference(): "http://www.acme.com/"
attributeCount(): 0
getAttributes(): an empty Iterator
Example: Link Form 3
From an incoming wikitext link of:
[Acme | http://www.acme.com/ | id='foo' rel='Next']
returns:
getText(): "Acme"
getReference(): "http://www.acme.com/"
attributeCount(): 2
getAttributes(): an Iterator containing:
JDOM Attribute: id="foo"
JDOM Attribute: rel="Next"
author:
Murray Altheim
since:
2.5.10 | 