=head1 MakeClicky extension

=head2 Description

I<MakeClicky> detects various formats of data in headers and email
messages, and extends them with supporting links.

=head2 Configuration

You can configure clicky actions from RT config with @Active_MakeClicky
option. It's ordered of the actions you want to apply.

By default, RT provides two actions:

=over 4

=item httpurl

Detects http:// and https:// URLs and adds '[Open URL]' link after the URL.

=item httpurl_overwrite

Also detects URLs as 'httpurl' format, but replace URL with link
and *adds spaces* into text if it's longer then 30 chars. This allow
browser to wrap long URLs and avoid horizontal scrolling.

=back

RTIR is shipped with several actions you can use: 'ip', 'ipdecimal',
'email', 'domain' and 'RIPE'.

=head2 Order of clicky actions

Order of actions is important in situations when you use actions that
could match the same block of a text, in this case only the first matching
action from the list would be applied. For example ot makes no sense to
use C<httpurl> and C<httpurl_overwrite> at the same time as both actions
always match the same piece of a text.

=head2 How it works

Each action consists of regular expression and function that do text replace.
When you open history of a ticket RT search in the text with the regular expresion
for matches. If some piece of the text matches it calls the function with the match
as argument, then replace matched text with string returned by the function. So
in two words this feature works like 'Search and Replace' with an active replacer.

Text of tickets is plain, but actions could generate arbitrary HTML.

=head2 Writing custom MakeClicky actions

To extend the list of actions with your own types of data, use the callback. Create
file F<local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>.

It will be provided with arguments:

=over 4

=item types

An array reference of hash references.  Modify this array
reference to add your own types; the first matching type will be
used. Each hashref should contain:

=over 4

=item name

The name of the data format; this is used in the
configuration file to enable the format.

=item regex

A regular expression to match against.

=item action

The name of the action to run (see "actions", below)

=back

=item actions

A hash reference of 'actions'.  Modify this hash reference to change or add
action types.  Values are subroutine references which will get called when needed.
They should return the modified string. Note that subroutine B<must escape> HTML.

=item handler

A subroutine reference; modify it only if you have to. This can be used
to add pre- or post-processing around all actions.

=back

=head2 Actions' arguments

A hash is passed to action with two keys that always exist:

=over 4

=item value - full match of the regular expression, this block of text will be
replaced with action's result.

=item all_matches - array with all matches including groups defined in the
regular expression, for example if your regexp is C<qr{ticket\s+#(\d+)}> then
the first element will be full match ("ticket #XXX") the same as in 'value' key,
but the second one element of the array will be id of a ticket (XXX), so you
can avoid parsing value in the action. Only eight groups of your regexps are
passed to actions.

=back

=head2 Custom MakeClicky action example

Create a new file F</opt/rt3/local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>
with the content:

  <%ARGS>
  $types   => []
  $actions => {}
  </%ARGS>
  <%INIT>
  my $web_path = RT->Config->Get('WebPath');
  
  # action that takes ticket ID as argument and returns link to the ticket
  $actions->{'link_ticket'} = sub {
      my %args = @_;
      my $id = $args{'all_matches'}[1];
      return qq{<a href="$web_path/Ticket/Display.html?id=$id">$args{value}</a>};
  };
  
  # add action to the list
  push @$types, {
      # name, that should be used in config to activate action
      name   => 'short_ticket_link',
      # regular expression that matches text 'ticket #xxx'
      regex  => qr{ticket\s+#(\d+)}i,
      # name of the action that should be applied
      action => 'link_ticket',
  };
  </%INIT>

That's all. Add C<short_ticket_link> to C<@Active_MakeClicky> option in your C<RT_SiteConfig.pm>.
Restart your server and create test ticket with 'ticket #1' text.

=head2 Notes for custom clicky actions writers

Note that an action B<must escape> illegal HTML characters with entities and/or
arguments in URLs.

Complex (slow) regular expressions could slow down RT as conversion is run each
time user open a ticket.

Try to match the shortest expression you need with your regular expression otherwise another action could miss its chance to match.

Precalculate values, use closures for functions.