From 28b4f5b847102e54eae8ce729cf68ed5e4e3ba02 Mon Sep 17 00:00:00 2001 From: "mkanat%bugzilla.org" <> Date: Sat, 12 Dec 2009 22:20:09 +0000 Subject: Bug 233398: Update the customization docs to point to the Extensions system POD instead of having docs about template hooks in the Guide. Patch by Max Kanat-Alexander r=LpSolit, a=LpSolit --- docs/en/xml/customization.xml | 256 ++++-------------------------------------- 1 file changed, 19 insertions(+), 237 deletions(-) (limited to 'docs') diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml index 24b1d4403..f397cff53 100644 --- a/docs/en/xml/customization.xml +++ b/docs/en/xml/customization.xml @@ -2,6 +2,23 @@ Customizing Bugzilla +
+ Bugzilla Extensions + + + One of the best ways to customize Bugzilla is by writing a Bugzilla + Extension. Bugzilla Extensions let you modify both the code and + UI of Bugzilla in a way that can be distributed to other Bugzilla + users and ported forward to future versions of Bugzilla with minimal + effort. + + + + See the Bugzilla Extension + documentation for information on how to write an Extension. + +
+
Custom Skins @@ -438,241 +455,6 @@
-
- The Bugzilla Extension Mechanism - - - - Note that the below paths are inconsistent and confusing. They will - likely be changed in Bugzilla 4.0. - - - - - Extensions are a way for extensions to Bugzilla to insert code - into the standard Bugzilla templates and source files - without modifying these files themselves. The extension mechanism - defines a consistent API for extending the standard templates and source files - in a way that cleanly separates standard code from extension code. - Hooks reduce merge conflicts and make it easier to write extensions that work - across multiple versions of Bugzilla, making upgrading a Bugzilla installation - with installed extensions easier. Furthermore, they make it easy to install - and remove extensions as each extension is nothing more than a - simple directory structure. - - - - There are two main types of hooks: code hooks and template hooks. Code - hooks allow extensions to invoke code at specific points in various - source files, while template hooks allow extensions to add elements to - the Bugzilla user interface. - - - - A hook is just a named place in a standard source or template file - where extension source code or template files for that hook get processed. - Each extension has a corresponding directory in the Bugzilla directory - tree (BUGZILLA_ROOT/extensions/extension_name). Hooking - an extension source file or template to a hook is as simple as putting - the extension file into extension's template or code directory. - When Bugzilla processes the source file or template and reaches the hook, - it will process all extension files in the hook's directory. - The hooks themselves can be added into any source file or standard template - upon request by extension authors. - - - - To use hooks to extend Bugzilla, first make sure there is - a hook at the appropriate place within the source file or template you - want to extend. The exact appearance of a hook depends on if the hook - is a code hook or a template hook. - - - - Code hooks appear in Bugzilla source files as a single method call - in the format Bugzilla::Hook->process("name");. - For instance, enter_bug.cgi may invoke the hook - "enter_bug-entrydefaultvars". Thus, a source file at - BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl - will be automatically invoked when the code hook is reached. - - - - Template hooks appear in the standard Bugzilla templates as a - single directive in the format - [% Hook.process("name") %], - where name is the unique name of the hook. - - - - If you aren't sure what you want to extend or just want to browse the - available hooks, either use your favorite multi-file search - tool (e.g. grep) to search the standard templates - for occurrences of Hook.process or the source - files for occurrences of Bugzilla::Hook::process. - - - - If there is no hook at the appropriate place within the Bugzilla - source file or template you want to extend, - file - a bug requesting one, specifying: - - - - the source or template file for which you are - requesting a hook; - - where in the file you would like the hook to be placed - (line number/position for latest version of the file in CVS - or description of location); - - the purpose of the hook; - a link to information about your extension, if any. - - - - The Bugzilla reviewers will promptly review each hook request, - name the hook, add it to the template or source file, and check - the new version of the template into CVS. - - - - You may optionally attach a patch to the bug which implements the hook - and check it in yourself after receiving approval from a Bugzilla - reviewer. The developers may suggest changes to the location of the - hook based on their analysis of your needs or so the hook can satisfy - the needs of multiple extensions, but the process of getting hooks - approved and checked in is not as stringent as the process for general - changes to Bugzilla, and any extension, whether released or still in - development, can have hooks added to meet their needs. - - - - After making sure the hook you need exists (or getting it added if not), - add your extension to the directory within the Bugzilla - extensions tree corresponding to the hook. - - - - That's it! Now, when the source file or template containing the hook - is processed, your extension file will be processed at the point - where the hook appears. - - - - For example, let's say you have an extension named Projman that adds - project management capabilities to Bugzilla. Projman has an - administration interface edit-projects.cgi, - and you want to add a link to it into the navigation bar at the bottom - of every Bugzilla page for those users who are authorized - to administer projects. - - - - The navigation bar is generated by the template file - useful-links.html.tmpl, which is located in - the global/ subdirectory on the standard Bugzilla - template path - BUGZILLA_ROOT/template/en/default/. - Looking in useful-links.html.tmpl, you find - the following hook at the end of the list of standard Bugzilla - administration links: - - - keywords' - IF user.in_group('editkeywords') %] - [% Hook.process("edit") %] -...]]> - - - The corresponding extension file for this hook is - BUGZILLA_ROOT/extensions/projman/template/en/global/useful-links-edit.html.tmpl. - You then create that template file and add the following constant: - - - projects' IF user.in_group('projman_admins') %]]]> - - - Voila! The link now appears after the other administration links in the - navigation bar for users in the projman_admins group. - - - - Now, let us say your extension adds a custom "project_manager" field - to enter_bug.cgi. You want to modify the CGI script to set the default - project manager to be productname@company.com. Looking at - enter_bug.cgi, you see the enter_bug-entrydefaultvars - hook near the bottom of the file before the default form values are set. - The corresponding extension source file for this hook is located at - BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl. - You then create that file and add the following: - - - $default{'project_manager'} = $product.'@company.com'; - - - This code will be invoked whenever enter_bug.cgi is executed. - Assuming that the rest of the customization was completed (e.g. the - custom field was added to the enter_bug template and the required hooks - were used in process_bug.cgi), the new field will now have this - default value. - - - - Notes: - - - - - - If your extension includes entirely new templates in addition to - extensions of standard templates, it should store those new - templates in its - BUGZILLA_ROOT/extensions/template/en/ - directory. Extension template directories, like the - default/ and custom/ - directories, are part of the template search path, so putting templates - there enables them to be found by the template processor. - - - - The template processor looks for templates first in the - custom/ directory (i.e. templates added by the - specific installation), then in the extensions/ - directory (i.e. templates added by extensions), and finally in the - default/ directory (i.e. the standard Bugzilla - templates). Thus, installation-specific templates override both - default and extension templates. - - - - - - If you are looking to customize Bugzilla, you can also take advantage - of template hooks. To do so, create a directory in - BUGZILLA_ROOT/template/en/custom/hook/ - that corresponds to the hook you wish to use, then place your - customization templates into those directories. For example, - if you wanted to use the hook "end" in - global/useful-links.html.tmpl, you would - create the directory BUGZILLA_ROOT/template/en/custom/hook/ - global/useful-links.html.tmpl/end/ and add your customization - template to this directory. - - - - Obviously this method of customizing Bugzilla only lets you add code - to the standard source files and templates; you cannot change the - existing code. Nevertheless, for those customizations that only add - code, this method can reduce conflicts when merging changes, - making upgrading your customized Bugzilla installation easier. - - - -
-
Customizing Who Can Change What @@ -795,8 +577,8 @@ Many utilities and applications can integrate with Bugzilla, - either on the client- or server-side. None of them is maintained - by the Bugzilla community, nor are they being tested during our + either on the client- or server-side. None of them are maintained + by the Bugzilla community, nor are they tested during our QA tests, so use them at your own risk. They are listed at . -- cgit v1.2.3-24-g4f1b