AugmentedWikiLinks is a new feature for the JSPWikiMarkupParser extending the original JSPWiki linking syntax to permit specification of the declared attributes available on the HTML anchor ("<a>") element. A few attributes that are security risks are disabled (ignored), otherwise the full set can be used.
Incorporation of the LinkParser providing these features is with JSPWiki CVS version 2.5.13, so no installation is necessary; this functionality is part of JSPWiki subsequent to 2.5.13.
The syntax is similar to the MediaWiki link syntax.
- Yes, you can now use the 'target' attribute on links to open up the link in a new tab or window.
- Adding an 'id' value permits you to link back to the point of the link to create a bidirectional link.
- With 'style' you can add CSS styling to the link or with 'class' use one of the existing classes in the JSPWiki CSS stylesheet.
- You can add an advisory title to links using the 'title' attribute. On some browsers this is displayed as a tooltip on mouseover.
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 | 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.
Declared Attributes on <a> Links#
The attribute list declaration for <a> from HTML 4 is as follows:
<!ELEMENT A - - (%inline;)* -(A) -- anchor --> <!ATTLIST A %attrs; -- %coreattrs, %i18n, %events -- charset %Charset; #IMPLIED -- char encoding of linked resource -- type %ContentType; #IMPLIED -- advisory content type -- name CDATA #IMPLIED -- named link end -- href %URI; #IMPLIED -- URI for linked resource -- hreflang %LanguageCode; #IMPLIED -- language code -- rel %LinkTypes; #IMPLIED -- forward link types -- rev %LinkTypes; #IMPLIED -- reverse link types -- accesskey %Character; #IMPLIED -- accessibility key character -- shape %Shape; rect -- for use with client-side image maps -- coords %Coords; #IMPLIED -- for use with client-side image maps -- tabindex NUMBER #IMPLIED -- position in tabbing order -- onfocus %Script; #IMPLIED -- the element got the focus -- onblur %Script; #IMPLIED -- the element lost the focus -- >
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: 'id', 'class', 'style', 'title' (from %coreattrs;); 'lang', 'dir' (from %i18n;); as well as 'accesskey', 'charset', 'hreflang', 'rel', 'rev', 'tabindex', 'target' , and 'type'. The declared attributes that will be ignored are: 'href', 'name', 'shape', 'coords', 'onfocus', 'onblur', or any of the other 'on*' event attributes. 'name' is not permitted in preference to 'id' (which should nowadays be used as its replacement).
This means that the list of permitted attributes includes (with their HTML 4 definitions):
- This attribute assigns a name to an element. This name must be unique in a document.
- This attribute assigns a class name or set of class names to an element. Any number of elements may be assigned the same class name or names. Multiple class names must be separated by white space characters.
- This attribute specifies style information for the current element.
- This attribute offers advisory information about the element for which it is set.
- This attribute specifies the base language of an element's attribute values and text content. The default value of this attribute is unknown.
- This attribute specifies the base direction of directionally neutral text (i.e., text that doesn't have inherent directionality as defined in UNICODE) in an element's content and attribute values. It also specifies the directionality of tables. Possible values: "ltr" for Left-to-right text or table; "rtl": Right-to-left text or table.
- This attribute specifies the character encoding of the resource designated by the link. Please consult the section on character encodings for more details.
- This attribute gives an advisory hint as to the content type of the content available at the link target address. It allows user agents to opt to use a fallback mechanism rather than fetch the content if they are advised that they will get content in a content type they do not support.
- This attribute specifies the base language of the resource designated by href and may only be used when href is specified.
- This attribute describes the relationship from the current document to the anchor specified by the href attribute. The value of this attribute is a space-separated list of link types.
- This attribute is used to describe a reverse link from the anchor specified by the href attribute to the current document. The value of this attribute is a space-separated list of link types.
- This attribute assigns an access key to an element. An access key is a single character from the document character set. Note. Authors should consider the input method of the expected reader when specifying an accesskey.
- This attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros.
- This attribute specifies the name of a frame where a document is to be opened. See the list of permitted values below.
Some of these could have real use on a wiki; others are more questionable. But being able to add IDs and titles is pretty helpful, with 'style' perhaps to hilight a link, and how to include target has been asked for a few times on the mailing list. Since permitted attributes are just passed along in the construction of normal HTML markup, whatever functionality they provide (i.e., whatever support a browser provides) is the same as any use of those attributes.
Note that the difference between 'lang' and 'hreflang' is that the former notes the language of the link text, the latter the language of the document at the end of the traversed link.
The permitted attributes and target attribute values are static String arrays (PERMITTED_ATTRIBUTES and PERMITTED_TARGET_VALUES resp.) that could be compile-time modified (i.e., predeclared). If you find an attribute is being abused by your users (e.g., 'style'), alter the list and recompile.
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.
- The user agent should load the designated document in a new, unnamed window.
- The user agent should load the document in the same frame as the element that refers to this target.
- 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.
- 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.
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.
NOTE: these examples won't work correctly until jspwiki.org site is using version 2.5.13 or later. The current version running on this site is 2.8.4-svn-9.
Example: Link Form 1#
From an incoming wikitext link of:
getText(): "WikiEtiquette" getReference(): "WikiEtiquette" attributeCount(): 0 getAttributes(): an empty Iterator
Example: Link Form 2#
From an incoming wikitext link of:
[Acme | http://www.acme.com/]Acme
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/ | target='_blank' title='Purveyors of fine freeware since 1972. On the net since 1991.']Acme
getText(): "Acme" getReference(): "http://www.acme.com/" attributeCount(): 2 getAttributes(): an Iterator containing: JDOM Attribute: target="_blank" JDOM Attribute: title="Purveyors of fine freeware since 1972. On the net since 1991."
This functionality is now incorporated into CVS HEAD, starting from version 2.5.13.