As of Nov. 2005 / JSPWiki 2.3.45 Janne had to break template compatibility. The idea here is to write a specification for a new link tag, the old could be supported for a while but over time deprecated. As the author of the configurable template, I have wrangled for a while already with the "grown" design of the various link methods in JSPWiki.

Starting with a discussion in InterWiki Janne writes: "Good point, and one I had completely forgotten about. This might make sense to do, yes. Could you draft quickly here (or on the mailing list) how you would make such a LinkTag to work (i.e. write a spec, please ;-)" -- JanneJalkanen

I cannot write a technically formal spec., but I try to be precise.


1. I propose to create a new tag "LinkTag" ( Simplest template syntax: <wiki:Link page='x' />. This is going to replace DiffLinkTag, EditLinkTag, LinkToParentTag, LinkToTag, PageInfoLinkTag, RSSLinkTag, UploadLinkTag (plus abstract base: The older tags may remain (unless the template compatibility break in 2.3.45 is a good point to remove them immediately).

2. This tag and the wiki link syntax (Formatting rules) should closely correspond to each other, have same power and ultimately use the same code for rendering.

  • This would enable existing wiki-based design (e.g. LeftMenu) to become more powerful and user-friendly.
  • Current cludges like having to define Edit links through InterWiki syntax, or splitting the LeftMenu to place an Edit link in the middle would no longer be necessary.
  • It would allow to move additional parts of the templates into wiki pages, which would simplify the future design of wikis, and especially localisation to different languages hugely.
  • By having greater parts of wikis accessible to wiki editors, the server administrators have less to do and the content editors become empowered to adjust the wiki to their needs. This is especially important for wiki farms with MultipleWikis.
  • See Idea Move Much More Template Business Into Wiki Pages for an example

Documentation of current parameters of template link tags.#

  • EditLinkTag and LinkToTag have identical parameters:
    • page: Page name to link to. If not set, uses the current page.
    • format: If "anchor", creates the full hyperlink (<a href="...">link text</a>); if "url", outputs only the URL.
    • version: Links to a specific version of a page. If not set, links to the latest version of the page.
  • LinkToParentTag, PageInfoLinkTag, and UploadLinkTag have identical parameters:
  • RSSLinkTag
    • has no parameters. Creates: <link rel="alternate" type="application/rss+xml" title="RSS feed" href="...rss.rdf" />
  • DiffLinkTag
    • page, and format like LinkToTag
    • version: The older version of the page. Can be "latest" to refer to the latest version; or "previous" to link to the previous version.
    • newVersion: The newer version of the page. Can be "latest" to refer to the latest version; or "previous" to link to the previous version.
      • Attention: from my own testing I believe that at least with contextual diff provider, the semantics of version and newversion are reverted, i.e. the newer version has to be in version, and newVersion must contain the older version.

Features of new linking syntax#

Links (both in template and wiki text have the following features:

  • A display text
    • The display text should be formattable in bold, italic and style (double-percent) syntax
    • display text may contain images in plugin or image inlining syntax
  • A link target (url, wiki page or interwiki link).
    • Target and display text may be combined. However, prior to processing as described below, they are then to be duplicated.
  • A relation attribute - which kind of relation is described?
  • A class attribute (CSS styles)
  • A title attribute (for text displayed as popup, similar to tooltips).
  • Although links may not normally be nested, the display text of a link may contain an image link.

Syntax of new LinkTag#

<wiki:Link \\
 >display text</wiki:Link>

All elements are optional:

  • If ref is missing, the current wiki page name is used.
  • If format is missing, anchor is assumed.
  • If version is missing, the latest version is assumed
  • If compareToVersion is missing a normal link is created, else a link to the difference provider (i.e. equivalent of DiffLinkTag).
  • If class is missing wikilink is assumed.
  • If rel or title are missing the respective features are missing.
  • If display text is missing, page is used (and from above follows: if page is missing, current page name is displayed).

From the above, the LinkToTag and DiffLinkTag are already covered. Rather than introducing an additional parameter for an "action", I propose to recognize specific link classes. Thus setting class='edit', 'pageinfo', and 'upload' informs the engine to create special urls.

Probably same for 'rss' - I am uncertain have not studied or used this yet...

Similarly, I feel that LinkToParentTag should rather be emulated by modifying the value of the link ref attribute. I have not analysed this properly, I never this tag so far.

A ready extension of the above would be to allow height and width attributes for inline image links.

Corresponding Wiki markup syntax#

[Displaytext | PageName]
[Displaytext | PageName | class='editlink' title='click here to edit this page']
[Displaytext | PageName | format='url']
[Displaytext | PageName | version='' class='myownversionlinkstyle']
[Displaytext | PageName | rel='']
[Displaytext | PageName | rel='' title=]

This syntax allows close correspondence to the template tag syntax. It is extensible, by adding further attributes in the future. One corresponding case should probably be excluded, there need no be an equivalent to <wiki:Link />, i.e. no [].

Note: the rel attribute is a provision for the future. JSPWiki is so damned close to become an excellent platform for an ontology wiki, that I believe this is a necessity when changing the syntax!


  • Since attribute values are sourrounded by apostrophes, these need to be escaped using html character entity & + apos;
  • It may not advisable to collapse link target and display while adding rel or class attributes. This may be a serious limitation when moving into ontology realms.
    • The limitation above is not a strict necessity. It would be possible to make the engine smart enough to distinguish [Displaytext | PageName] from [PageName | class='stylename']. In the first case, the second link part may contain only wiki name syntax (not much punctuation), in the second case it must contain a "=".
  • CamelCase linking is only possible without any advanced features, but I see no problems with this.
  • In wiki syntax, it is not easy to leave the page name away, to alway refer to the current page. This is, however, desirable for edit and version links. I therefore propose that the syntax also supports:
[Displaytext | | version='4']
[Displaytext | | class='editlink' title='click here to edit this page']

So far, so far unfinished...

-- Gregor Hagedorn, 25. Nov. 2005


I'd like to see support for the equivalent of the html 'target' attribute - to allow the link to be opened in a different browser window or frame.

--Rich Freedman, 25 Nov. 2005

How about this?

<wiki:Link \\
 >display text</wiki:Link>

where "type" = view|edit|diff, etc - just like with the CheckRequestContextTag. This would cover then all types of links. "style" = CSS style; "target" = different window.

I would still keep the old tags around for a while, though.

The wikimarkup link syntax will have to wait for a moment (personal bandwidth issues), but this one looks quite okay. Clean patches against the current CVS version appreciated ;-)

-- JanneJalkanen

I definitely forgot target, and perhaps indeed better to have a separate attribute for request context. However, naming this attribute "type" seems to be likely to cause confusion with other usage of type. See, e.g., "type" parameter in IncludeResourcesTag. Perhaps rather call it "request":

<wiki:Link \\
 >display text</wiki:Link>

I am begging those able to do to address this issue in the code. Please, however, do write an engine function that also works (even if slightly later) with wikimarkup. I believe the wikimarkup being much more important, because wiki authors do want to create powerful pages. Currently there are so many things you can not do in a wiki page (you can not cite a version, point users to a diff between specific versions, can not make real edit links, can not add any information to a link about semantics (and perhaps associated formatting), etc.

This simplicity is by design, too. Wikis in general are supposed to be simple, and very few people really need that kind of capability. A lone geek in the company could make even WikiMarkup completely unreadable, if there are too many features ;-). But anyway, this is a matter of priorization. If anyone is willing to contribute code, that would be great - if not, it'll go to my "queue of things that are cool, but are not requested by all people, are necessary, nor sufficiently cool." I know, it's a lousy answer, but... I can't do everything :-( --JanneJalkanen

Outline of necessary processing:#

Note: The processing proposed below differs from current processing, which is riddled with problems (not correctly cascading punctuation and capitalization normalization, interwiki and inline image resolver, not handling interwiki in the display text, etc.)

Even if link target (ref or page name) and display text are collapsed into one string, prior to further processing they should be duplicated.

  • The link target should (in this sequence):
    • pass the captitalization normalizer (turning "(my) link!" to "(My) Link!")
    • pass the blank and punctuation crusher (turning "(My) Link!" to "MyLink"
      • excluding period, underscore, leading and trailing hyphens and ":" from crushing.
    • Test for Image inline pattern, remember result. It should be possible to use the simple image inlining with interwiki links, see several recent bug reports.
    • Test for Interwiki definitions, expand them if possible
    • Crush the remaining ":" to finish punctuation normalization - i.e. those ":" not related to InterWiki links.
  • The display target should
    • only if copied from a collapsed link-target = display text: Be tested whether the start is a valid interwiki code defined for the currently running instance (e.g. "Wikipedia:") and if so, the interwiki prefix be removed. This is a big problem with current JSPWiki that whenever referring to external glossaries, dictionaries or encyclopedias, one has to use [interwiki:term|term] rather than simpler and more readable [interwiki:term].
      • This is by design. I personally like to see where a link is going - and with the upcoming WikiFarm system, you're likely to start seeing these a lot more often. -- Janne
      • Perhaps this may be a design decision prior to the introduction of outward-link marker (the red arrow after external links)? With normal external links you do not see where you are going other than in the browser status line, but you do see that it is an external link. Why would external links that are made simpler by interwiki syntax be treated differently? At the moment JSPWiki is unable to create a readable glossary, either the editing view becomes unreadable because of all the [term|wiktionary:term] syntax, or the presentation view because half the words have a "wiktionary:" in front of it. -- Gregor
    • in all cases: simply run display text through translate/renderer, thus appropriately handling links containing formatting or inline images. like:
[__Display__''text''| PageName]
[H%%sub 2%%~ O| PageName]
[ [img/image.png] | PageName]

-- Gregor Hagedorn

The initial try is now in 2.3.49. Note also the new "jsp" -attribute, which can be used to link to a top-level JSP file (so you don't have to play around anymore with <wiki:BaseURL>).

I decided to keep the "page" as an alternative method. It always refers to a wiki page. The "ref" -attribute is interpreted as if it was a WikiMarkup between brackets, i.e. interwiki, page, external, attachment are all recognized (except for local links, but that's only because I was lazy. Will be fixed in the future.)

I'll take the wikimarkup change under consideration. I'll need to check the MediaWiki progression on it; I know they're planning an upgrade as well. I'd like to keep similarity...

-- JanneJalkanen

Many thanks Janne, for tackling this!

... and as it goes, it seems we forgot something in the specs. Dirk is implementing accesskeys (see BrushedTemplateKeyboardShortcuts) which seems a good idea. From "The following elements support the accesskey attribute: A, AREA, BUTTON, INPUT, LABEL, and LEGEND, and TEXTAREA." Revised attribute summary:

<wiki:Link \\
 >display text</wiki:Link>

-- Gregor Hagedorn

OK. Not a biggie... (BTW: I'm using "context" instead of "request", so that it is more in line with the general lingo...)

-- JanneJalkanen

The accesskey is now in 2.3.52. Note that the 2.3.50 version of LinkTag is broken...

-- JanneJalkanen


--AnonymousCoward, 13-Feb-2006

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-25) was last changed on 13-Feb-2006 05:16 by AnonymousCoward