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