[Rt-commit] rt branch, 4.2/pluggable-cf-types, updated. rt-4.0.1rc1-48-g8ef6a80

Chia-liang Kao clkao at bestpractical.com
Thu Jun 16 10:27:22 EDT 2011


The branch, 4.2/pluggable-cf-types has been updated
       via  8ef6a8081f1a501759d8350d69549c135e163dd7 (commit)
       via  f5fb8fdba6c67142e69f0f92666b5f3bd7b06981 (commit)
      from  eceab20680202278d06d34447c77c18790868c0b (commit)

Summary of changes:
 lib/RT/CustomField/Type.pm                  |  169 ++++++++++++++++++++++++++-
 lib/RT/CustomField/Type/Date.pm             |   48 ++++++++
 lib/RT/CustomField/Type/DateTime.pm         |   48 ++++++++
 lib/RT/CustomField/Type/IPAddress.pm        |   48 ++++++++
 lib/RT/CustomField/Type/IPAddressRange.pm   |   48 ++++++++
 lib/RT/CustomField/Type/ImageWithCaption.pm |   48 ++++++++
 6 files changed, 404 insertions(+), 5 deletions(-)

- Log -----------------------------------------------------------------
commit f5fb8fdba6c67142e69f0f92666b5f3bd7b06981
Author: Chia-liang Kao <clkao at bestpractical.com>
Date:   Thu Jun 16 22:25:55 2011 +0800

    document pluggable CF type

diff --git a/lib/RT/CustomField/Type.pm b/lib/RT/CustomField/Type.pm
index 45595f8..00ce373 100644
--- a/lib/RT/CustomField/Type.pm
+++ b/lib/RT/CustomField/Type.pm
@@ -2,11 +2,63 @@ package RT::CustomField::Type;
 use strict;
 use warnings;
 
+=head1 NAME
+
+  RT::CustomField::Type - Custom Field Type definition
+
+=head1 DESCRIPTION
+
+You can define types for RT's custom field.  For example, if you want
+to create a type ImageWithCatpion, which consists of an uploaded
+image, and an user-entered caption.  You can define how the CF is
+stored, displayed, or even searched.
+
+To define a type, you want to register it in your subclass of
+L<RT::CustomField::Type>:
+
+  RT::CustomField->RegisterType(
+    ImageWithCaption => {
+        sort_order => 55,
+        selection_type => 0,
+        labels         => [
+                    'Upload multiple images with caption',   # loc
+                    'Upload one image with caption',         # loc
+                    'Upload up to [_1] images with caption', # loc
+                  ],
+        class => 'RT::CustomField::Type::ImageWithCaption',
+    }
+  );
+
+You should then override the following methods to customize the type-specific behavior.
+
+=head1 methods for storage and display
+
+for storage, per-object custom field values are stored as
+L<RT::ObjectCustomFieldValue> objects, and the commonly used fields
+are C<ContentType>, C<Content> and C<LargeContent>.
+
+=head2 $class->CanonicalizeForCreate($cf, $ocfv, $args)
+
+Called when the value is being validated or created.  You should
+example C<$args> and make modifications before it is passed to
+C<RT::ObjectCustomFieldValue-E<gt>Create>.  C<$ocfv> can be used to get
+CurrentUser, should you need to access it.
+
+=cut
+
 sub CanonicalizeForCreate {
     my ($self, $cf, $ocfv, $args) = @_;
     return wantarray ? (1) : 1;
 }
 
+=head2 $class->Stringify($ocfv)
+
+for displaying the custom field value in summary.  The default
+behavior pulls C<Content> if it exists, otherwise C<LargeContent> if
+C<ContentType> is text/plain.
+
+=cut
+
 sub Stringify {
     my ($self, $ocfv) = @_;
     my $content = $ocfv->_Value('Content');
@@ -18,10 +70,27 @@ sub Stringify {
     }
 }
 
