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