When a hook named C<HOOK_NAME> is run, Bugzilla looks through all
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
can run code during a hook.
Invoke any code hooks with a matching name from any installed extensions.
-See C<customization.xml> in the Bugzilla Guide for more information on
-Bugzilla's extension mechanism.
+See L<Bugzilla::Extension> for more information on Bugzilla's extension
+mechanism.
=item B<Params>
=item C<$name> - The name of the hook to invoke.
=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
=item C<data> - A reference pointing either to the content of the file
being uploaded or pointing to the filehandle associated with the file.
-=item C<attributes> - A hashref whose keys are the same as
-L<Bugzilla::Attachment/create>. The data it contains hasn't been checked yet.
+=item C<attributes> - A hashref whose keys are the same as the input to
+L<Bugzilla::Attachment/create>. The data in this hashref hasn't been validated
+yet.
=back
value is F<Bugzilla/Auth/Login/DB.pm>.)
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
right path to your module. That module's C<new> method will be called,
=item C<bug> - The changed bug object, with all fields set to their updated
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
=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>
Generally you should not modify this yourself. Instead you should be
returning regular expressions using the C<regexes> array.
-The text has already been word-wrapped, but has not been parsed in any way
-otherwise. (So, for example, it is not HTML-escaped. You get "&", not
-"&".)
+The text has not been parsed in any way. (So, for example, it is not
+HTML-escaped. You get "&", not "&".)
=item C<bug>
=item C<comment>
-A hashref representing the comment you are about to parse, including
-all of the fields that comments contain when they are returned by
-by L<Bugzilla::Bug/longdescs>.
+A L<Bugzilla::Comment> object representing the comment you are about to
+parse.
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
=head2 buglist_columns
-This happens in buglist.cgi after the standard columns have been defined and
-right before the display column determination. It gives you the opportunity
-to add additional display columns.
+This happens in L<Bugzilla::Search/COLUMNS>, which determines legal bug
+list columns for F<buglist.cgi> and F<colchange.cgi>. It gives you the
+opportunity to add additional display columns.
Params:
=item C<panel_modules>
-A hashref, where the keys are the "name" of the module and the value
-is the Perl module containing that config module. For example, if
+A hashref, where the keys are the "name" of the panel and the value
+is the Perl module representing that panel. For example, if
the name is C<Auth>, the value would be C<Bugzilla::Config::Auth>.
-For your extension, the Perl module name must start with
-C<extensions::yourextension::lib>. (See the code in the example
-extension.)
+For your extension, the Perl module would start with
+C<Bugzilla::Extension::Foo>, where "Foo" is the name of your Extension.
+(See the code in the example extension.)
=back
=head2 flag_end_of_update
-This happens at the end of L<Bugzilla::Flag/update_flags>, after all other changes
-are made to the database and after emails are sent. It gives you a before/after
-snapshot of flags so you can react to specific flag changes.
+This happens at the end of L<Bugzilla::Flag/update_flags>, after all other
+changes are made to the database and after emails are sent. It gives you a
+before/after snapshot of flags so you can react to specific flag changes.
This generally occurs inside a database transaction.
Note that the interface to this hook is B<UNSTABLE> and it may change in the
=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.
=over
-=item C<group> - The changed L<Bugzilla::Group> object, with all fields set
-to their updated values.
+=item C<group>
+
+The new L<Bugzilla::Group> object that was just created.
=back
=item C<silent>
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
This happens at the very end of all the tables being updated
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
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
-with any future Bugzilla tables.
+prefix the names of your tables with some word (preferably the name of
+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
in L</install_update_db>.
This hook is called right before the template is loaded, so that you can
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:
=over
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.
+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>
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
-a database transaction, so if the hook throws an error all previous
-changes will be rolled back including the creation of the new product.
+a database transaction, so if the hook throws an error, all previous
+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:
=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
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::>
-(replace C<yourextension> with the name of your extension). The C<package>
-declaration inside that module must also start with
-C<extensions::yourextension::lib::> in that module's code.
+The Perl module name will most likely start with C<Bugzilla::Extension::Foo::>
+(where "Foo" is the name of your extension).
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
name of your extension, so that you don't conflict with the standard Bugzilla
projects / thirdparty / bugzilla.git / commitdiff
