[Rt-commit] r5170 - in rt/branches/3.7-EXPERIMENTAL: .
jesse at bestpractical.com
jesse at bestpractical.com
Fri May 5 18:42:27 EDT 2006
Author: jesse
Date: Fri May 5 18:42:26 2006
New Revision: 5170
Added:
rt/branches/3.7-EXPERIMENTAL/docs/creating_external_custom_fields.pod
rt/branches/3.7-EXPERIMENTAL/docs/extending_clickable_links.pod
Modified:
rt/branches/3.7-EXPERIMENTAL/ (props changed)
Log:
r13264 at hualien: jesse | 2006-05-05 18:41:38 -0400
* Adding new docs from ruslan!
Added: rt/branches/3.7-EXPERIMENTAL/docs/creating_external_custom_fields.pod
==============================================================================
--- (empty file)
+++ rt/branches/3.7-EXPERIMENTAL/docs/creating_external_custom_fields.pod Fri May 5 18:42:26 2006
@@ -0,0 +1,97 @@
+=head1 External custom fields
+
+=head2 Description
+
+C<External custom fields> is extension to custom fields that allow
+you to define CF with a dinamic list of values. Loading values into
+this custom fields requires writing a little Perl code to fetch the
+data from the external source; the code that we added to RT 3.7
+allows it to load data from arbitrary external sources.
+
+=head2 Introduction into writing source of values
+
+For each type of data source that you want, you'll need to put a file
+in F</opt/rt3/local/lib/RT/CustomFieldValues/> (or equivilent if you
+installed RT someplace other than F</opt/rt3>). To get a sense of the
+code that you'll need to write, take a look at the code in
+L</opt/rt3/lib/RT/CustomFieldValues/Groups.pm> for a simple example
+which just uses RT's API to pull in a list of RT's groups.
+
+Running C<perldoc /opt/rt3/lib/RT/CustomFieldValues/External.pm> will
+show you the documentation for the API that needs to be fulfilled, by
+copying and editing the C<Groups> example is probably a fine place to
+start.
+
+Later in this doc we'll describe the example a little bit more.
+
+=head2 Configuration
+
+After the custom code is written, you need to tell RT about its
+existence by adding something like following to your RT_SiteConfig.pm:
+Set(@CustomFieldValuesSources, "RT::CustomFieldValues::MySource");
+
+The value in quotes should be the name of the class that you created.
+
+Stop and start your web server to enable any config changes. Open the web interface with
+as an administrative user (such as root) create new custom field. In order to use
+a custom source of values, you should select a custom field type
+that lets users pick values from a list, for example it could be C<Select *>
+or a type with autocompletion. It shouldn't be C<Enter one value> type
+as this type doesn't allow user to choose values. Other types that
+don't have a defined list of values are also unacceptable.
+
+Save the changes, now you have ability to select a "source" for values.
+Choose the class you wrote from the list and save changes.
+
+=head2 How to write custom source
+
+You have to implement a subclass of L<RT::CustomFieldValues::External>.
+There are two main methods you want to override:
+
+=over 4
+
+=item SourceDescription
+
+This method should return a string describing the data source; this is
+the identifier which the adimistrator will see in the dropdown in the web
+interface. See L</Configuration>.
+
+=item ExternalValues
+
+This method should return an array reference of hash references. The
+hash references should contain keys for C<name>, C<description>, and
+C<sortorder>. C<name> is most important one. The others are optional
+
+=back
+
+Here's a simple static example:
+
+ package RT::CustomFieldValues::MySource;
+
+ # define class inheritance
+ use base qw(RT::CustomFieldValues::External);
+
+ # admin friendly description, the default valuse is the name of the class
+ sub SourceDescription {
+ return 'My Source';
+ }
+
+ # actual values provider method
+ sub ExternalValues {
+ # return reference to array ([])
+ return [
+ # each element of the array is a reference to hash that describe a value
+ # possible keys are name, description and sortorder
+ { name => 'value1', description => 'external value', sortorder => 1 },
+ { name => 'value2', description => 'another external value', sortorder => 2 },
+ # values without description are also valid, the default description is empty string
+ { name => 'value3', sortorder => 3 },
+ # you can skip sortorder too, but note that the default sortorder is 0 (zero)
+ { name => 'value3' },
+ ];
+ }
+
+ 1; # don't forget to return some true value
+
+That's all. Install and configure your class as described in the L</Configuration> section.
+
Added: rt/branches/3.7-EXPERIMENTAL/docs/extending_clickable_links.pod
==============================================================================
--- (empty file)
+++ rt/branches/3.7-EXPERIMENTAL/docs/extending_clickable_links.pod Fri May 5 18:42:26 2006
@@ -0,0 +1,138 @@
+=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/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 Custom MakeClicky action example
+
+Create a new file F</opt/rt3/local/html/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{'value'} =~ /(\d+)/);
+ 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.
+
+=head3 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.
+
More information about the Rt-commit
mailing list