Putting 4.2.0 on top of 4.0.17
[usit-rt.git] / 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 makes them into links in RT's web UI.
7
8 =head2 Configuration
9
10 You can configure which actions are enabled from RT config with the
11 @Active_MakeClicky option, which should contain an ordered list of the
12 actions you want to apply.
13
14 By default, RT provides two actions:
15
16 =over 4
17
18 =item C<httpurl>
19
20 Detects C<http://> and C<https://> URLs and adds an C<[Open URL]> link
21 after the URL.
22
23 =item C<httpurl_overwrite>
24
25 Detects URLs as C<httpurl> format, but replaces the URL with a link.
26 This action is enabled by default.
27
28 =back
29
30 RTIR, an RT extension for CERT teams (not installed with core RT),
31 shipps with several additional actions you can use: C<ip>, C<ipdecimal>,
32 C<email>, C<domain> and C<RIPE>.
33
34 =head2 Order of actions
35
36 The order of the actions is important in situations when you use
37 multiple actions that could match the same block of text; only the first
38 matching action from the list is applied. For example, it makes no sense
39 to use C<httpurl> and C<httpurl_overwrite> at the same time, as both
40 actions always match the same pieces of text.
41
42 =head2 How it works
43
44 Each action consists of regular expression and function that does text
45 replacement.  When you open the history of a ticket, RT searches in the
46 text with the given regular expresion for matches. If it finds a match,
47 it calls the function with the match as the argument, then replaces the
48 matched text with the string returned by the function.
49
50 While RT only searches plaintext content, the actions can generate
51 arbitrary HTML.
52
53 =head2 Writing custom MakeClicky actions
54
55 To extend the list of actions with your own types of data, use the
56 provided callback. Specifically, create the file
57 F<local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>.
58
59 It will be called with the following arguments:
60
61 =over 4
62
63 =item types
64
65 An array reference of hash references.  Modify this array
66 reference to add your own types; the first matching type will be
67 used. Each hashref should contain:
68
69 =over 4
70
71 =item name
72
73 The name of the data format; this is used in the configuration file to
74 enable the format.
75
76 =item regex
77
78 A regular expression to match against.
79
80 =item action
81
82 The name of the action to run (see "actions", below)
83
84 =back
85
86 =item actions
87
88 A hash reference of 'actions'.  Modify this hash reference to change or
89 add action types.  Values are subroutine references which will get
90 called when needed.  They should return the modified string. Note that
91 subroutine B<must escape> HTML.
92
93 =item handler
94
95 A subroutine reference; modify it only if you have to. This can be used
96 to add pre- or post-processing around all actions.
97
98 =back
99
100 =head2 Actions' arguments
101
102 A hash is passed to the action with two keys that always exist:
103
104 =over 4
105
106 =item value
107
108 The full match of the regular expression; this is the block of text that
109 will be replaced with action's result.
110
111 =item all_matches
112
113 And arrayref with all of the match's capturing groups; for example if
114 your regexp is C<qr{ticket\s+#(\d+)}>, then the first element will be
115 full match ("ticket #XXX"), the same as in 'value' key, but the second
116 element of the array will be the id of a ticket (XXX).  Using this, you
117 can avoid reparsing the value in the action.  Only the first eight
118 groups of your regexps are passed to action.
119
120 =back
121
122 =head2 Custom MakeClicky action example
123
124 Create a new file F</opt/rt4/local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>
125 with the content:
126
127   <%ARGS>
128   $types   => []
129   $actions => {}
130   </%ARGS>
131   <%INIT>
132   my $web_path = RT->Config->Get('WebPath');
133   
134   # action that takes ticket ID as argument and returns link to the ticket
135   $actions->{'link_ticket'} = sub {
136       my %args = @_;
137       my $id = $args{'all_matches'}[1];
138       return qq{<a href="$web_path/Ticket/Display.html?id=$id">$args{value}</a>};
139   };
140   
141   # add action to the list
142   push @$types, {
143       # name, that should be used in config to activate action
144       name   => 'short_ticket_link',
145       # regular expression that matches text 'ticket #xxx'
146       regex  => qr{ticket\s+#(\d+)}i,
147       # name of the action that should be applied
148       action => 'link_ticket',
149   };
150   </%INIT>
151
152 That's all; add C<short_ticket_link> to the C<@Active_MakeClicky> option
153 in your C<RT_SiteConfig.pm>, and restart your server.  Creating a ticket
154 with "ticket #1" in the body should cause that text to be automatically
155 linked to the ticket in question.
156
157 =head2 Notes for custom clicky actions writers
158
159 =over
160
161 =item *
162
163 Note that an action B<must escape> illegal HTML characters with entities
164 and/or arguments in URLs.
165
166 =item *
167
168 Complex regular expressions could slow down RT, as the conversion is run
169 each time a user opens a ticket, for every transaction.  For long
170 tickets and complex regular expressions, this can slow down ticket
171 display notably.
172
173 =item *
174
175 Try to match the shortest expression you need with your regular
176 expression; otherwise another action may miss its chance to match.
177
178 =item *
179
180 Whenever possible, precalculate values using closures around the
181 functions.
182
183 =back
184
185 =cut