Bug 1261679 - Add more examples about how to define new parameters using the config_add_panels hook

r=gerv

3 files changed, 70 insertions, 7 deletions

diff --git a/Bugzilla/Config/Common.pm b/Bugzilla/Config/Common.pm
index 860977b65..6e89fdcae 100644
--- a/Bugzilla/Config/Common.pm
+++ b/Bugzilla/Config/Common.pm
@@ -401,11 +401,6 @@ sub check_comment_taggers_group {
 #      &check_multi should always be used as the param verification function
 #      for list (single and multiple) parameter types.
 #
-# o -- A list of values, orderable, and with many selectable (shows up as a
-#      JavaScript-enhanced select box if JavaScript is enabled, and a text
-#      entry field if not)
-#      Set up in the same way as type m.
-#
 # s -- A list of values, with one selectable (shows up as a select box)
 #      To specify the list of values, make the 'choices' key be an array
 #      reference of the valid choices. The 'default' key should be one of
@@ -424,6 +419,13 @@ sub check_comment_taggers_group {
 #
 #      &check_multi should always be used as the param verification function
 #      for list (single and multiple) parameter types.
+#
+# o -- A list of values, orderable, and with many selectable (shows up as a
+#      JavaScript-enhanced select box if JavaScript is enabled, and a text
+#      entry field if not)
+#      Set up in the same way as type s. If the default has multiple values,
+#      then they must be concatenated, separated by a comma.
+#      For instance: default => 'a,c'.
 
 sub get_param_list {
     return;
diff --git a/extensions/Example/lib/Config.pm b/extensions/Example/lib/Config.pm
index 311ea4a6a..c183b0efc 100644
--- a/extensions/Example/lib/Config.pm
+++ b/extensions/Example/lib/Config.pm
@@ -22,7 +22,58 @@ sub get_param_list {
     {
         name => 'example_string',
         type => 't',
-        default => 'EXAMPLE',
+        default => 'Bugzilla is powerful'
+    },
+    {
+        name => 'example_constrained_string',
+        type => 't',
+        default => '12-xfdd-5',
+        checker => sub { $_[0] =~ /^\d{2}\-[a-zA-Z]{4}\-\d$/ ?
+                         '' : "$_[0] must be of the form NN-XXXX-N"; }
+    },
+    {
+        name => 'example_number',
+        type => 't',
+        default => '905',
+        checker => \&check_numeric
+    },
+    {
+        name => 'example_password',
+        type => 'p',
+        default => '1234'
+    },
+    {
+        name => 'example_multi_lines',
+        type => 'l',
+        default => "This text can be very long.\n\nVery very long!"
+    },
+    # Default can only be 0 or 1.
+    {
+        name => 'example_boolean',
+        type => 'b',
+        default => 0
+    },
+    {
+        name => 'example_single_select',
+        type => 's',
+        choices => [ 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday' ],
+        default => 'Thursday',
+        checker => \&check_multi
+    },
+    {
+        name => 'example_multi_select',
+        type => 'm',
+        choices => [ 'Mercury', 'Venus', 'Mars', 'Jupiter', 'Saturn' ],
+        default => [ 'Venus', 'Saturn' ],
+        checker => \&check_multi
+    },
+    # This one lets you order selected items.
+    {
+        name => 'example_multi_ordered',
+        type => 'o',
+        choices => [ 'Perl', 'Python', 'PHP', 'C++', 'Java' ],
+        default => 'Perl,C++',
+        checker => \&check_multi
     },
     );
     return @param_list;
diff --git a/extensions/Example/template/en/default/admin/params/example.html.tmpl b/extensions/Example/template/en/default/admin/params/example.html.tmpl
index 48143945c..d399ac161 100644
--- a/extensions/Example/template/en/default/admin/params/example.html.tmpl
+++ b/extensions/Example/template/en/default/admin/params/example.html.tmpl
@@ -11,6 +11,16 @@
 %]
 
 [% param_descs = {
-  example_string => "Example string",
+  example_string        => "This parameter accepts any text. (type t)",
+  example_constrained_string => "This parameter accepts only a text of the form " _
+                                "NN-XXXX-N, where N is a digit and X a letter.",
+  example_number        => "This parameter accepts only a positive integer.",
+  example_password      => "Text with all characters replaced by asterisks for " _
+                           "security purposes. (type p)",
+  example_multi_lines   => "Text field permitting multiple lines of text. (type l)",
+  example_boolean       => "You have only two choices: On (1) or Off (0). (type b)",
+  example_single_select => "Select a single value from a list. (type s)",
+  example_multi_select  => "Select none, one or several values from a list. (type m)",
+  example_multi_ordered => "Several values can be selected and ordered. (type o)",
 }
 %]