Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

Note that I've made some changes so pmdev members can see the prior version, Everything/ (and, for example, download it to compare it to the current version, Everything/ and I'll follow this convention for future patches to the PM modules.

For pmdev members hoping to patch in new link short-cuts, here is some documentation on how the new, simpler, more robust link handlers are written:

The following variables are set for you to use in the link handler:

[$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 title ( $url, $deftitle ) # Alternate default title ( '', $html ) # No separate URL; avoid this if possible ( ) # $linkspec was invalid, $q->escapeHTML("[$fullspec]") used

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 "Jul 11, 2014 at 17: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].

In the next day or two I'll fix the settings display page and patching pages to stop stripping newlines and switch back to using "handlelinks settings" (instead of the current "new handlelinks settings" that made the migration easier) and then patches can be applied again. Sorry for the delay.

- tye        

In reply to Re: Batch of improvements applied (pmdev) by tye
in thread Batch of improvements applied by tye

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others wandering the Monastery: (21)
    As of 2014-07-11 17:36 GMT
    Find Nodes?
      Voting Booth?

      When choosing user names for websites, I prefer to use:

      Results (232 votes), past polls