Commit 62e7d4e0 authored by Max Kanat-Alexander's avatar Max Kanat-Alexander

Bug 581311: Bring the documentation of various hooks in Bugzilla::Hook

up to date r=mkanat, a=mkanat (module owner)
parent 9a1d5db8
...@@ -84,7 +84,7 @@ F<extensions/Example/Extension.pm>. ...@@ -84,7 +84,7 @@ F<extensions/Example/Extension.pm>.
When a hook named C<HOOK_NAME> is run, Bugzilla looks through all When a hook named C<HOOK_NAME> is run, Bugzilla looks through all
enabled L<extensions|Bugzilla::Extension> for extensions that implement enabled L<extensions|Bugzilla::Extension> for extensions that implement
a subroutined named C<HOOK_NAME>. a subroutine named C<HOOK_NAME>.
See L<Bugzilla::Extension> for more details about how an extension See L<Bugzilla::Extension> for more details about how an extension
can run code during a hook. can run code during a hook.
...@@ -101,8 +101,8 @@ can run code during a hook. ...@@ -101,8 +101,8 @@ can run code during a hook.
Invoke any code hooks with a matching name from any installed extensions. Invoke any code hooks with a matching name from any installed extensions.
See C<customization.xml> in the Bugzilla Guide for more information on See L<Bugzilla::Extension> for more information on Bugzilla's extension
Bugzilla's extension mechanism. mechanism.
=item B<Params> =item B<Params>
...@@ -111,7 +111,7 @@ Bugzilla's extension mechanism. ...@@ -111,7 +111,7 @@ Bugzilla's extension mechanism.
=item C<$name> - The name of the hook to invoke. =item C<$name> - The name of the hook to invoke.
=item C<$args> - A hashref. The named args to pass to the hook. =item C<$args> - A hashref. The named args to pass to the hook.
They will be accessible to the hook via L<Bugzilla/hook_args>. They will be passed as arguments to the hook method in the extension.
=back =back
...@@ -140,8 +140,9 @@ Params: ...@@ -140,8 +140,9 @@ Params:
=item C<data> - A reference pointing either to the content of the file =item C<data> - A reference pointing either to the content of the file
being uploaded or pointing to the filehandle associated with the file. being uploaded or pointing to the filehandle associated with the file.
=item C<attributes> - A hashref whose keys are the same as =item C<attributes> - A hashref whose keys are the same as the input to
L<Bugzilla::Attachment/create>. The data it contains hasn't been checked yet. L<Bugzilla::Attachment/create>. The data in this hashref hasn't been validated
yet.
=back =back
...@@ -163,7 +164,8 @@ actual path to the module on disk. (For example, if the key is C<DB>, the ...@@ -163,7 +164,8 @@ actual path to the module on disk. (For example, if the key is C<DB>, the
value is F<Bugzilla/Auth/Login/DB.pm>.) value is F<Bugzilla/Auth/Login/DB.pm>.)
For your extension, the path will start with For your extension, the path will start with
F<extensions/yourextension/lib/>. (See the code in the example extension.) F<Bugzilla/Extension/Foo/>, where "Foo" is the name of your Extension.
(See the code in the example extension.)
If your login type is in the hash as a key, you should set that key to the If your login type is in the hash as a key, you should set that key to the
right path to your module. That module's C<new> method will be called, right path to your module. That module's C<new> method will be called,
...@@ -211,7 +213,8 @@ Params: ...@@ -211,7 +213,8 @@ Params:
=item C<bug> - The changed bug object, with all fields set to their updated =item C<bug> - The changed bug object, with all fields set to their updated
values. values.
=item C<timestamp> - The timestamp used for all updates in this transaction. =item C<timestamp> - The timestamp used for all updates in this transaction,
as a SQL date string.
=back =back
...@@ -250,7 +253,8 @@ their updated values (so it has the old values available for each field). ...@@ -250,7 +253,8 @@ their updated values (so it has the old values available for each field).
=item C<timestamp> =item C<timestamp>
The timestamp used for all updates in this transaction. The timestamp used for all updates in this transaction, as a SQL date
string.
=item C<changes> =item C<changes>
...@@ -260,11 +264,14 @@ The hash of changed fields. C<< $changes->{field} = [old, new] >> ...@@ -260,11 +264,14 @@ The hash of changed fields. C<< $changes->{field} = [old, new] >>
=head2 bug_check_can_change_field =head2 bug_check_can_change_field
This hook controls what fields users are allowed to change. You can add code here for This hook controls what fields users are allowed to change. You can add code
site-specific policy changes and other customizations. This hook is only here for site-specific policy changes and other customizations.
executed if the field's new and old values differ. Any denies take priority over any allows.
So, if another extension denies a change but yours allows the change, the other extension's This hook is only executed if the field's new and old values differ.
deny will override your extension's allow.
Any denies take priority over any allows. So, if another extension denies
a change but yours allows the change, the other extension's deny will
override your extension's allow.
Params: Params:
...@@ -379,9 +386,8 @@ A B<reference> to the exact text that you are parsing. ...@@ -379,9 +386,8 @@ A B<reference> to the exact text that you are parsing.
Generally you should not modify this yourself. Instead you should be Generally you should not modify this yourself. Instead you should be
returning regular expressions using the C<regexes> array. returning regular expressions using the C<regexes> array.
The text has already been word-wrapped, but has not been parsed in any way The text has not been parsed in any way. (So, for example, it is not
otherwise. (So, for example, it is not HTML-escaped. You get "&", not HTML-escaped. You get "&", not "&amp;".)
"&amp;".)
=item C<bug> =item C<bug>
...@@ -390,9 +396,8 @@ C<undef>, meaning that we are parsing text that is not on a bug. ...@@ -390,9 +396,8 @@ C<undef>, meaning that we are parsing text that is not on a bug.
=item C<comment> =item C<comment>
A hashref representing the comment you are about to parse, including A L<Bugzilla::Comment> object representing the comment you are about to
all of the fields that comments contain when they are returned by parse.
by L<Bugzilla::Bug/longdescs>.
Sometimes this is C<undef>, meaning that we are parsing text that is Sometimes this is C<undef>, meaning that we are parsing text that is
not a bug comment (but could still be some other part of a bug, like not a bug comment (but could still be some other part of a bug, like
...@@ -402,9 +407,9 @@ the summary line). ...@@ -402,9 +407,9 @@ the summary line).
=head2 buglist_columns =head2 buglist_columns
This happens in buglist.cgi after the standard columns have been defined and This happens in L<Bugzilla::Search/COLUMNS>, which determines legal bug
right before the display column determination. It gives you the opportunity list columns for F<buglist.cgi> and F<colchange.cgi>. It gives you the
to add additional display columns. opportunity to add additional display columns.
Params: Params:
...@@ -508,13 +513,13 @@ Params: ...@@ -508,13 +513,13 @@ Params:
=item C<panel_modules> =item C<panel_modules>
A hashref, where the keys are the "name" of the module and the value A hashref, where the keys are the "name" of the panel and the value
is the Perl module containing that config module. For example, if is the Perl module representing that panel. For example, if
the name is C<Auth>, the value would be C<Bugzilla::Config::Auth>. the name is C<Auth>, the value would be C<Bugzilla::Config::Auth>.
For your extension, the Perl module name must start with For your extension, the Perl module would start with
C<extensions::yourextension::lib>. (See the code in the example C<Bugzilla::Extension::Foo>, where "Foo" is the name of your Extension.
extension.) (See the code in the example extension.)
=back =back
...@@ -558,9 +563,9 @@ Params: ...@@ -558,9 +563,9 @@ Params:
=head2 flag_end_of_update =head2 flag_end_of_update
This happens at the end of L<Bugzilla::Flag/update_flags>, after all other changes This happens at the end of L<Bugzilla::Flag/update_flags>, after all other
are made to the database and after emails are sent. It gives you a before/after changes are made to the database and after emails are sent. It gives you a
snapshot of flags so you can react to specific flag changes. before/after snapshot of flags so you can react to specific flag changes.
This generally occurs inside a database transaction. This generally occurs inside a database transaction.
Note that the interface to this hook is B<UNSTABLE> and it may change in the Note that the interface to this hook is B<UNSTABLE> and it may change in the
...@@ -572,7 +577,8 @@ Params: ...@@ -572,7 +577,8 @@ Params:
=item C<object> - The changed bug or attachment object. =item C<object> - The changed bug or attachment object.
=item C<timestamp> - The timestamp used for all updates in this transaction. =item C<timestamp> - The timestamp used for all updates in this transaction,
as a SQL date string.
=item C<old_flags> - The snapshot of flag summaries from before the change. =item C<old_flags> - The snapshot of flag summaries from before the change.
...@@ -606,8 +612,9 @@ Params: ...@@ -606,8 +612,9 @@ Params:
=over =over
=item C<group> - The changed L<Bugzilla::Group> object, with all fields set =item C<group>
to their updated values.
The new L<Bugzilla::Group> object that was just created.
=back =back
...@@ -640,6 +647,9 @@ Params: ...@@ -640,6 +647,9 @@ Params:
=item C<silent> =item C<silent>
A flag that indicates whether or not checksetup is running in silent mode. A flag that indicates whether or not checksetup is running in silent mode.
If this is true, messages that are I<always> printed by checksetup.pl should be
suppressed, but messages about any changes that are just being done this one
time should be printed.
=back =back
...@@ -647,13 +657,14 @@ A flag that indicates whether or not checksetup is running in silent mode. ...@@ -647,13 +657,14 @@ A flag that indicates whether or not checksetup is running in silent mode.
This happens at the very end of all the tables being updated This happens at the very end of all the tables being updated
during an installation or upgrade. If you need to modify your custom during an installation or upgrade. If you need to modify your custom
schema, do it here. No params are passed. schema or add new columns to existing tables, do it here. No params are
passed.
=head2 db_schema_abstract_schema =head2 db_schema_abstract_schema
This allows you to add tables to Bugzilla. Note that we recommend that you This allows you to add tables to Bugzilla. Note that we recommend that you
prefix the names of your tables with some word, so that they don't conflict prefix the names of your tables with some word (preferably the name of
with any future Bugzilla tables. your Extension), so that they don't conflict with any future Bugzilla tables.
If you wish to add new I<columns> to existing Bugzilla tables, do that If you wish to add new I<columns> to existing Bugzilla tables, do that
in L</install_update_db>. in L</install_update_db>.
...@@ -952,6 +963,10 @@ C<page.cgi?id=fields.html> loads F<template/en/default/pages/fields.html.tmpl>. ...@@ -952,6 +963,10 @@ C<page.cgi?id=fields.html> loads F<template/en/default/pages/fields.html.tmpl>.
This hook is called right before the template is loaded, so that you can This hook is called right before the template is loaded, so that you can
pass your own variables to your own pages. pass your own variables to your own pages.
You can also use this to implement complex custom pages, by doing your own
output and then calling C<exit> at the end of the hook, thus preventing
the normal C<page.cgi> behavior from occurring.
Params: Params:
=over =over
...@@ -962,6 +977,9 @@ This is the name of the page being loaded, like C<fields.html>. ...@@ -962,6 +977,9 @@ This is the name of the page being loaded, like C<fields.html>.
Note that if two extensions use the same name, it is uncertain which will Note that if two extensions use the same name, it is uncertain which will
override the others, so you should be careful with how you name your pages. override the others, so you should be careful with how you name your pages.
Usually extensions prefix their pages with a directory named after their
extension, so for an extension named "Foo", page ids usually look like
C<foo/mypage.html>.
=item C<vars> =item C<vars>
...@@ -988,8 +1006,13 @@ Params: ...@@ -988,8 +1006,13 @@ Params:
Called right after a new product has been created, allowing additional Called right after a new product has been created, allowing additional
changes to be made to the new product's attributes. This occurs inside of changes to be made to the new product's attributes. This occurs inside of
a database transaction, so if the hook throws an error all previous a database transaction, so if the hook throws an error, all previous
changes will be rolled back including the creation of the new product. changes will be rolled back, including the creation of the new product.
(However, note that such rollbacks should not normally be used, as
some databases that Bugzilla supports have very bad rollback performance.
If you want to validate input and throw errors before the Product is created,
use L</object_end_of_create_validators> instead, or add a validator
using L</object_validators>.)
Params: Params:
...@@ -1104,20 +1127,20 @@ Params: ...@@ -1104,20 +1127,20 @@ Params:
=item C<dispatch> =item C<dispatch>
A hashref that you can specify the names of your modules and what Perl A hashref where you can specify the names of your modules and which Perl
module handles the functions for that module. (This is actually sent to module handles the functions for that module. (This is actually sent to
L<SOAP::Lite/dispatch_with>. You can see how that's used in F<xmlrpc.cgi>.) L<SOAP::Lite/dispatch_with>. You can see how that's used in F<xmlrpc.cgi>.)
The Perl module name must start with C<extensions::yourextension::lib::> The Perl module name will most likely start with C<Bugzilla::Extension::Foo::>
(replace C<yourextension> with the name of your extension). The C<package> (where "Foo" is the name of your extension).
declaration inside that module must also start with
C<extensions::yourextension::lib::> in that module's code.
Example: Example:
$dispatch->{Example} = "extensions::example::lib::Example"; $dispatch->{'Example.Blah'} = "Bugzilla::Extension::Example::Webservice::Blah";
And then you'd have a module F<extensions/example/lib/Example.pm> And then you'd have a module F<extensions/Example/lib/Webservice/Blah.pm>,
and could call methods from that module like C<Example.Blah.Foo()> using
the WebServices interface.
It's recommended that all the keys you put in C<dispatch> start with the It's recommended that all the keys you put in C<dispatch> start with the
name of your extension, so that you don't conflict with the standard Bugzilla name of your extension, so that you don't conflict with the standard Bugzilla
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment