- MakeClicky extension
  - Description
  - Configuration
  - Order of actions
  - How it works
  - Writing custom MakeClicky actions
  - Actions' arguments
  - Custom MakeClicky action example
  - Notes for custom clicky actions writers

# MakeClicky extension

## Description

MakeClicky detects various formats of data in headers and email messages, and makes them into links in RT's web UI.

## Configuration

You can configure which actions are enabled from RT config with the @Active_MakeClicky option, which should contain an ordered list of the actions you want to apply.

By default, RT provides two actions:

`httpurl`

  Detects `http://` and `https://` URLs and adds an `[Open URL]` link after the URL.

`httpurl_overwrite`

  Detects URLs as `httpurl` format, but replaces the URL with a link.

RTIR, an RT extension for CERT teams (not installed with core RT), shipps with several additional actions you can use: `ip`, `ipdecimal`, `email`, `domain` and `RIPE`.

## Order of actions

The order of the actions is important in situations when you use multiple actions that could match the same block of text; only the first matching action from the list is applied. For example, it makes no sense to use `httpurl` and `httpurl_overwrite` at the same time, as both actions always match the same pieces of text.

## How it works

Each action consists of regular expression and function that does text replacement. When you open the history of a ticket, RT searches in the text with the given regular expresion for matches. If it finds a match, it calls the function with the match as the argument, then replaces the matched text with the string returned by the function.

While RT only searches plaintext content, the actions can generate arbitrary HTML.

## Writing custom MakeClicky actions

To extend the list of actions with your own types of data, use the provided callback. Specifically, create the file /usr/local/share/request-tracker4/html/Callbacks/MyCallbacks/Elements/MakeClicky/Default.

It will be called with the following arguments:

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:

  name

    The name of the data format; this is used in the configuration file to enable the format.

  regex

    A regular expression to match against.

  action

    The name of the action to run (see "actions", below)

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 must escape HTML.

handler

  A subroutine reference; modify it only if you have to. This can be used to add pre- or post-processing around all actions.

## Actions' arguments

A hash is passed to the action with two keys that always exist:

value

  The full match of the regular expression; this is the block of text that will be replaced with action's result.

all_matches

  And arrayref with all of the match's capturing groups; for example if your regexp is `qr{ticket\s+#(\d+)}`, then the first element will be full match ("ticket #XXX"), the same as in 'value' key, but the second element of the array will be the id of a ticket (XXX). Using this, you can avoid reparsing the value in the action. Only the first eight groups of your regexps are passed to action.

## Custom MakeClicky action example

Create a new file /usr/local/share/request-tracker4/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 `short_ticket_link` to the `@Active_MakeClicky` option in your `RT_SiteConfig.pm`, and restart your server. Creating a ticket with "ticket #1" in the body should cause that text to be automatically linked to the ticket in question.

## Notes for custom clicky actions writers

- Note that an action must escape illegal HTML characters with entities and/or arguments in URLs.

- Complex regular expressions could slow down RT, as the conversion is run each time a user opens a ticket, for every transaction. For long tickets and complex regular expressions, this can slow down ticket display notably.

- Try to match the shortest expression you need with your regular expression; otherwise another action may miss its chance to match.

- Whenever possible, precalculate values using closures around the functions.

← Back to index