Wiki Link Syntax

Highlights#

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:

  1. [Text]
  2. [Text | Link]
  3. [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. 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):

'id'
This attribute assigns a name to an element. This name must be unique in a document.
'class'
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.
'style'
This attribute specifies style information for the current element.
'title'
This attribute offers advisory information about the element for which it is set.
'lang'
This attribute specifies the base language of an element's attribute values and text content. The default value of this attribute is unknown.
'dir'
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.
'charset'
This attribute specifies the character encoding of the resource designated by the link. Please consult the section on character encodings for more details.
'type'
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.
'hreflang'
This attribute specifies the base language of the resource designated by href and may only be used when href is specified.
'rel'
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.
'rev'
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.
'accesskey'
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.
'tabindex'
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.
'target'
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 highlight 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.

_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.

Example of target#

[X86_virtualization|http://en.wikipedia.org/wiki/X86_virtualization| target='_blank'] works like X86_virtualization

Returned Value#

This returns a Link object, a public inner class with methods:

The attributeCount() method can be used to circumvent calling getAttributes(), which will create an empty Iterator rather than return a null.!! Examples

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.11.3.! Example: Link Form 1

From an incoming wikitext link of: 

  [WikiEtiquette]
WikiEtiquette

returns: 

  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

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/ | target='_blank'
   title='Purveyors of fine freeware since 1972. On the net since 1991.']
Acme

returns: 

  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."
Please see our Copyright And Intellectual Property Page and Standard Disclaimer Pages!