rt/docs/creating_external_custom_fields.pod

   1 =head1 External custom fields
   2
   3 =head2 Description
   4
   5 C<External custom fields> is extension to custom fields that allow
   6 you to define CF with a dynamic list of values. Loading values into
   7 this custom fields requires writing a little Perl code to fetch the
   8 data from the external source; the code that we added to RT 3.7
   9 allows it to load data from arbitrary external sources.
  10
  11 =head2 Introduction into writing source of values
  12
  13 For each type of data source that you want, you'll need to put a file
  14 in F</opt/rt3/local/lib/RT/CustomFieldValues/> (or equivilent if you
  15 installed RT someplace other than F</opt/rt3>). To get a sense of the
  16 code that you'll need to write, take a look at the code in
  17 L</opt/rt3/lib/RT/CustomFieldValues/Groups.pm> for a simple example
  18 which just uses RT's API to pull in a list of RT's groups.
  19
  20 Running C<perldoc /opt/rt3/lib/RT/CustomFieldValues/External.pm> will
  21 show you the documentation for the API that needs to be fulfilled, by
  22 copying and editing the C<Groups> example is probably a fine place to
  23 start.
  24
  25 Later in this doc we'll describe the example a little bit more.
  26
  27 =head2 Configuration
  28
  29 After the custom code is written, you need to tell RT about its
  30 existence by adding something like following to your RT_SiteConfig.pm:
  31 Set(@CustomFieldValuesSources, "RT::CustomFieldValues::MySource");
  32
  33 The value in quotes should be the name of the class that you created.
  34
  35 Stop and start your web server to enable any config changes. Open the web interface with
  36 as an administrative user (such as root) create new custom field. In order to use
  37 a custom source of values, you should select a custom field type
  38 that lets users pick values from a list, for example it could be C<Select *>
  39 or a type with autocompletion. It shouldn't be C<Enter one value> type
  40 as this type doesn't allow user to choose values. Other types that
  41 don't have a defined list of values are also unacceptable.
  42
  43 Save the changes, now you have ability to select a "source" for values.
  44 Choose the class you wrote from the list and save changes.
  45
  46 =head2 How to write custom source
  47
  48 You have to implement a subclass of L<RT::CustomFieldValues::External>.
  49 There are two main methods you want to override:
  50
  51 =over 4
  52
  53 =item SourceDescription
  54
  55 This method should return a string describing the data source; this is
  56 the identifier which the adimistrator will see in the dropdown in the web
  57 interface. See L</Configuration>.
  58
  59 =item ExternalValues
  60
  61 This method should return an array reference of hash references.  The
  62 hash references should contain keys for C<name>, C<description>, and
  63 C<sortorder>. C<name> is most important one. The others are optional
  64
  65 =back
  66
  67 Here's a simple static example:
  68
  69   package RT::CustomFieldValues::MySource;
  70
  71   # define class inheritance
  72   use base qw(RT::CustomFieldValues::External);
  73
  74   # admin friendly description, the default valuse is the name of the class
  75   sub SourceDescription {
  76       return 'My Source';
  77   }
  78
  79   # actual values provider method
  80   sub ExternalValues {
  81       # return reference to array ([])
  82       return [
  83           # each element of the array is a reference to hash that describe a value
  84           # possible keys are name, description and sortorder
  85           { name => 'value1', description => 'external value', sortorder => 1 },
  86           { name => 'value2', description => 'another external value', sortorder => 2 },
  87           # values without description are also valid, the default description is empty string
  88           { name => 'value3', sortorder => 3 },
  89           # you can skip sortorder too, but note that the default sortorder is 0 (zero)
  90           { name => 'value3' },
  91       ];
  92   }
  93
  94   1; # don't forget to return some true value
  95
  96 That's all. Install and configure your class as described in the L</Configuration> section.
  97