rt/docs/extending/external_custom_fields.pod

   1 =head1 External custom fields
   2
   3 =head2 Description
   4
   5 C<External custom fields> is an extension to custom fields that allow
   6 you to define CFs with dynamic lists of values. Loading values into
   7 these custom fields requires writing a little Perl code to fetch the
   8 data from the external source.
   9
  10 =head2 Introduction into writing source of values
  11
  12 For each type of data source that you want, you'll need to put a file in
  13 F</opt/rt4/local/lib/RT/CustomFieldValues/> (or equivalent if you
  14 installed RT into someplace other than F</opt/rt4>). To get a sense of
  15 the code that you'll need to write, take a look at the code in
  16 F</opt/rt4/lib/RT/CustomFieldValues/Groups.pm> for a simple example
  17 which just uses RT's API to pull in a list of RT's groups.
  18
  19 Running C<perldoc /opt/rt4/lib/RT/CustomFieldValues/External.pm> will
  20 show you the documentation for the API that needs to be fulfilled;
  21 copying and editing the C<Groups> example is probably a fine place to
  22 start.
  23
  24 Later in this doc we'll describe the example a little bit more.
  25
  26 =head2 Configuration
  27
  28 After the custom code is written, you need to tell RT about its
  29 existence by adding something like following to your RT_SiteConfig.pm:
  30
  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
  36 web interface as an administrative user (such as root), and create new
  37 custom field. Set its type to be a Select or Autocomplete field, and
  38 save the changes.  You should now you have ability to select a "source"
  39 for values.  Choose the class you wrote from the list and the save
  40 changes.
  41
  42 =head2 How to write custom source
  43
  44 You have to implement a subclass of L<RT::CustomFieldValues::External>.
  45 There are two main methods you want to override:
  46
  47 =over 4
  48
  49 =item SourceDescription
  50
  51 This method should return a string describing the data source; this is
  52 the identifier which the administrator will see in the dropdown in the
  53 web interface. See L</Configuration>.
  54
  55 =item ExternalValues
  56
  57 This method should return an array reference of hash references.  The
  58 hash references should contain keys for C<name>, C<description>, and
  59 C<sortorder>. C<name> is most important one; the others are optional.
  60 You can also optionally provide a key for C<category> and use the
  61 "Categories are based on" option on the custom field configuration
  62 page to make the values displayed for this custom field vary based
  63 on the value selected in the "based on" custom field.
  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, sortorder, and category
  85           { name => 'value1', description => 'external value', sortorder => 1, category => 'Other CF' },
  86           { name => 'value2', description => 'another external value', sortorder => 2, category => 'Other CF' },
  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