diff options
Diffstat (limited to 'Bugzilla/Extension.pm')
| -rw-r--r-- | Bugzilla/Extension.pm | 78 |
1 files changed, 39 insertions, 39 deletions
diff --git a/Bugzilla/Extension.pm b/Bugzilla/Extension.pm index e7f398784..7e53d87f3 100644 --- a/Bugzilla/Extension.pm +++ b/Bugzilla/Extension.pm @@ -74,7 +74,7 @@ sub load { my ($class, $extension_file, $config_file) = @_; my $package; - # This is needed during checksetup.pl, because Extension packages can + # This is needed during checksetup.pl, because Extension packages can # only be loaded once (they return "1" the second time they're loaded, # instead of their name). During checksetup.pl, extensions are loaded # once by Bugzilla::Install::Requirements, and then later again via @@ -89,7 +89,7 @@ sub load { my $name = require $config_file; if ($name =~ /^\d+$/) { ThrowCodeError('extension_must_return_name', - { extension => $config_file, + { extension => $config_file, returned => $name }); } $package = "${class}::$name"; @@ -102,7 +102,7 @@ sub load { else { my $name = require $extension_file; if ($name =~ /^\d+$/) { - ThrowCodeError('extension_must_return_name', + ThrowCodeError('extension_must_return_name', { extension => $extension_file, returned => $name }); } $package = "${class}::$name"; @@ -124,7 +124,7 @@ sub _validate_package { } if (!eval { $package->NAME }) { - ThrowCodeError('extension_no_name', + ThrowCodeError('extension_no_name', { filename => $extension_file, package => $package }); } @@ -183,7 +183,7 @@ Bugzilla::Extension - Base class for Bugzilla Extensions. =head1 SYNOPSIS -The following would be in F<extensions/Foo/Extension.pm> or +The following would be in F<extensions/Foo/Extension.pm> or F<extensions/Foo.pm>: package Bugzilla::Extension::Foo @@ -198,7 +198,7 @@ F<extensions/Foo.pm>: __PACKAGE__->NAME; Custom templates would go into F<extensions/Foo/template/en/default/>. -L<Template hooks|/Template Hooks> would go into +L<Template hooks|/Template Hooks> would go into F<extensions/Foo/template/en/default/hook/>. =head1 DESCRIPTION @@ -209,7 +209,7 @@ This is the base class for all Bugzilla extensions. The L</SYNOPSIS> above gives a pretty good overview of what's basically required to write an extension. This section gives more information -on exactly how extensions work and how you write them. There is also a +on exactly how extensions work and how you write them. There is also a L<wiki page|https://wiki.mozilla.org/Bugzilla:Extension_Notes> with additional HOWTOs, tips and tricks. =head2 Using F<extensions/create.pl> @@ -243,7 +243,7 @@ There are two ways to write extensions: =item 1 If your extension will have only code and no templates or other files, -you can create a simple C<.pm> file in the F<extensions/> directory. +you can create a simple C<.pm> file in the F<extensions/> directory. For example, if you wanted to create an extension called "Foo" using this method, you would put your code into a file called F<extensions/Foo.pm>. @@ -318,13 +318,13 @@ described in the L</Where Extension Code Goes> section above. During your subroutine, you may want to know what values were passed as CGI arguments to the current script, or what arguments were passed to -the current WebService method. You can get that data via +the current WebService method. You can get that data via L<Bugzilla/input_params>. =head3 Adding New Hooks To Bugzilla If you need a new hook for your extension and you want that hook to be -added to Bugzilla itself, see our development process at +added to Bugzilla itself, see our development process at L<http://wiki.mozilla.org/Bugzilla:Developers>. In order for a new hook to be accepted into Bugzilla, it has to work, @@ -350,7 +350,7 @@ L<Bugzilla::Install::Requirements/REQUIRED_MODULES>. If there are optional modules that add additional functionality to your application, you can specify them in a constant called OPTIONAL_MODULES, -which has the same format as +which has the same format as L<Bugzilla::Install::Requirements/OPTIONAL_MODULES>. =head3 If Your Extension Needs Certain Modules In Order To Compile @@ -385,11 +385,11 @@ named C<Foo>: Note that it is I<not> a subclass of C<Bugzilla::Extension>, because at the time that module requirements are being checked in L<checksetup>, C<Bugzilla::Extension> cannot be loaded. Also, just like F<Extension.pm>, -it ends with C<< __PACKAGE__->NAME; >>. Note also that it has the +it ends with C<< __PACKAGE__->NAME; >>. Note also that it has the B<exact same> C<package> name as F<Extension.pm>. This file may not use any Perl modules other than L<Bugzilla::Constants>, -L<Bugzilla::Install::Util>, L<Bugzilla::Install::Requirements>, and +L<Bugzilla::Install::Util>, L<Bugzilla::Install::Requirements>, and modules that ship with Perl itself. If you want to define both C<REQUIRED_MODULES> and C<OPTIONAL_MODULES>, @@ -401,7 +401,7 @@ will have access to everything in F<Config.pm>. Don't define anything with an identical name in both files, or Perl may throw a warning that you are redefining things. -This method of setting C<REQUIRED_MODULES> is of course not available if +This method of setting C<REQUIRED_MODULES> is of course not available if your extension is a single file named C<Foo.pm>. If any of this is confusing, just look at the code of the Example extension. @@ -410,7 +410,7 @@ It uses this method to specify requirements. =head2 Libraries Extensions often want to have their own Perl modules. Your extension -can load any Perl module in its F<lib/> directory. (So, if your extension is +can load any Perl module in its F<lib/> directory. (So, if your extension is F<extensions/Foo/>, then your Perl modules go into F<extensions/Foo/lib/>.) However, the C<package> name of your libraries will not work quite @@ -421,12 +421,12 @@ which should have C<package Bugzilla::Extension::Foo::Bar;> as its package name. This allows any place in Bugzilla to load your modules, which is important -for some hooks. It even allows other extensions to load your modules, and +for some hooks. It even allows other extensions to load your modules, and allows you to install your modules into the global Perl install as F<Bugzilla/Extension/Foo/Bar.pm>, if you'd like, which helps allow CPAN distribution of Bugzilla extensions. -B<Note:> If you want to C<use> or C<require> a module that's in +B<Note:> If you want to C<use> or C<require> a module that's in F<extensions/Foo/lib/> at the top level of your F<Extension.pm>, you must have a F<Config.pm> (see above) with at least the C<NAME> constant defined in it. @@ -462,13 +462,13 @@ interface of Bugzilla. =head3 Which Templates Can Be Hooked There is no list of template hooks like there is for standard code hooks. -To find what places in the user interface can be hooked, search for the -string C<Hook.process> in Bugzilla's templates (in the -F<template/en/default/> directory). That will also give you the name of +To find what places in the user interface can be hooked, search for the +string C<Hook.process> in Bugzilla's templates (in the +F<template/en/default/> directory). That will also give you the name of the hooks--the first argument to C<Hook.process> is the name of the hook. (A later section in this document explains how to use that name). -For example, if you see C<Hook.process("additional_header")>, that means +For example, if you see C<Hook.process("additional_header")>, that means the name of the hook is C<additional_header>. =head3 Where Template Hooks Go @@ -485,10 +485,10 @@ intended to distribute.) The files that go into this directory have a certain name, based on the name of the template that is being hooked, and the name of the hook. For example, let's imagine that you have an extension named "Foo", -and you want to use the C<additional_header> hook in +and you want to use the C<additional_header> hook in F<template/en/default/global/header.html.tmpl>. Your code would go into -F<extensions/Foo/template/en/default/hook/global/header-additional_header.html.tmpl>. Any code you put into that file will happen at the point that -C<Hook.process("additional_header")> is called in +F<extensions/Foo/template/en/default/hook/global/header-additional_header.html.tmpl>. Any code you put into that file will happen at the point that +C<Hook.process("additional_header")> is called in F<template/en/default/global/header.html.tmpl>. As you can see, template extension file names follow a pattern. The @@ -500,7 +500,7 @@ pattern looks like: =item <templates> -This is the full path to the template directory, like +This is the full path to the template directory, like F<extensions/Foo/template/en/default>. This works much like normal templates do, in the sense that template extensions in C<custom> override template extensions in C<default> for your extension, templates for different languages @@ -512,13 +512,13 @@ will be run for I<every> extension, whereas for normal templates, Bugzilla just takes the first one it finds and stops searching. So while a template extension in the C<custom> directory may override the same-named template extension in the C<default> directory I<within your Bugzilla extension>, -it will not override the same-named template extension in the C<default> +it will not override the same-named template extension in the C<default> directory of another Bugzilla extension. =item <template path> -This is the part of the path (excluding the filename) that comes after -F<template/en/default/> in a template's path. So, for +This is the part of the path (excluding the filename) that comes after +F<template/en/default/> in a template's path. So, for F<template/en/default/global/header.html.tmpl>, this would simply be C<global>. @@ -531,7 +531,7 @@ C<header>. =item <hook name> This is the name of the hook--what you saw in C<Hook.process> inside -of the template you want to hook. In our example, this is +of the template you want to hook. In our example, this is C<additional_header>. =item <template type> @@ -545,7 +545,7 @@ type of output the template has. =head3 Adding New Template Hooks to Bugzilla -Adding new template hooks is just like adding code hooks (see +Adding new template hooks is just like adding code hooks (see L</Adding New Hooks To Bugzilla>) except that you don't have to document them, and including example code is optional. @@ -556,11 +556,11 @@ it entirely with your extension's template, or you want to add an entirely new template to Bugzilla for your extension to use. To replace the F<template/en/default/global/banner.html.tmpl> template -in an extension named "Foo", create a file called +in an extension named "Foo", create a file called F<extensions/Foo/template/en/default/global/banner.html.tmpl>. Note that this is very similar to the path for a template hook, except that it excludes F<hook/>, and the template is named I<exactly> like the standard Bugzilla -template. +template. You can also use this method to add entirely new templates. If you have an extension named "Foo", and you add a file named @@ -592,10 +592,10 @@ other pages that other extensions might add. If you include CSS, JavaScript, and images in your extension that are served directly to the user (that is, they're not read by a script and then printed--they're just linked directly in your HTML), they should go -into the F<web/> subdirectory of your extension. +into the F<web/> subdirectory of your extension. So, for example, if you had a CSS file called F<style.css> and your -extension was called F<Foo>, your file would go into +extension was called F<Foo>, your file would go into F<extensions/Foo/web/style.css>. =head2 Disabling Your Extension @@ -617,13 +617,13 @@ return C<0> or some false value. If you've made an extension and you want to publish it, the first thing you'll want to do is package up your extension's code and -then put a link to it in the appropriate section of +then put a link to it in the appropriate section of L<http://wiki.mozilla.org/Bugzilla:Addons>. =head2 Distributing on CPAN If you want a centralized distribution point that makes it easy -for Bugzilla users to install your extension, it is possible to +for Bugzilla users to install your extension, it is possible to distribute your Bugzilla Extension through CPAN. The details of making a standard CPAN module are too much to @@ -631,7 +631,7 @@ go into here, but a lot of it is covered in L<perlmodlib> and on L<http://www.cpan.org/> among other places. When you distribute your extension via CPAN, your F<Extension.pm> -should simply install itself as F<Bugzilla/Extension/Foo.pm>, +should simply install itself as F<Bugzilla/Extension/Foo.pm>, where C<Foo> is the name of your module. You do not need a separate F<Config.pm> file, because CPAN itself will handle installing the prerequisites of your module, so Bugzilla doesn't have to @@ -705,9 +705,9 @@ by Bugzilla, and C<0> otherwise. =head3 C<package_dir> -This returns the directory that your extension is located in. +This returns the directory that your extension is located in. -If this is an extension that was installed via CPAN, the directory will +If this is an extension that was installed via CPAN, the directory will be the path to F<Bugzilla/Extension/Foo/>, if C<Foo.pm> is the name of your extension. |