Putting 4.2.0 on top of 4.0.17
[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
93=item handler
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
98=back
99
100=head2 Actions' arguments
101
102A hash is passed to the action with two keys that always exist:
103
104=over 4
105
106=item value
107
108The full match of the regular expression; this is the block of text that
109will be replaced with action's result.
110
111=item all_matches
112
113And arrayref with all of the match's capturing groups; for example if
114your regexp is C<qr{ticket\s+#(\d+)}>, then the first element will be
115full match ("ticket #XXX"), the same as in 'value' key, but the second
116element of the array will be the id of a ticket (XXX). Using this, you
117can avoid reparsing the value in the action. Only the first eight
118groups of your regexps are passed to action.
119
120=back
121
122=head2 Custom MakeClicky action example
123
124Create a new file F</opt/rt4/local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>
125with 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
152That's all; add C<short_ticket_link> to the C<@Active_MakeClicky> option
153in your C<RT_SiteConfig.pm>, and restart your server. Creating a ticket
154with "ticket #1" in the body should cause that text to be automatically
155linked to the ticket in question.
156
157=head2 Notes for custom clicky actions writers
158
159=over
160
161=item *
162
163Note that an action B<must escape> illegal HTML characters with entities
164and/or arguments in URLs.
165
166=item *
167
168Complex regular expressions could slow down RT, as the conversion is run
169each time a user opens a ticket, for every transaction. For long
170tickets and complex regular expressions, this can slow down ticket
171display notably.
172
173=item *
174
175Try to match the shortest expression you need with your regular
176expression; otherwise another action may miss its chance to match.
177
178=item *
179
180Whenever possible, precalculate values using closures around the
181functions.
182
183=back
184
185=cut