]>
Commit | Line | Data |
---|---|---|
84fb5b46 MKG |
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. | |
af59614d | 26 | This action is enabled by default. |
84fb5b46 MKG |
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 | ||
c33a4027 | 93 | =item handle |
84fb5b46 MKG |
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 | ||
c33a4027 MKG |
98 | =item cache |
99 | ||
100 | An undefined variable that should be replaced with a subroutine | |
101 | reference. This subroutine will be called twice, once with the arguments | |
102 | fetch => content_ref and once with store => content_ref. In the fetch | |
103 | case, if a cached copy is found, return the cached content, otherwise | |
104 | return a false value. When passed store, you should populate your cache | |
105 | with the content. The return value is ignored in this case. | |
106 | ||
84fb5b46 MKG |
107 | =back |
108 | ||
109 | =head2 Actions' arguments | |
110 | ||
111 | A hash is passed to the action with two keys that always exist: | |
112 | ||
113 | =over 4 | |
114 | ||
115 | =item value | |
116 | ||
117 | The full match of the regular expression; this is the block of text that | |
118 | will be replaced with action's result. | |
119 | ||
120 | =item all_matches | |
121 | ||
122 | And arrayref with all of the match's capturing groups; for example if | |
123 | your regexp is C<qr{ticket\s+#(\d+)}>, then the first element will be | |
124 | full match ("ticket #XXX"), the same as in 'value' key, but the second | |
125 | element of the array will be the id of a ticket (XXX). Using this, you | |
126 | can avoid reparsing the value in the action. Only the first eight | |
127 | groups of your regexps are passed to action. | |
128 | ||
129 | =back | |
130 | ||
131 | =head2 Custom MakeClicky action example | |
132 | ||
133 | Create a new file F</opt/rt4/local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default> | |
134 | with 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 | ||
161 | That's all; add C<short_ticket_link> to the C<@Active_MakeClicky> option | |
162 | in your C<RT_SiteConfig.pm>, and restart your server. Creating a ticket | |
163 | with "ticket #1" in the body should cause that text to be automatically | |
164 | linked to the ticket in question. | |
165 | ||
166 | =head2 Notes for custom clicky actions writers | |
167 | ||
168 | =over | |
169 | ||
170 | =item * | |
171 | ||
172 | Note that an action B<must escape> illegal HTML characters with entities | |
173 | and/or arguments in URLs. | |
174 | ||
175 | =item * | |
176 | ||
177 | Complex regular expressions could slow down RT, as the conversion is run | |
178 | each time a user opens a ticket, for every transaction. For long | |
179 | tickets and complex regular expressions, this can slow down ticket | |
180 | display notably. | |
181 | ||
182 | =item * | |
183 | ||
184 | Try to match the shortest expression you need with your regular | |
185 | expression; otherwise another action may miss its chance to match. | |
186 | ||
187 | =item * | |
188 | ||
189 | Whenever possible, precalculate values using closures around the | |
190 | functions. | |
191 | ||
192 | =back | |
193 | ||
194 | =cut |