From 8ab64629d3a091a0ccb6af52c48ee7bb9fd8834d Mon Sep 17 00:00:00 2001 From: "lpsolit%gmail.com" <> Date: Fri, 4 Apr 2008 00:05:36 +0000 Subject: Bug 182975: Bugzilla directory structure to be adopted to l10n needs - Patch by A.A. Shimono (himorin) r=LpSolit r=mkanat a=LpSolit --- docs/en/xml/customization.xml | 820 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 820 insertions(+) create mode 100644 docs/en/xml/customization.xml (limited to 'docs/en/xml/customization.xml') diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml new file mode 100644 index 000000000..bb89cb12b --- /dev/null +++ b/docs/en/xml/customization.xml @@ -0,0 +1,820 @@ + + + Customizing Bugzilla + +
+ Custom Skins + + + Bugzilla allows you to have multiple skins. These are custom CSS and possibly + also custom images for Bugzilla. To create a new custom skin, you have two + choices: + + + + Make a single CSS file, and put it in the + skins/contrib directory. + + + + + Make a directory that contains all the same CSS file + names as skins/standard/, and put + your directory in skins/contrib/. + + + + + + + After you put the file or the directory there, make sure to run checksetup.pl + so that it can reset the file permissions correctly. + + + After you have installed the new skin, it will show up as an option in the + user's General Preferences. If you would like to force a particular skin on all + users, just select it in the Default Preferences and then uncheck "Enabled" on + the preference. + +
+ +
+ Template Customization + + + Administrators can configure the look and feel of Bugzilla without + having to edit Perl files or face the nightmare of massive merge + conflicts when they upgrade to a newer version in the future. + + + + Templatization also makes localized versions of Bugzilla possible, + for the first time. It's possible to have Bugzilla's UI language + determined by the user's browser. More information is available in + . + + +
+ Template Directory Structure + + The template directory structure starts with top level directory + named template, which contains a directory + for each installed localization. The next level defines the + language used in the templates. Bugzilla comes with English + templates, so the directory name is en, + and we will discuss template/en throughout + the documentation. Below template/en is the + default directory, which contains all the + standard templates shipped with Bugzilla. + + + + + A directory data/templates also exists; + this is where Template Toolkit puts the compiled versions of + the templates from either the default or custom directories. + Do not directly edit the files in this + directory, or all your changes will be lost the next time + Template Toolkit recompiles the templates. + + +
+ +
+ Choosing a Customization Method + + If you want to edit Bugzilla's templates, the first decision + you must make is how you want to go about doing so. There are two + choices, and which you use depends mainly on the scope of your + modifications, and the method you plan to use to upgrade Bugzilla. + + + + The first method of making customizations is to directly edit the + templates found in template/en/default. + This is probably the best way to go about it if you are going to + be upgrading Bugzilla through CVS, because if you then execute + a cvs update, any changes you have made will + be merged automagically with the updated versions. + + + + + If you use this method, and CVS conflicts occur during an + update, the conflicted templates (and possibly other parts + of your installation) will not work until they are resolved. + + + + + The second method is to copy the templates to be modified + into a mirrored directory structure under + template/en/custom. Templates in this + directory structure automatically override any identically-named + and identically-located templates in the + default directory. + + + + + The custom directory does not exist + at first and must be created if you want to use it. + + + + + The second method of customization should be used if you + use the overwriting method of upgrade, because otherwise + your changes will be lost. This method may also be better if + you are using the CVS method of upgrading and are going to make major + changes, because it is guaranteed that the contents of this directory + will not be touched during an upgrade, and you can then decide whether + to continue using your own templates, or make the effort to merge your + changes into the new versions by hand. + + + + Using this method, your installation may break if incompatible + changes are made to the template interface. Such changes should + be documented in the release notes, provided you are using a + stable release of Bugzilla. If you use using unstable code, you will + need to deal with this one yourself, although if possible the changes + will be mentioned before they occur in the deprecations section of the + previous stable release's release notes. + + + + + Regardless of which method you choose, it is recommended that + you run ./checksetup.pl after creating or + editing any templates in the template/en/default + directory, and after editing any templates in the + custom directory. + + + + + + It is required that you run + ./checksetup.pl after creating a new + template in the custom directory. Failure + to do so will raise an incomprehensible error message. + + +
+ +
+ How To Edit Templates + + + + If you are making template changes that you intend on submitting back + for inclusion in standard Bugzilla, you should read the relevant + sections of the + Developers' + Guide. + + + + + The syntax of the Template Toolkit language is beyond the scope of + this guide. It's reasonably easy to pick up by looking at the current + templates; or, you can read the manual, available on the + Template Toolkit home + page. + + + + One thing you should take particular care about is the need + to properly HTML filter data that has been passed into the template. + This means that if the data can possibly contain special HTML characters + such as <, and the data was not intended to be HTML, they need to be + converted to entity form, i.e. &lt;. You use the 'html' filter in the + Template Toolkit to do this. If you forget, you may open up + your installation to cross-site scripting attacks. + + + + Also note that Bugzilla adds a few filters of its own, that are not + in standard Template Toolkit. In particular, the 'url_quote' filter + can convert characters that are illegal or have special meaning in URLs, + such as &, to the encoded form, i.e. %26. This actually encodes most + characters (but not the common ones such as letters and numbers and so + on), including the HTML-special characters, so there's never a need to + HTML filter afterwards. + + + + Editing templates is a good way of doing a poor man's custom + fields. + For example, if you don't use the Status Whiteboard, but want to have + a free-form text entry box for Build Identifier, + then you can just + edit the templates to change the field labels. It's still be called + status_whiteboard internally, but your users don't need to know that. + + +
+ + +
+ Template Formats and Types + + + Some CGI's have the ability to use more than one template. For example, + buglist.cgi can output itself as RDF, or as two + formats of HTML (complex and simple). The mechanism that provides this + feature is extensible. + + + + Bugzilla can support different types of output, which again can have + multiple formats. In order to request a certain type, you can append + the &ctype=<contenttype> (such as rdf or html) to the + <cginame>.cgi URL. If you would like to + retrieve a certain format, you can use the &format=<format> + (such as simple or complex) in the URL. + + + + To see if a CGI supports multiple output formats and types, grep the + CGI for get_format. If it's not present, adding + multiple format/type support isn't too hard - see how it's done in + other CGIs, e.g. config.cgi. + + + + To make a new format template for a CGI which supports this, + open a current template for + that CGI and take note of the INTERFACE comment (if present.) This + comment defines what variables are passed into this template. If + there isn't one, I'm afraid you'll have to read the template and + the code to find out what information you get. + + + + Write your template in whatever markup or text style is appropriate. + + + + You now need to decide what content type you want your template + served as. The content types are defined in the + Bugzilla/Constants.pm file in the + contenttypes + constant. If your content type is not there, add it. Remember + the three- or four-letter tag assigned to your content type. + This tag will be part of the template filename. + + + + + After adding or changing a content type, it's suitable to edit + Bugzilla/Constants.pm in order to reflect + the changes. Also, the file should be kept up to date after an + upgrade if content types have been customized in the past. + + + + + Save the template as <stubname>-<formatname>.<contenttypetag>.tmpl. + Try out the template by calling the CGI as + <cginame>.cgi?format=<formatname>&ctype=<type> . + +
+ + +
+ Particular Templates + + + There are a few templates you may be particularly interested in + customizing for your installation. + + + + index.html.tmpl: + This is the Bugzilla front page. + + + + global/header.html.tmpl: + This defines the header that goes on all Bugzilla pages. + The header includes the banner, which is what appears to users + and is probably what you want to edit instead. However the + header also includes the HTML HEAD section, so you could for + example add a stylesheet or META tag by editing the header. + + + + global/banner.html.tmpl: + This contains the banner, the part of the header + that appears + at the top of all Bugzilla pages. The default banner is reasonably + barren, so you'll probably want to customize this to give your + installation a distinctive look and feel. It is recommended you + preserve the Bugzilla version number in some form so the version + you are running can be determined, and users know what docs to read. + + + + global/footer.html.tmpl: + This defines the footer that goes on all Bugzilla pages. Editing + this is another way to quickly get a distinctive look and feel for + your Bugzilla installation. + + + + global/variables.none.tmpl: + This defines a list of terms that may be changed in order to + brand the Bugzilla instance In this way, terms + like bugs can be replaced with issues + across the whole Bugzilla installation. The name + Bugzilla and other words can be customized as well. + + + + list/table.html.tmpl: + This template controls the appearance of the bug lists created + by Bugzilla. Editing this template allows per-column control of + the width and title of a column, the maximum display length of + each entry, and the wrap behaviour of long entries. + For long bug lists, Bugzilla inserts a 'break' every 100 bugs by + default; this behaviour is also controlled by this template, and + that value can be modified here. + + + + bug/create/user-message.html.tmpl: + This is a message that appears near the top of the bug reporting page. + By modifying this, you can tell your users how they should report + bugs. + + + + bug/process/midair.html.tmpl: + This is the page used if two people submit simultaneous changes to the + same bug. The second person to submit their changes will get this page + to tell them what the first person did, and ask if they wish to + overwrite those changes or go back and revisit the bug. The default + title and header on this page read "Mid-air collision detected!" If + you work in the aviation industry, or other environment where this + might be found offensive (yes, we have true stories of this happening) + you'll want to change this to something more appropriate for your + environment. + + + + bug/create/create.html.tmpl and + bug/create/comment.txt.tmpl: + You may not wish to go to the effort of creating custom fields in + Bugzilla, yet you want to make sure that each bug report contains + a number of pieces of important information for which there is not + a special field. The bug entry system has been designed in an + extensible fashion to enable you to add arbitrary HTML widgets, + such as drop-down lists or textboxes, to the bug entry page + and have their values appear formatted in the initial comment. + A hidden field that indicates the format should be added inside + the form in order to make the template functional. Its value should + be the suffix of the template filename. For example, if the file + is called create-cust.html.tmpl, then + <input type="hidden" name="format" value="cust"> + should be used inside the form. + + + + An example of this is the mozilla.org + guided + bug submission form. The code for this comes with the Bugzilla + distribution as an example for you to copy. It can be found in the + files + create-guided.html.tmpl and + comment-guided.html.tmpl. + + + + So to use this feature, create a custom template for + enter_bug.cgi. The default template, on which you + could base it, is + custom/bug/create/create.html.tmpl. + Call it create-<formatname>.html.tmpl, and + in it, add widgets for each piece of information you'd like + collected - such as a build number, or set of steps to reproduce. + + + + Then, create a template like + custom/bug/create/comment.txt.tmpl, and call it + comment-<formatname>.txt.tmpl. This + template should reference the form fields you have created using + the syntax [% form.<fieldname> %]. When a + bug report is + submitted, the initial comment attached to the bug report will be + formatted according to the layout of this template. + + + + For example, if your custom enter_bug template had a field + <input type="text" name="buildid" size="30"> + and then your comment.txt.tmpl had + BuildID: [% form.buildid %] + then something like + BuildID: 20020303 + would appear in the initial comment. + +
+ + +
+ Configuring Bugzilla to Detect the User's Language + + Bugzilla honours the user's Accept: HTTP header. You can install + templates in other languages, and Bugzilla will pick the most appropriate + according to a priority order defined by you. Many + language templates can be obtained from . Instructions + for submitting new languages are also available from that location. + +
+ +
+ +
+ The Bugzilla Extension Mechanism + + + + Custom extensions require Template Toolkit version 2.12 or + above, or the application of a patch. See bug + 239112 for details. + + + + + 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.groups.editkeywords %] + [% Hook.process("edit") %] +...]]> + + + The corresponding extension file for this hook is + BUGZILLA_ROOT/extensions/projman/template/en/hook/global/useful-links-edit.html.tmpl. + You then create that template file and add the following constant: + + + 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. + + + + 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 + + + + This feature should be considered experimental; the Bugzilla code you + will be changing is not stable, and could change or move between + versions. Be aware that if you make modifications as outlined here, + you may have + to re-make them or port them if Bugzilla changes internally between + versions, and you upgrade. + + + + + Companies often have rules about which employees, or classes of employees, + are allowed to change certain things in the bug system. For example, + only the bug's designated QA Contact may be allowed to VERIFY the bug. + Bugzilla has been + designed to make it easy for you to write your own custom rules to define + who is allowed to make what sorts of value transition. + + + + By default, assignees, QA owners and users + with editbugs privileges can edit all fields of bugs, + except group restrictions (unless they are members of the groups they + are trying to change). Bug reporters also have the ability to edit some + fields, but in a more restrictive manner. Other users, without + editbugs privileges, can not edit + bugs, except to comment and add themselves to the CC list. + + + + For maximum flexibility, customizing this means editing Bugzilla's Perl + code. This gives the administrator complete control over exactly who is + allowed to do what. The relevant method is called + check_can_change_field(), + and is found in Bug.pm in your + Bugzilla/ directory. If you open that file and search for + sub check_can_change_field, you'll find it. + + + + This function has been carefully commented to allow you to see exactly + how it works, and give you an idea of how to make changes to it. + Certain marked sections should not be changed - these are + the plumbing which makes the rest of the function work. + In between those sections, you'll find snippets of code like: + # Allow the assignee to change anything. + if ($ownerid eq $whoid) { + return 1; + } + It's fairly obvious what this piece of code does. + + + + So, how does one go about changing this function? Well, simple changes + can be made just by removing pieces - for example, if you wanted to + prevent any user adding a comment to a bug, just remove the lines marked + Allow anyone to change comments. If you don't want the + Reporter to have any special rights on bugs they have filed, just + remove the entire section that deals with the Reporter. + + + + More complex customizations are not much harder. Basically, you add + a check in the right place in the function, i.e. after all the variables + you are using have been set up. So, don't look at $ownerid before + $ownerid has been obtained from the database. You can either add a + positive check, which returns 1 (allow) if certain conditions are true, + or a negative check, which returns 0 (deny.) E.g.: + if ($field eq "qacontact") { + if (Bugzilla->user->groups("quality_assurance")) { + return 1; + } + else { + return 0; + } + } + This says that only users in the group "quality_assurance" can change + the QA Contact field of a bug. + + + + Getting more weird: + user->email =~ /.*\@example\.com$/)) + { + if ($oldvalue eq "P1") { + return 1; + } + else { + return 0; + } + }]]> + This says that if the user is trying to change the priority field, + and their email address is @example.com, they can only do so if the + old value of the field was "P1". Not very useful, but illustrative. + + + + + If you are modifying process_bug.cgi in any + way, do not change the code that is bounded by DO_NOT_CHANGE blocks. + Doing so could compromise security, or cause your installation to + stop working entirely. + + + + + For a list of possible field names, look at the bugs table in the + database. If you need help writing custom rules for your organization, + ask in the newsgroup. + +
+ + + &integration; + + + + + -- cgit v1.2.3-24-g4f1b