diff options
Diffstat (limited to 'rt/docs/extending_clickable_links.pod')
-rw-r--r-- | rt/docs/extending_clickable_links.pod | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/rt/docs/extending_clickable_links.pod b/rt/docs/extending_clickable_links.pod new file mode 100644 index 0000000..6432673 --- /dev/null +++ b/rt/docs/extending_clickable_links.pod @@ -0,0 +1,157 @@ +=head1 MakeClicky extension + +=head2 Description + +I<MakeClicky> detects various formats of data in headers and email +messages, and extends them with supporting links. + +=head2 Configuration + +You can configure clicky actions from RT config with @Active_MakeClicky +option. It's ordered of the actions you want to apply. + +By default, RT provides two actions: + +=over 4 + +=item httpurl + +Detects http:// and https:// URLs and adds '[Open URL]' link after the URL. + +=item httpurl_overwrite + +Also detects URLs as 'httpurl' format, but replace URL with link +and *adds spaces* into text if it's longer then 30 chars. This allow +browser to wrap long URLs and avoid horizontal scrolling. + +=back + +RTIR is shipped with several actions you can use: 'ip', 'ipdecimal', +'email', 'domain' and 'RIPE'. + +=head2 Order of clicky actions + +Order of actions is important in situations when you use actions that +could match the same block of a text, in this case only the first matching +action from the list would be applied. For example ot makes no sense to +use C<httpurl> and C<httpurl_overwrite> at the same time as both actions +always match the same piece of a text. + +=head2 How it works + +Each action consists of regular expression and function that do text replace. +When you open history of a ticket RT search in the text with the regular expresion +for matches. If some piece of the text matches it calls the function with the match +as argument, then replace matched text with string returned by the function. So +in two words this feature works like 'Search and Replace' with an active replacer. + +Text of tickets is plain, but actions could generate arbitrary HTML. + +=head2 Writing custom MakeClicky actions + +To extend the list of actions with your own types of data, use the callback. Create +file F<local/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default>. + +It will be provided with 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 handler + +A subroutine reference; modify it only if you have to. This can be used +to add pre- or post-processing around all actions. + +=back + +=head2 Actions' arguments + +A hash is passed to action with two keys that always exist: + +=over 4 + +=item value - full match of the regular expression, this block of text will be +replaced with action's result. + +=item all_matches - array with all matches including groups defined in the +regular expression, 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 one element of the array will be id of a ticket (XXX), so you +can avoid parsing value in the action. Only eight groups of your regexps are +passed to actions. + +=back + +=head2 Custom MakeClicky action example + +Create a new file F</opt/rt3/local/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 C<@Active_MakeClicky> option in your C<RT_SiteConfig.pm>. +Restart your server and create test ticket with 'ticket #1' text. + +=head2 Notes for custom clicky actions writers + +Note that an action B<must escape> illegal HTML characters with entities and/or +arguments in URLs. + +Complex (slow) regular expressions could slow down RT as conversion is run each +time user open a ticket. + +Try to match the shortest expression you need with your regular expression otherwise another action could miss its chance to match. + +Precalculate values, use closures for functions. + |