From a3c3abffe5a964685d596a82261fde79b416107a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Buclin?= <LpSolit@gmail.com>
Date: Thu, 4 Nov 2010 18:00:58 +0100
Subject: Bug 485418: Code and template hooks for userprefs.cgi to be able to
 add additional tabs r=mkanat a=LpSolit

---
 Bugzilla/Hook.pm                                   | 43 ++++++++++++++++++++++
 extensions/Example/Extension.pm                    | 20 ++++++++++
 .../en/default/account/prefs/my_tab.html.tmpl      | 30 +++++++++++++++
 .../hook/account/prefs/prefs-tabs.html.tmpl        | 23 ++++++++++++
 template/en/default/account/prefs/prefs.html.tmpl  |  2 +
 userprefs.cgi                                      | 24 ++++++++----
 6 files changed, 135 insertions(+), 7 deletions(-)
 create mode 100644 extensions/Example/template/en/default/account/prefs/my_tab.html.tmpl
 create mode 100644 extensions/Example/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl

diff --git a/Bugzilla/Hook.pm b/Bugzilla/Hook.pm
index adcb7ff4b..8958b7785 100644
--- a/Bugzilla/Hook.pm
+++ b/Bugzilla/Hook.pm
@@ -1159,6 +1159,49 @@ name), you can get it from here.
 
 =back
 
+=head2 user_preferences
+
+This hook allows you to add additional panels to the User Preferences page,
+and validate data displayed and returned from these panels. It works in
+combination with the C<tabs> hook available in the
+F<template/en/default/account/prefs/prefs.html.tmpl> template. To make it
+work, you must define two templates in your extension:
+F<extensions/Foo/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl>
+contains a list of additional panels to include.
+F<extensions/Foo/template/en/default/account/prefs/bar.html.tmpl> contains
+the content of the panel itself. See the C<Example> extension to see how
+things work.
+
+Params:
+
+=over
+
+=item C<current_tab>
+
+The name of the current panel being viewed by the user. You should always
+make sure that the name of the panel matches what you expect it to be.
+Else you could be interacting with the panel of another extension.
+
+=item C<save_changes>
+
+A boolean which is true when data should be validated and the DB updated
+accordingly. This means the user clicked the "Submit Changes" button.
+
+=item C<handled>
+
+This is a B<reference> to a scalar, not a scalar. (So you would set it like
+C<$$handled = 1>, not like C<$handled = 1>.) Set this to a true value to let
+Bugzilla know that the passed-in panel is valid and that you have handled it.
+(Otherwise, Bugzilla will throw an error that the panel is invalid.) Don't set
+this to true if you didn't handle the panel listed in C<current_tab>.
+
+=item C<vars>
+
+You can add as many new key/value pairs as you want to this hashref.
+It will be passed to the template.
+
+=back
+
 =head2 webservice
 
 This hook allows you to add your own modules to the WebService. (See
diff --git a/extensions/Example/Extension.pm b/extensions/Example/Extension.pm
index 5c6865362..f16ddf725 100644
--- a/extensions/Example/Extension.pm
+++ b/extensions/Example/Extension.pm
@@ -682,6 +682,26 @@ sub bug_check_can_change_field {
     }
 }
 
