Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris

handlelinks settings sitedoclet

by SiteDocClan
on Feb 26, 2006 at 11:40 UTC ( #532864=sitedoclet: print w/replies, xml ) Need Help??

The following variables are available for use in handlelinks settings:

[$fullspec] [ $prefix :// $suffix | $title ] $linkspec= "$prefix://$suffix" $escsuffix= $q->escape($suffix) # URL-encoded

That is, $fullspec is exactly what the user typed between the brackets, including whitespace. $prefix, $suffix, and $title have leading and trailing whitespace stripped and $prefix is forced to lowercase.

If your handler is just a bareword, then you are defining an alias (the ftp and https handlers are both just "http"). Otherwise, your handler should return one of the following cases:

  • ( $url ) # The most common case. uses $suffix as default text, i.e. text to be used if the author omitted explicit link text.
  • ( $url, $deftitle ) # same, but specifies the default text.
  • ( '', $html ) # No URL means no link will be implicitly constructed. Use this when the "shortcut" is more like a general macro.
  • ( ) # $linkspec was invalid; [$fullspec] (appropriately html-escaped) will be displayed instead.

So a typical link handler is often as simple as:


If you want [lyrics://ironic] to render as <a ...>lyrics://ironic</a> instead of w/o the "lyrics://" part showing, then you'd use:

( "$escsuffix", $q->escapeHTML($linkspec) )

Note that the second value returned is just the default title and it is only used if $title is blank (which should mean that the user didn't include "|title" in their link -- but your link handler can also "mess with" $title if you have a good reason, which is unlikely).

I have a few $q->escapeHTML() calls missing (from the setting of the default title and from the 'http' short-cut), so I'll fix that soonish. But, the default title you return should be HTML so be sure to escapeHTML() it if needed (usually the case).

Also note that the presence or absence of each returned value is determined with a simple Perl boolean test so returning ( $url, "0" ) is the same as ( $url ), ( 0, $html ) means ( '', $html ), and ( undef, '0') means ( ), for example.

Returning ( '', $html ) is supported for strange cases like [localtime://] (which renders as "May 20, 2018 at 18:37 UTC", ATM) but should be avoided, if possible. Some link handlers (like pad://) currently use it just because it was a pain to fix them to use the new convention, but I hope they will get converted eventually. Note that such link short-cuts don't work in the "Search" box.

Returning no true values means that the link spec was invalid and what the user typed should simply be output unchanged, for example, [id://notanumber].

If you change any of these settings, be sure to update What shortcuts can I use for linking to other information?! Also consider that publicizing your change via Tidings may be appropriate as well.

Log In?

What's my password?
Create A New User
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (5)
As of 2018-05-20 18:34 GMT
Find Nodes?
    Voting Booth?