+++ /dev/null
-=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.
-
projects / freeside.git / blobdiff