diff options
Diffstat (limited to 'rt/docs/creating_external_custom_fields.pod')
-rw-r--r-- | rt/docs/creating_external_custom_fields.pod | 97 |
1 files changed, 0 insertions, 97 deletions
diff --git a/rt/docs/creating_external_custom_fields.pod b/rt/docs/creating_external_custom_fields.pod deleted file mode 100644 index f8eca44fb..000000000 --- a/rt/docs/creating_external_custom_fields.pod +++ /dev/null @@ -1,97 +0,0 @@ -=head1 External custom fields - -=head2 Description - -C<External custom fields> is extension to custom fields that allow -you to define CF with a dynamic 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. - |