+sub user_preferences {
+    my ($self, $args) = @_;
+    my $tab = $args->{current_tab};
+    my $save = $args->{save_changes};
+    my $handled = $args->{handled};
+
+    return unless $tab eq 'my_tab';
+
+    my $value = Bugzilla->input_params->{'example_pref'};
+    if ($save) {
+        # Validate your data and update the DB accordingly.
+        $value =~ s/\s+/:/g;
+    }
+    $args->{'vars'}->{example_pref} = $value;
+
+    # Set the 'handled' scalar reference to true so that the caller
+    # knows the panel name is valid and that an extension took care of it.
+    $$handled = 1;
+}
+
 sub webservice {
     my ($self, $args) = @_;
 
diff --git a/extensions/Example/template/en/default/account/prefs/my_tab.html.tmpl b/extensions/Example/template/en/default/account/prefs/my_tab.html.tmpl
new file mode 100644
index 000000000..ca7a3bd13
--- /dev/null
+++ b/extensions/Example/template/en/default/account/prefs/my_tab.html.tmpl
@@ -0,0 +1,30 @@
+[%#
+  # The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Example Plugin.
+  #
+  # The Initial Developer of the Original Code is Frédéric Buclin.
+  # Portions created by the Initial Developer are Copyright (C) 2010
+  # the Initial Developer. All Rights Reserved.
+  #
+  # Contributor(s): Frédéric Buclin <LpSolit@gmail.com>
+  #%]
+
+<p>
+  Type some short text in the field below. Whitespaces will be replaced
+  by colons.
+</p>
+
+<p>
+  <label for="example_pref">Short text:</label>
+  <input type="text" id="example_pref" name="example_pref" size="30"
+         maxlength="50" value="[% example_pref FILTER html %]">
+</p>
diff --git a/extensions/Example/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl b/extensions/Example/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl
new file mode 100644
index 000000000..83801540a
--- /dev/null
+++ b/extensions/Example/template/en/default/hook/account/prefs/prefs-tabs.html.tmpl
@@ -0,0 +1,23 @@
+[%#
+  # The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Example Plugin.
+  #
+  # The Initial Developer of the Original Code is Frédéric Buclin.
+  # Portions created by the Initial Developer are Copyright (C) 2010
+  # the Initial Developer. All Rights Reserved.
+  #
+  # Contributor(s): Frédéric Buclin <LpSolit@gmail.com>
+  #%]
+
+[% tabs = tabs.import([{ name => "my_tab", label => "Example Custom Preferences",
+                         link => "userprefs.cgi?tab=my_tab", saveable => 1 }
+                      ]) %]
diff --git a/template/en/default/account/prefs/prefs.html.tmpl b/template/en/default/account/prefs/prefs.html.tmpl
index 328eb5091..2e7d98c07 100644
--- a/template/en/default/account/prefs/prefs.html.tmpl
+++ b/template/en/default/account/prefs/prefs.html.tmpl
@@ -55,6 +55,8 @@
             { name => "permissions", label => "Permissions", 
               link => "userprefs.cgi?tab=permissions", saveable => "0" } ] %]
 
+[% Hook.process('tabs') %]
+
 [% FOREACH tab IN tabs %]
   [% IF tab.name == current_tab_name %]
     [% current_tab = tab %]
diff --git a/userprefs.cgi b/userprefs.cgi
index 68c7d2748..009361324 100755
--- a/userprefs.cgi
+++ b/userprefs.cgi
@@ -502,7 +502,8 @@ if (!Bugzilla->user->id) {
 }
 Bugzilla->login(LOGIN_REQUIRED);
 
-$vars->{'changes_saved'} = $cgi->param('dosave');
+my $save_changes = $cgi->param('dosave');
+$vars->{'changes_saved'} = $save_changes;
 
 my $current_tab_name = $cgi->param('tab') || "settings";
 
@@ -512,22 +513,22 @@ trick_taint($current_tab_name);
 $vars->{'current_tab_name'} = $current_tab_name;
 
 my $token = $cgi->param('token');
-check_token_data($token, 'edit_user_prefs') if $cgi->param('dosave');
+check_token_data($token, 'edit_user_prefs') if $save_changes;
 
 # Do any saving, and then display the current tab.
 SWITCH: for ($current_tab_name) {
     /^account$/ && do {
-        SaveAccount() if $cgi->param('dosave');
+        SaveAccount() if $save_changes;
         DoAccount();
         last SWITCH;
     };
     /^settings$/ && do {
-        SaveSettings() if $cgi->param('dosave');
+        SaveSettings() if $save_changes;
         DoSettings();
         last SWITCH;
     };
     /^email$/ && do {
-        SaveEmail() if $cgi->param('dosave');
+        SaveEmail() if $save_changes;
         DoEmail();
         last SWITCH;
     };
@@ -536,15 +537,24 @@ SWITCH: for ($current_tab_name) {
         last SWITCH;
     };
     /^saved-searches$/ && do {
-        SaveSavedSearches() if $cgi->param('dosave');
+        SaveSavedSearches() if $save_changes;
         DoSavedSearches();
         last SWITCH;
     };
+    # Extensions must set it to 1 to confirm the tab is valid.
+    my $handled = 0;
+    Bugzilla::Hook::process('user_preferences',
+                            { 'vars'       => $vars,
+                              save_changes => $save_changes,
+                              current_tab  => $current_tab_name,
+                              handled      => \$handled });
+    last SWITCH if $handled;
+
     ThrowUserError("unknown_tab",
                    { current_tab_name => $current_tab_name });
 }
 
-delete_token($token) if $cgi->param('dosave');
+delete_token($token) if $save_changes;
 if ($current_tab_name ne 'permissions') {
     $vars->{'token'} = issue_session_token('edit_user_prefs');
 }
-- 
cgit v1.2.1