X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2Fdocs%2Fextending_clickable_links.pod;fp=rt%2Fdocs%2Fextending_clickable_links.pod;h=64326737469fedaf9f79caf62555b3dc73ddeb50;hp=0000000000000000000000000000000000000000;hb=b4b0c7e72d7eaee2fbfc7022022c9698323203dd;hpb=2dfda73eeb3eae2d4f894099754794ef07d060dd

diff --git a/rt/docs/extending_clickable_links.pod b/rt/docs/extending_clickable_links.pod
new file mode 100644
index 000000000..643267374
--- /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.
+