]>
Commit | Line | Data |
---|---|---|
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 | L</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 | ||
61 | =back | |
62 | ||
63 | Here's a simple static example: | |
64 | ||
65 | package RT::CustomFieldValues::MySource; | |
66 | ||
67 | # define class inheritance | |
68 | use base qw(RT::CustomFieldValues::External); | |
69 | ||
70 | # admin friendly description, the default valuse is the name of the class | |
71 | sub SourceDescription { | |
72 | return 'My Source'; | |
73 | } | |
74 | ||
75 | # actual values provider method | |
76 | sub ExternalValues { | |
77 | # return reference to array ([]) | |
78 | return [ | |
79 | # each element of the array is a reference to hash that describe a value | |
80 | # possible keys are name, description and sortorder | |
81 | { name => 'value1', description => 'external value', sortorder => 1 }, | |
82 | { name => 'value2', description => 'another external value', sortorder => 2 }, | |
83 | # values without description are also valid, the default description is empty string | |
84 | { name => 'value3', sortorder => 3 }, | |
85 | # you can skip sortorder too, but note that the default sortorder is 0 (zero) | |
86 | { name => 'value3' }, | |
87 | ]; | |
88 | } | |
89 | ||
90 | 1; # don't forget to return some true value |