HOWTO: Custom Links

Last modified 1/10/2007.

This document describes how custom links work. This is an advanced feature that allows you to create new formatting commands, that work just like the built-in "file:", "include:", "toc:", etc. These can be used for a variety of purposes, from adding special formatting, to integrating content from other sites and services, whether your own internal information systems, or public "Web 2.0" services.

Custom links can only be defined by the site administrator. This is done using the "Custom Links" page in the Site Administration area; any custom links that are created are available for use across all forums on the entire site.

Defining a custom links consists of two parts: defining what unique pattern in a forum page will match (trigger) the link, and then defining how the link should be displayed.

Matching a Custom Link

Custom links must define a prefix, an optional selector, and a number of parameters that will trigger the custom link handler when a matching link is found in the page.

Link prefix. Custom links always appear in square brackets, and begin with a link prefix consisting of one or more lowercase characters, followed by a colon (":"). The prefix cannot be the same as a link prefix already built-into ProjectForum, such as "file:", "rss:", "include:", etc. For example:

• [stock:APPL] — prefix is "stock"
• [address:"Joe Smith" personal] — prefix is "address"
• [companylogo:] — prefix is "companylogo"

Parameters. When you define a custom link, you specify how many parameters should be passed to the link when used. Each parameter is a single word, or can be several words put in quotes. In the examples above, the first has a single parameter ("APPL"), the second has two ("Joe Smith" and "personal"), and the third has none. As will be shown below, these parameters can be used when displaying the link.

Selectors. A custom link may specify that the first parameter is a specific word, known as a selector. This is a handy way of grouping together related formatting. For example:

• [quote:start] — prefix is "quote", selector is "start", no parameters
• [quote:end] — prefix is "quote", selector is "end", no parameters

Disambiguating custom links. You can define many different custom links. For those having the same prefix, they must have either a different number of parameters or different selectors. If more than one custom link definition matches a link in the page, the following two rules apply. Matches that specify a selector (and match the appropriate number of parameters of course) take precedence over those that do not specify a selector. Matches that specify an exact number of parameters take precedence over those specifying "any" number of parameters.

Displaying the link

Having defined what links in the page will match to the custom link, the second part is specifying how these links will be displayed. This can be done either with inline HTML, or via a web CGI.

Inline HTML. With the inline HTML type, the administrator provides a block of HTML code as the "body" of the link. The place where the link appears in the page is replaced by the HTML provided. For example, the earlier [quote:start] and [quote:end] examples could be displayed as "<blockquote>" and "</blockquote>" respectively.

Web CGI. With web CGI custom links, rather than the body of the link being the HTML to display, it is instead a URL that will be called to retrieve the HTML to display. This is one way to allow your code to interact and retrieve data from a remote service. This works similarly to the [include:] built-in command.

Parameter substitutions. Your custom link, whether it is an inline HTML link or a web CGI link, can also make use of any parameters that were provided with the link on the page. If the body of the link contains "$1", the "$1" will be replaced with the parameter. Similarly, "$2" for the second parameter, up to "$9" for the ninth. The special "$0" means substitute all parameters of the link.

The "[stock:]" example from earlier might be a Web CGI link that calls a stock service which returns an HTML snippet showing the value of a stock. We'd want to pass the first parameter (e.g. "APPL" in the example), which could be done with a URL like this:

http://www.foo.com/getstock.cgi?ticker=$1

http://www.foo.com/getstock.cgi?ticker=APPL

Examples