From 7241b44ffeb389bc82b650f52e0befb383627009 Mon Sep 17 00:00:00 2001 From: "myk%mozilla.org" <> Date: Fri, 4 Apr 2008 11:47:41 +0000 Subject: improved readability (for both readers and editors); added docbook tags for variables, literals, and inline code; corrected a few errors, regressions, and typos; and added section explaining applicability of hooks for installation customizers --- docs/en/xml/customization.xml | 180 +++++++++++++++++++++++------------------- 1 file changed, 98 insertions(+), 82 deletions(-) (limited to 'docs') diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml index a9005665e..86cbacd8f 100644 --- a/docs/en/xml/customization.xml +++ b/docs/en/xml/customization.xml @@ -295,7 +295,7 @@ After untarring the localizations (or creating your own) in the - $BUGZILLA_HOME/template directory, + BUGZILLA_ROOT/template directory, you must update the parameter to contain any localizations you'd like to permit. You may also wish to set the parameter to something other than @@ -309,73 +309,73 @@ Template Hooks - Template hooks are a way for customisers or Bugzilla extensions to insert - code into the standard Bugzilla templates without modifying them. - The hooks mechanism defines an API for extending the - standard templates with a clean separation of code. - This makes the changes less tied to specific versions of - Bugzilla, and reduces merge conflicts, making - upgrading a modified Bugzilla installation easier. + Template hooks are a way for extensions to Bugzilla to insert code + into the standard Bugzilla templates without modifying the template files + themselves. The hooks mechanism defines a consistent API for extending + the standard templates 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. - A template hook is just an named place in a standard template file. - When Bugzilla reaches this position, it checks whether there are any - extension template files for that hook. If so, it processes them. Each - hook has a directory of its own in the Bugzilla template directory tree. - Hooking a template file on to a specific hook is as - simple as putting the file into that hook's directory. + A template hook is just a named place in a standard template file + where extension template files for that hook get processed. Each hook + has a corresponding directory in the Bugzilla directory tree. Hooking an + extension template to a hook is as simple as putting the extension file + into the hook's directory. When Bugzilla processes the standard template + and reaches the hook, it will process all extension templates in the + hook's directory. The hooks themselves can be added into any standard + template upon request by extension authors. - To use hooks to extend a Bugzilla template, first make sure there is a - hook at the appropriate place within the template you want to extend. - Hooks appear in the default Bugzilla templates as a single template - directive in the format - [% Hook.process("<name>") %], where - <name> - is the unique (within that template) name of the hook. + To use hooks to extend a Bugzilla template, first make sure there is + a hook at the appropriate place within the template you want to extend. + Hooks appear in the standard Bugzilla templates as a single directive + in the format + [% Hook.process("name") %], + where name is the unique (within that template) + name of the hook. - If you aren't sure which template 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 browse the directory tree in - $BUGZILLA_HOME/template/en/extension/hook/, - which contains a directory for each hook. Each hook's directory - is located as follows: + If you aren't sure which template 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 browse + the directory tree in + BUGZILLA_ROOT/template/en/extension/hook/, + which contains a directory for each hook in the following location: - $BUGZILLA_HOME/template/en/extension/hook/<path-to-standard-template>/<standard-template-name>/<hook-name>/ + BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/ - If there is no hook in the appropriate place within the Bugzilla - template you want to extend, - file + If there is no hook at the appropriate place within the Bugzilla template + you want to extend, + file a bug requesting one, specifying: the template for which you are requesting a hook; - - where in the template you would like the hook to be placed (line - number/position for latest version of template in CVS or description of - location); + where in the template you would like the hook to be placed + (line number/position for latest version of template 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 and check the new version into CVS, and add the - corresponding directory to - $BUGZILLA_HOME/template/en/extension/hook/. + The Bugzilla reviewers will promptly review each hook request, + name the hook, add it to the template, check the new version + of the template into CVS, and create the corresponding directory in + BUGZILLA_ROOT/template/en/extension/hook/. @@ -396,8 +396,8 @@ - That's it! Now, when the standard template containing the hook is - processed, your extension template will be processed at the point + That's it! Now, when the standard template containing the hook + is processed, your extension template will be processed at the point where the hook appears. @@ -405,44 +405,44 @@ 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. + 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 + useful-links.html.tmpl, which is located in + the global/ subdirectory on the standard Bugzilla template path - $BUGZILLA_HOME/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: + 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: - ... - [% ', <a href="editkeywords.cgi">keywords</a>' + keywords' IF user.groups.editkeywords %] [% Hook.process("edit") %] -... +...]]> The corresponding directory for this hook is - $BUGZILLA_HOME/template/en/extension/hook/global/useful-links.html.tmpl/edit/. + BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/. - You put a template named + You put a template named projman-edit-projects.html.tmpl into that directory with the following content: - [% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %] + projects' IF user.groups.projman_admins %]]]> Voila! The link now appears after the other administration links in the - navigation bar for users in the projman_admins group. + navigation bar for users in the projman_admins group. @@ -452,26 +452,24 @@ - You may want to prefix your extension templates names with - the name of your extension, e.g. - projman-foo.html.tmpl, - so there is no chance of a conflict with the names of - templates installed by other extensions. + You may want to prefix your extension template names + with the name of your extension, e.g. + projman-foo.html.tmpl, + so they do not conflict with the names of templates installed by + other extensions. If your extension includes entirely new templates in addition to - extensions of standard templates, it should install those new templates - into an extension-specific subdirectory of the - $BUGZILLA_HOME/template/en/extension/ - directory. - The extension/ directory, like the - default/ - and custom/ directories, is part of the template - search path, so putting templates there enables them to be found by - the template processor. + extensions of standard templates, it should install those new + templates into an extension-specific subdirectory of the + BUGZILLA_ROOT/template/en/extension/ + directory. The extension/ directory, like the + default/ and custom/ + directories, is part of the template search path, so putting templates + there enables them to be found by the template processor. @@ -479,18 +477,36 @@ custom/ directory (i.e. templates added by the specific installation), then in the extension/ directory (i.e. templates added by extensions), and finally in the - default/ directory, for the standard Bugzilla - templates. - Thus extension templates can override standard templates, but - installation-specific templates override both. + default/ directory (i.e. the standard Bugzilla + templates). Thus extension templates can override standard templates, + but installation-specific templates override both. + + + + Note that overriding standard templates with extension templates + gives you great power but also makes upgrading an installation harder. + As with custom templates, we recommend using this functionality + sparingly and only when absolutely necessary. + + + + + + Installation customizers can also take advantage of hooks when adding + code to a Bugzilla template. To do so, create directories in + BUGZILLA_ROOT/template/en/custom/hook/ + equivalent to the directories in + BUGZILLA_ROOT/template/en/extension/hook/ + for the hooks you want to use, then place your customization templates + into those directories. - Note that overriding standard templates gives you great power but - also makes - upgrading an installation harder. As with custom templates, we - recommend using this functionality sparingly and only when absolutely - necessary. + Obviously this method of customizing Bugzilla only lets you add code + to the standard 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. -- cgit v1.2.3-24-g4f1b