rt/docs/extending_clickable_links.pod

   1 =head1 MakeClicky extension
   2
   3 =head2 Description
   4
   5 I<MakeClicky> detects various formats of data in headers and email
   6 messages, and extends them with supporting links.
   7
   8 =head2 Configuration
   9
  10 You can configure clicky actions from RT config with @Active_MakeClicky
  11 option. It's ordered of the actions you want to apply.
  12
  13 By default, RT provides two actions:
  14
  15 =over 4
  16
  17 =item httpurl
  18
  19 Detects http:// and https:// URLs and adds '[Open URL]' link after the URL.
  20
  21 =item httpurl_overwrite
  22
  23 Also detects URLs as 'httpurl' format, but replace URL with link
  24 and *adds spaces* into text if it's longer then 30 chars. This allow
  25 browser to wrap long URLs and avoid horizontal scrolling.
  26
  27 =back
  28
  29 RTIR is shipped with several actions you can use: 'ip', 'ipdecimal',
  30 'email', 'domain' and 'RIPE'.
  31
  32 =head2 Order of clicky actions
  33
  34 Order of actions is important in situations when you use actions that
  35 could match the same block of a text, in this case only the first matching
  36 action from the list would be applied. For example ot makes no sense to
  37 use C<httpurl> and C<httpurl_overwrite> at the same time as both actions
  38 always match the same piece of a text.
  39
  40 =head2 How it works
  41
  42 Each action consists of regular expression and function that do text replace.
  43 When you open history of a ticket RT search in the text with the regular expresion
  44 for matches. If some piece of the text matches it calls the function with the match
  45 as argument, then replace matched text with string returned by the function. So
  46 in two words this feature works like 'Search and Replace' with an active replacer.
  47
  48 Text of tickets is plain, but actions could generate arbitrary HTML.
  49
  50 =head2 Writing custom MakeClicky actions
  51
  52 To extend the list of actions with your own types of data, use the callback. Create
  53 file F<local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>.
  54
  55 It will be provided with arguments:
  56
  57 =over 4
  58
  59 =item types
  60
  61 An array reference of hash references.  Modify this array
  62 reference to add your own types; the first matching type will be
  63 used. Each hashref should contain:
  64
  65 =over 4
  66
  67 =item name
  68
  69 The name of the data format; this is used in the
  70 configuration file to enable the format.
  71
  72 =item regex
  73
  74 A regular expression to match against.
  75
  76 =item action
  77
  78 The name of the action to run (see "actions", below)
  79
  80 =back
  81
  82 =item actions
  83
  84 A hash reference of 'actions'.  Modify this hash reference to change or add
  85 action types.  Values are subroutine references which will get called when needed.
  86 They should return the modified string. Note that subroutine B<must escape> HTML.
  87
  88 =item handler
  89
  90 A subroutine reference; modify it only if you have to. This can be used
  91 to add pre- or post-processing around all actions.
  92
  93 =back
  94
  95 =head2 Actions' arguments
  96
  97 A hash is passed to action with two keys that always exist:
  98
  99 =over 4
 100
 101 =item value - full match of the regular expression, this block of text will be
 102 replaced with action's result.
 103
 104 =item all_matches - array with all matches including groups defined in the
 105 regular expression, for example if your regexp is C<qr{ticket\s+#(\d+)}> then
 106 the first element will be full match ("ticket #XXX") the same as in 'value' key,
 107 but the second one element of the array will be id of a ticket (XXX), so you
 108 can avoid parsing value in the action. Only eight groups of your regexps are
 109 passed to actions.
 110
 111 =back
 112
 113 =head2 Custom MakeClicky action example
 114
 115 Create a new file F</opt/rt3/local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>
 116 with the content:
 117
 118   <%ARGS>
 119   $types   => []
 120   $actions => {}
 121   </%ARGS>
 122   <%INIT>
 123   my $web_path = RT->Config->Get('WebPath');
 124
 125   # action that takes ticket ID as argument and returns link to the ticket
 126   $actions->{'link_ticket'} = sub {
 127       my %args = @_;
 128       my $id = $args{'all_matches'}[1];
 129       return qq{<a href="$web_path/Ticket/Display.html?id=$id">$args{value}</a>};
 130   };
 131
 132   # add action to the list
 133   push @$types, {
 134       # name, that should be used in config to activate action
 135       name   => 'short_ticket_link',
 136       # regular expression that matches text 'ticket #xxx'
 137       regex  => qr{ticket\s+#(\d+)}i,
 138       # name of the action that should be applied
 139       action => 'link_ticket',
 140   };
 141   </%INIT>
 142
 143 That's all. Add C<short_ticket_link> to C<@Active_MakeClicky> option in your C<RT_SiteConfig.pm>.
 144 Restart your server and create test ticket with 'ticket #1' text.
 145
 146 =head2 Notes for custom clicky actions writers
 147
 148 Note that an action B<must escape> illegal HTML characters with entities and/or
 149 arguments in URLs.
 150
 151 Complex (slow) regular expressions could slow down RT as conversion is run each
 152 time user open a ticket.
 153
 154 Try to match the shortest expression you need with your regular expression otherwise another action could miss its chance to match.
 155
 156 Precalculate values, use closures for functions.
 157