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