-sub CanonicalizeForSearch {
-    my ($self, $cf, $value, $op ) = @_;
-    return $value;
-}
+=head1 methods for web interaction
+
+The mason component F<share/html/Elements/EditCustomField$TypeName>
+will be used for creating or editing a custom field value of type
+C<$TypeName>.  F<share/html/Elements/ShowCustomField$TypeName> will be
+used for displaying the value.
+
+=head2 $class->CreateArgsFromWebArgs($cf, $web_args)
+
+This is used for processing cf values when creating a new ticket.
+
+The C<$web_args> are the form values without prefix, from the type's
+corresponding form.
+
+The value returned will be used as the value of the cf when calling
+C<RT::Ticket-E<gt>Create>.  An entry or an arrayref of entries can be
+returned.  Each entry can be a plaintext value, or a hashref for
+creating L<RT::ObjectCustomFieldValue> where the C<Content> field
+should be passed in as C<Value>, for historical reasons.
+
+=cut
 
 sub CreateArgsFromWebArgs {
     my ($self, $cf, $web_args) = @_;
@@ -40,7 +109,7 @@ sub CreateArgsFromWebArgs {
 
 =head2 ValuesFromWeb C<$args>
 
-Parse the args passed in from web
+Helper method for parsing the args passed in from web.
 
 =cut
 
@@ -65,11 +134,46 @@ sub ValuesFromWeb {
     } grep defined, @values;
 }
 
+=head1 methods for search and search builder
+
+By default the search behavor works on the custom field value's
+C<Content>, and provides some default op for the user to choose from
+in the search builder.  If you want to perform different types of
+search, you need to override some of the methods here.
+
+=head2 $class->CanonicalizeForSearch($cf, $value, $op)
+
+Canonicalize user-entered value for searching.
+
+=cut
+
+sub CanonicalizeForSearch {
+    my ($self, $cf, $value, $op ) = @_;
+    return $value;
+}
+
+=head2 $class->Limit($tickets, $field, $value, $op, %rest)
+
+If you want to perform search other than simple C<==> and C<!=> on
+C<Content> of the custom field value, you need to write your own
+DBIx::SearchBuilder rules here.  see
+L<RT::CustomField::Type::IPAddressRange> for examples.
+
+=cut
 
 sub Limit {
     return;
 }
 
+=head2 $class->SearchBuilderUIArguments($cf)
+
+Returns a hash where key C<Op> is a hashref of spec for the mason
+component for showing operators in search builder, and optionally key
+C<Value> for mason conponents for entering/selecting values during
+search.
+
+=cut
+
 sub SearchBuilderUIArguments {
     my ($self, $cf) = @_;
 
@@ -90,4 +194,11 @@ sub SearchBuilderUIArguments {
         });
 }
 
+=head1 SEE ALSO
+
+L<RT::CustomField::Type::IPAddress> and L<RT::CustomField::Type::Date> for examples.
+
+=cut
+
 1;
+

commit 8ef6a8081f1a501759d8350d69549c135e163dd7
Author: Chia-liang Kao <clkao at bestpractical.com>
Date:   Thu Jun 16 22:26:47 2011 +0800

    tag new files with licenses.

diff --git a/lib/RT/CustomField/Type.pm b/lib/RT/CustomField/Type.pm
index 00ce373..6640ea0 100644
--- a/lib/RT/CustomField/Type.pm
+++ b/lib/RT/CustomField/Type.pm
@@ -1,3 +1,51 @@
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
+#                                          <sales at bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+
 package RT::CustomField::Type;
 use strict;
 use warnings;
diff --git a/lib/RT/CustomField/Type/Date.pm b/lib/RT/CustomField/Type/Date.pm
index 13b0c7d..c896de7 100644
--- a/lib/RT/CustomField/Type/Date.pm
+++ b/lib/RT/CustomField/Type/Date.pm
@@ -1,3 +1,51 @@
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
+#                                          <sales at bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+
 package RT::CustomField::Type::Date;
 use strict;
 use warnings;
diff --git a/lib/RT/CustomField/Type/DateTime.pm b/lib/RT/CustomField/Type/DateTime.pm
index c415a69..b46e25e 100644
--- a/lib/RT/CustomField/Type/DateTime.pm
+++ b/lib/RT/CustomField/Type/DateTime.pm
@@ -1,3 +1,51 @@
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
+#                                          <sales at bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+
 package RT::CustomField::Type::DateTime;
 use strict;
 use warnings;
diff --git a/lib/RT/CustomField/Type/IPAddress.pm b/lib/RT/CustomField/Type/IPAddress.pm
index 640f0db..577e731 100644
--- a/lib/RT/CustomField/Type/IPAddress.pm
+++ b/lib/RT/CustomField/Type/IPAddress.pm
@@ -1,3 +1,51 @@
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
+#                                          <sales at bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+
 package RT::CustomField::Type::IPAddress;
 use strict;
 use warnings;
diff --git a/lib/RT/CustomField/Type/IPAddressRange.pm b/lib/RT/CustomField/Type/IPAddressRange.pm
index 9e5b3e9..2aebae4 100644
--- a/lib/RT/CustomField/Type/IPAddressRange.pm
+++ b/lib/RT/CustomField/Type/IPAddressRange.pm
@@ -1,3 +1,51 @@
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
+#                                          <sales at bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+
 package RT::CustomField::Type::IPAddressRange;
 use strict;
 use warnings;
diff --git a/lib/RT/CustomField/Type/ImageWithCaption.pm b/lib/RT/CustomField/Type/ImageWithCaption.pm
index 08592fb..79067e3 100644
--- a/lib/RT/CustomField/Type/ImageWithCaption.pm
+++ b/lib/RT/CustomField/Type/ImageWithCaption.pm
@@ -1,3 +1,51 @@
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
+#                                          <sales at bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+
 package RT::CustomField::Type::ImageWithCaption;
 use strict;
 use warnings;

-----------------------------------------------------------------------


More information about the Rt-commit mailing list