import rt 3.8.7

[freeside.git] / rt / docs / creating_external_custom_fields.pod

diff --git a/rt/docs/creating_external_custom_fields.pod b/rt/docs/creating_external_custom_fields.pod
new file mode 100644 (file)
index 0000000..f8eca44
--- /dev/null
+++ b/rt/docs/creating_external_custom_fields.pod
@@ -0,0 +1,97 @@
+=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.
+