1 =head1 MakeClicky extension
5 I<MakeClicky> detects various formats of data in headers and email
6 messages, and extends them with supporting links.
10 You can configure clicky actions from RT config with @Active_MakeClicky
11 option. It's ordered of the actions you want to apply.
13 By default, RT provides two actions:
19 Detects http:// and https:// URLs and adds '[Open URL]' link after the URL.
21 =item httpurl_overwrite
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.
29 RTIR is shipped with several actions you can use: 'ip', 'ipdecimal',
30 'email', 'domain' and 'RIPE'.
32 =head2 Order of clicky actions
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.
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.
48 Text of tickets is plain, but actions could generate arbitrary HTML.
50 =head2 Writing custom MakeClicky actions
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>.
55 It will be provided with arguments:
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:
69 The name of the data format; this is used in the
70 configuration file to enable the format.
74 A regular expression to match against.
78 The name of the action to run (see "actions", below)
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.
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.
95 =head2 Actions' arguments
97 A hash is passed to action with two keys that always exist:
101 =item value - full match of the regular expression, this block of text will be
102 replaced with action's result.
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
113 =head2 Custom MakeClicky action example
115 Create a new file F</opt/rt3/local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>
123 my $web_path = RT->Config->Get('WebPath');
125 # action that takes ticket ID as argument and returns link to the ticket
126 $actions->{'link_ticket'} = sub {
128 my $id = $args{'all_matches'}[1];
129 return qq{<a href="$web_path/Ticket/Display.html?id=$id">$args{value}</a>};
132 # add action to the list
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',
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.
146 =head2 Notes for custom clicky actions writers
148 Note that an action B<must escape> illegal HTML characters with entities and/or
151 Complex (slow) regular expressions could slow down RT as conversion is run each
152 time user open a ticket.
154 Try to match the shortest expression you need with your regular expression otherwise another action could miss its chance to match.
156 Precalculate values, use closures for functions.