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