diff options
Diffstat (limited to 'rt/docs/extending_clickable_links.pod')
-rw-r--r-- | rt/docs/extending_clickable_links.pod | 157 |
1 files changed, 0 insertions, 157 deletions
diff --git a/rt/docs/extending_clickable_links.pod b/rt/docs/extending_clickable_links.pod deleted file mode 100644 index 6432673..0000000 --- a/rt/docs/extending_clickable_links.pod +++ /dev/null @@ -1,157 +0,0 @@ -=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. - |