timothy@apple.com | f42518d | 2008-02-06 20:19:16 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <HTML |
| 3 | ><HEAD |
| 4 | ><TITLE |
| 5 | >Template Customization</TITLE |
| 6 | ><META |
| 7 | NAME="GENERATOR" |
| 8 | CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK |
| 9 | REL="HOME" |
| 10 | TITLE="The Bugzilla Guide - 2.20.1 |
| 11 | Release" |
| 12 | HREF="index.html"><LINK |
| 13 | REL="UP" |
| 14 | TITLE="Customising Bugzilla" |
| 15 | HREF="customization.html"><LINK |
| 16 | REL="PREVIOUS" |
| 17 | TITLE="Customising Bugzilla" |
| 18 | HREF="customization.html"><LINK |
| 19 | REL="NEXT" |
| 20 | TITLE="Template Hooks" |
| 21 | HREF="cust-hooks.html"></HEAD |
| 22 | ><BODY |
| 23 | CLASS="section" |
| 24 | BGCOLOR="#FFFFFF" |
| 25 | TEXT="#000000" |
| 26 | LINK="#0000FF" |
| 27 | VLINK="#840084" |
| 28 | ALINK="#0000FF" |
| 29 | ><DIV |
| 30 | CLASS="NAVHEADER" |
| 31 | ><TABLE |
| 32 | SUMMARY="Header navigation table" |
| 33 | WIDTH="100%" |
| 34 | BORDER="0" |
| 35 | CELLPADDING="0" |
| 36 | CELLSPACING="0" |
| 37 | ><TR |
| 38 | ><TH |
| 39 | COLSPAN="3" |
| 40 | ALIGN="center" |
| 41 | >The Bugzilla Guide - 2.20.1 |
| 42 | Release</TH |
| 43 | ></TR |
| 44 | ><TR |
| 45 | ><TD |
| 46 | WIDTH="10%" |
| 47 | ALIGN="left" |
| 48 | VALIGN="bottom" |
| 49 | ><A |
| 50 | HREF="customization.html" |
| 51 | ACCESSKEY="P" |
| 52 | >Prev</A |
| 53 | ></TD |
| 54 | ><TD |
| 55 | WIDTH="80%" |
| 56 | ALIGN="center" |
| 57 | VALIGN="bottom" |
| 58 | >Chapter 5. Customising Bugzilla</TD |
| 59 | ><TD |
| 60 | WIDTH="10%" |
| 61 | ALIGN="right" |
| 62 | VALIGN="bottom" |
| 63 | ><A |
| 64 | HREF="cust-hooks.html" |
| 65 | ACCESSKEY="N" |
| 66 | >Next</A |
| 67 | ></TD |
| 68 | ></TR |
| 69 | ></TABLE |
| 70 | ><HR |
| 71 | ALIGN="LEFT" |
| 72 | WIDTH="100%"></DIV |
| 73 | ><DIV |
| 74 | CLASS="section" |
| 75 | ><H1 |
| 76 | CLASS="section" |
| 77 | ><A |
| 78 | NAME="cust-templates" |
| 79 | >5.1. Template Customization</A |
| 80 | ></H1 |
| 81 | ><P |
| 82 | > Administrators can configure the look and feel of Bugzilla without |
| 83 | having to edit Perl files or face the nightmare of massive merge |
| 84 | conflicts when they upgrade to a newer version in the future. |
| 85 | </P |
| 86 | ><P |
| 87 | > Templatization also makes localized versions of Bugzilla possible, |
| 88 | for the first time. It's possible to have Bugzilla's UI language |
| 89 | determined by the user's browser. More information is available in |
| 90 | <A |
| 91 | HREF="cust-templates.html#template-http-accept" |
| 92 | >Section 5.1.6</A |
| 93 | >. |
| 94 | </P |
| 95 | ><DIV |
| 96 | CLASS="section" |
| 97 | ><H2 |
| 98 | CLASS="section" |
| 99 | ><A |
| 100 | NAME="template-directory" |
| 101 | >5.1.1. Template Directory Structure</A |
| 102 | ></H2 |
| 103 | ><P |
| 104 | > The template directory structure starts with top level directory |
| 105 | named <TT |
| 106 | CLASS="filename" |
| 107 | >template</TT |
| 108 | >, which contains a directory |
| 109 | for each installed localization. The next level defines the |
| 110 | language used in the templates. Bugzilla comes with English |
| 111 | templates, so the directory name is <TT |
| 112 | CLASS="filename" |
| 113 | >en</TT |
| 114 | >, |
| 115 | and we will discuss <TT |
| 116 | CLASS="filename" |
| 117 | >template/en</TT |
| 118 | > throughout |
| 119 | the documentation. Below <TT |
| 120 | CLASS="filename" |
| 121 | >template/en</TT |
| 122 | > is the |
| 123 | <TT |
| 124 | CLASS="filename" |
| 125 | >default</TT |
| 126 | > directory, which contains all the |
| 127 | standard templates shipped with Bugzilla. |
| 128 | </P |
| 129 | ><DIV |
| 130 | CLASS="warning" |
| 131 | ><P |
| 132 | ></P |
| 133 | ><TABLE |
| 134 | CLASS="warning" |
| 135 | WIDTH="100%" |
| 136 | BORDER="0" |
| 137 | ><TR |
| 138 | ><TD |
| 139 | WIDTH="25" |
| 140 | ALIGN="CENTER" |
| 141 | VALIGN="TOP" |
| 142 | ><IMG |
| 143 | SRC="../images/warning.gif" |
| 144 | HSPACE="5" |
| 145 | ALT="Warning"></TD |
| 146 | ><TD |
| 147 | ALIGN="LEFT" |
| 148 | VALIGN="TOP" |
| 149 | ><P |
| 150 | > A directory <TT |
| 151 | CLASS="filename" |
| 152 | >data/templates</TT |
| 153 | > also exists; |
| 154 | this is where Template Toolkit puts the compiled versions of |
| 155 | the templates from either the default or custom directories. |
| 156 | <EM |
| 157 | >Do not</EM |
| 158 | > directly edit the files in this |
| 159 | directory, or all your changes will be lost the next time |
| 160 | Template Toolkit recompiles the templates. |
| 161 | </P |
| 162 | ></TD |
| 163 | ></TR |
| 164 | ></TABLE |
| 165 | ></DIV |
| 166 | ></DIV |
| 167 | ><DIV |
| 168 | CLASS="section" |
| 169 | ><H2 |
| 170 | CLASS="section" |
| 171 | ><A |
| 172 | NAME="template-method" |
| 173 | >5.1.2. Choosing a Customization Method</A |
| 174 | ></H2 |
| 175 | ><P |
| 176 | > If you want to edit Bugzilla's templates, the first decision |
| 177 | you must make is how you want to go about doing so. There are two |
| 178 | choices, and which you use depends mainly on the scope of your |
| 179 | modifications, and the method you plan to use to upgrade Bugzilla. |
| 180 | </P |
| 181 | ><P |
| 182 | > The first method of making customizations is to directly edit the |
| 183 | templates found in <TT |
| 184 | CLASS="filename" |
| 185 | >template/en/default</TT |
| 186 | >. |
| 187 | This is probably the best way to go about it if you are going to |
| 188 | be upgrading Bugzilla through CVS, because if you then execute |
| 189 | a <B |
| 190 | CLASS="command" |
| 191 | >cvs update</B |
| 192 | >, any changes you have made will |
| 193 | be merged automagically with the updated versions. |
| 194 | </P |
| 195 | ><DIV |
| 196 | CLASS="note" |
| 197 | ><P |
| 198 | ></P |
| 199 | ><TABLE |
| 200 | CLASS="note" |
| 201 | WIDTH="100%" |
| 202 | BORDER="0" |
| 203 | ><TR |
| 204 | ><TD |
| 205 | WIDTH="25" |
| 206 | ALIGN="CENTER" |
| 207 | VALIGN="TOP" |
| 208 | ><IMG |
| 209 | SRC="../images/note.gif" |
| 210 | HSPACE="5" |
| 211 | ALT="Note"></TD |
| 212 | ><TD |
| 213 | ALIGN="LEFT" |
| 214 | VALIGN="TOP" |
| 215 | ><P |
| 216 | > If you use this method, and CVS conflicts occur during an |
| 217 | update, the conflicted templates (and possibly other parts |
| 218 | of your installation) will not work until they are resolved. |
| 219 | </P |
| 220 | ></TD |
| 221 | ></TR |
| 222 | ></TABLE |
| 223 | ></DIV |
| 224 | ><P |
| 225 | > The second method is to copy the templates to be modified |
| 226 | into a mirrored directory structure under |
| 227 | <TT |
| 228 | CLASS="filename" |
| 229 | >template/en/custom</TT |
| 230 | >. Templates in this |
| 231 | directory structure automatically override any identically-named |
| 232 | and identically-located templates in the |
| 233 | <TT |
| 234 | CLASS="filename" |
| 235 | >default</TT |
| 236 | > directory. |
| 237 | </P |
| 238 | ><DIV |
| 239 | CLASS="note" |
| 240 | ><P |
| 241 | ></P |
| 242 | ><TABLE |
| 243 | CLASS="note" |
| 244 | WIDTH="100%" |
| 245 | BORDER="0" |
| 246 | ><TR |
| 247 | ><TD |
| 248 | WIDTH="25" |
| 249 | ALIGN="CENTER" |
| 250 | VALIGN="TOP" |
| 251 | ><IMG |
| 252 | SRC="../images/note.gif" |
| 253 | HSPACE="5" |
| 254 | ALT="Note"></TD |
| 255 | ><TD |
| 256 | ALIGN="LEFT" |
| 257 | VALIGN="TOP" |
| 258 | ><P |
| 259 | > The <TT |
| 260 | CLASS="filename" |
| 261 | >custom</TT |
| 262 | > directory does not exist |
| 263 | at first and must be created if you want to use it. |
| 264 | </P |
| 265 | ></TD |
| 266 | ></TR |
| 267 | ></TABLE |
| 268 | ></DIV |
| 269 | ><P |
| 270 | > The second method of customization should be used if you |
| 271 | use the overwriting method of upgrade, because otherwise |
| 272 | your changes will be lost. This method may also be better if |
| 273 | you are using the CVS method of upgrading and are going to make major |
| 274 | changes, because it is guaranteed that the contents of this directory |
| 275 | will not be touched during an upgrade, and you can then decide whether |
| 276 | to continue using your own templates, or make the effort to merge your |
| 277 | changes into the new versions by hand. |
| 278 | </P |
| 279 | ><P |
| 280 | > Using this method, your installation may break if incompatible |
| 281 | changes are made to the template interface. Such changes should |
| 282 | be documented in the release notes, provided you are using a |
| 283 | stable release of Bugzilla. If you use using unstable code, you will |
| 284 | need to deal with this one yourself, although if possible the changes |
| 285 | will be mentioned before they occur in the deprecations section of the |
| 286 | previous stable release's release notes. |
| 287 | </P |
| 288 | ><DIV |
| 289 | CLASS="note" |
| 290 | ><P |
| 291 | ></P |
| 292 | ><TABLE |
| 293 | CLASS="note" |
| 294 | WIDTH="100%" |
| 295 | BORDER="0" |
| 296 | ><TR |
| 297 | ><TD |
| 298 | WIDTH="25" |
| 299 | ALIGN="CENTER" |
| 300 | VALIGN="TOP" |
| 301 | ><IMG |
| 302 | SRC="../images/note.gif" |
| 303 | HSPACE="5" |
| 304 | ALT="Note"></TD |
| 305 | ><TD |
| 306 | ALIGN="LEFT" |
| 307 | VALIGN="TOP" |
| 308 | ><P |
| 309 | > Regardless of which method you choose, it is recommended that |
| 310 | you run <B |
| 311 | CLASS="command" |
| 312 | >./checksetup.pl</B |
| 313 | > after creating or |
| 314 | editing any templates in the <TT |
| 315 | CLASS="filename" |
| 316 | >template/en/default</TT |
| 317 | > |
| 318 | directory, and after editing any templates in the |
| 319 | <TT |
| 320 | CLASS="filename" |
| 321 | >custom</TT |
| 322 | > directory. |
| 323 | </P |
| 324 | ></TD |
| 325 | ></TR |
| 326 | ></TABLE |
| 327 | ></DIV |
| 328 | ><DIV |
| 329 | CLASS="warning" |
| 330 | ><P |
| 331 | ></P |
| 332 | ><TABLE |
| 333 | CLASS="warning" |
| 334 | WIDTH="100%" |
| 335 | BORDER="0" |
| 336 | ><TR |
| 337 | ><TD |
| 338 | WIDTH="25" |
| 339 | ALIGN="CENTER" |
| 340 | VALIGN="TOP" |
| 341 | ><IMG |
| 342 | SRC="../images/warning.gif" |
| 343 | HSPACE="5" |
| 344 | ALT="Warning"></TD |
| 345 | ><TD |
| 346 | ALIGN="LEFT" |
| 347 | VALIGN="TOP" |
| 348 | ><P |
| 349 | > It is <EM |
| 350 | >required</EM |
| 351 | > that you run |
| 352 | <B |
| 353 | CLASS="command" |
| 354 | >./checksetup.pl</B |
| 355 | > after creating a new |
| 356 | template in the <TT |
| 357 | CLASS="filename" |
| 358 | >custom</TT |
| 359 | > directory. Failure |
| 360 | to do so will raise an incomprehensible error message. |
| 361 | </P |
| 362 | ></TD |
| 363 | ></TR |
| 364 | ></TABLE |
| 365 | ></DIV |
| 366 | ></DIV |
| 367 | ><DIV |
| 368 | CLASS="section" |
| 369 | ><H2 |
| 370 | CLASS="section" |
| 371 | ><A |
| 372 | NAME="template-edit" |
| 373 | >5.1.3. How To Edit Templates</A |
| 374 | ></H2 |
| 375 | ><DIV |
| 376 | CLASS="note" |
| 377 | ><P |
| 378 | ></P |
| 379 | ><TABLE |
| 380 | CLASS="note" |
| 381 | WIDTH="100%" |
| 382 | BORDER="0" |
| 383 | ><TR |
| 384 | ><TD |
| 385 | WIDTH="25" |
| 386 | ALIGN="CENTER" |
| 387 | VALIGN="TOP" |
| 388 | ><IMG |
| 389 | SRC="../images/note.gif" |
| 390 | HSPACE="5" |
| 391 | ALT="Note"></TD |
| 392 | ><TD |
| 393 | ALIGN="LEFT" |
| 394 | VALIGN="TOP" |
| 395 | ><P |
| 396 | > If you are making template changes that you intend on submitting back |
| 397 | for inclusion in standard Bugzilla, you should read the relevant |
| 398 | sections of the |
| 399 | <A |
| 400 | HREF="http://www.bugzilla.org/docs/developer.html" |
| 401 | TARGET="_top" |
| 402 | >Developers' |
| 403 | Guide</A |
| 404 | >. |
| 405 | </P |
| 406 | ></TD |
| 407 | ></TR |
| 408 | ></TABLE |
| 409 | ></DIV |
| 410 | ><P |
| 411 | > The syntax of the Template Toolkit language is beyond the scope of |
| 412 | this guide. It's reasonably easy to pick up by looking at the current |
| 413 | templates; or, you can read the manual, available on the |
| 414 | <A |
| 415 | HREF="http://www.template-toolkit.org" |
| 416 | TARGET="_top" |
| 417 | >Template Toolkit home |
| 418 | page</A |
| 419 | >. |
| 420 | </P |
| 421 | ><P |
| 422 | > One thing you should take particular care about is the need |
| 423 | to properly HTML filter data that has been passed into the template. |
| 424 | This means that if the data can possibly contain special HTML characters |
| 425 | such as <, and the data was not intended to be HTML, they need to be |
| 426 | converted to entity form, i.e. &lt;. You use the 'html' filter in the |
| 427 | Template Toolkit to do this. If you forget, you may open up |
| 428 | your installation to cross-site scripting attacks. |
| 429 | </P |
| 430 | ><P |
| 431 | > Also note that Bugzilla adds a few filters of its own, that are not |
| 432 | in standard Template Toolkit. In particular, the 'url_quote' filter |
| 433 | can convert characters that are illegal or have special meaning in URLs, |
| 434 | such as &, to the encoded form, i.e. %26. This actually encodes most |
| 435 | characters (but not the common ones such as letters and numbers and so |
| 436 | on), including the HTML-special characters, so there's never a need to |
| 437 | HTML filter afterwards. |
| 438 | </P |
| 439 | ><P |
| 440 | > Editing templates is a good way of doing a <SPAN |
| 441 | CLASS="QUOTE" |
| 442 | >"poor man's custom |
| 443 | fields"</SPAN |
| 444 | >. |
| 445 | For example, if you don't use the Status Whiteboard, but want to have |
| 446 | a free-form text entry box for <SPAN |
| 447 | CLASS="QUOTE" |
| 448 | >"Build Identifier"</SPAN |
| 449 | >, |
| 450 | then you can just |
| 451 | edit the templates to change the field labels. It's still be called |
| 452 | status_whiteboard internally, but your users don't need to know that. |
| 453 | </P |
| 454 | ></DIV |
| 455 | ><DIV |
| 456 | CLASS="section" |
| 457 | ><H2 |
| 458 | CLASS="section" |
| 459 | ><A |
| 460 | NAME="template-formats" |
| 461 | >5.1.4. Template Formats and Types</A |
| 462 | ></H2 |
| 463 | ><P |
| 464 | > Some CGI's have the ability to use more than one template. For example, |
| 465 | <TT |
| 466 | CLASS="filename" |
| 467 | >buglist.cgi</TT |
| 468 | > can output itself as RDF, or as two |
| 469 | formats of HTML (complex and simple). The mechanism that provides this |
| 470 | feature is extensible. |
| 471 | </P |
| 472 | ><P |
| 473 | > Bugzilla can support different types of output, which again can have |
| 474 | multiple formats. In order to request a certain type, you can append |
| 475 | the &ctype=<contenttype> (such as rdf or html) to the |
| 476 | <TT |
| 477 | CLASS="filename" |
| 478 | ><cginame>.cgi</TT |
| 479 | > URL. If you would like to |
| 480 | retrieve a certain format, you can use the &format=<format> |
| 481 | (such as simple or complex) in the URL. |
| 482 | </P |
| 483 | ><P |
| 484 | > To see if a CGI supports multiple output formats and types, grep the |
| 485 | CGI for <SPAN |
| 486 | CLASS="QUOTE" |
| 487 | >"GetFormat"</SPAN |
| 488 | >. If it's not present, adding |
| 489 | multiple format/type support isn't too hard - see how it's done in |
| 490 | other CGIs, e.g. config.cgi. |
| 491 | </P |
| 492 | ><P |
| 493 | > To make a new format template for a CGI which supports this, |
| 494 | open a current template for |
| 495 | that CGI and take note of the INTERFACE comment (if present.) This |
| 496 | comment defines what variables are passed into this template. If |
| 497 | there isn't one, I'm afraid you'll have to read the template and |
| 498 | the code to find out what information you get. |
| 499 | </P |
| 500 | ><P |
| 501 | > Write your template in whatever markup or text style is appropriate. |
| 502 | </P |
| 503 | ><P |
| 504 | > You now need to decide what content type you want your template |
| 505 | served as. The content types are defined in the |
| 506 | <TT |
| 507 | CLASS="filename" |
| 508 | >Bugzilla/Constants.pm</TT |
| 509 | > file in the |
| 510 | <TT |
| 511 | CLASS="filename" |
| 512 | >contenttypes</TT |
| 513 | > |
| 514 | constant. If your content type is not there, add it. Remember |
| 515 | the three- or four-letter tag assigned to your content type. |
| 516 | This tag will be part of the template filename. |
| 517 | </P |
| 518 | ><DIV |
| 519 | CLASS="note" |
| 520 | ><P |
| 521 | ></P |
| 522 | ><TABLE |
| 523 | CLASS="note" |
| 524 | WIDTH="100%" |
| 525 | BORDER="0" |
| 526 | ><TR |
| 527 | ><TD |
| 528 | WIDTH="25" |
| 529 | ALIGN="CENTER" |
| 530 | VALIGN="TOP" |
| 531 | ><IMG |
| 532 | SRC="../images/note.gif" |
| 533 | HSPACE="5" |
| 534 | ALT="Note"></TD |
| 535 | ><TD |
| 536 | ALIGN="LEFT" |
| 537 | VALIGN="TOP" |
| 538 | ><P |
| 539 | > After adding or changing a content type, it's suitable to edit |
| 540 | <TT |
| 541 | CLASS="filename" |
| 542 | >Bugzilla/Constants.pm</TT |
| 543 | > in order to reflect |
| 544 | the changes. Also, the file should be kept up to date after an |
| 545 | upgrade if content types have been customized in the past. |
| 546 | </P |
| 547 | ></TD |
| 548 | ></TR |
| 549 | ></TABLE |
| 550 | ></DIV |
| 551 | ><P |
| 552 | > Save the template as <TT |
| 553 | CLASS="filename" |
| 554 | ><stubname>-<formatname>.<contenttypetag>.tmpl</TT |
| 555 | >. |
| 556 | Try out the template by calling the CGI as |
| 557 | <TT |
| 558 | CLASS="filename" |
| 559 | ><cginame>.cgi?format=<formatname>&ctype=<type></TT |
| 560 | > . |
| 561 | </P |
| 562 | ></DIV |
| 563 | ><DIV |
| 564 | CLASS="section" |
| 565 | ><H2 |
| 566 | CLASS="section" |
| 567 | ><A |
| 568 | NAME="template-specific" |
| 569 | >5.1.5. Particular Templates</A |
| 570 | ></H2 |
| 571 | ><P |
| 572 | > There are a few templates you may be particularly interested in |
| 573 | customizing for your installation. |
| 574 | </P |
| 575 | ><P |
| 576 | > <B |
| 577 | CLASS="command" |
| 578 | >index.html.tmpl</B |
| 579 | >: |
| 580 | This is the Bugzilla front page. |
| 581 | </P |
| 582 | ><P |
| 583 | > <B |
| 584 | CLASS="command" |
| 585 | >global/header.html.tmpl</B |
| 586 | >: |
| 587 | This defines the header that goes on all Bugzilla pages. |
| 588 | The header includes the banner, which is what appears to users |
| 589 | and is probably what you want to edit instead. However the |
| 590 | header also includes the HTML HEAD section, so you could for |
| 591 | example add a stylesheet or META tag by editing the header. |
| 592 | </P |
| 593 | ><P |
| 594 | > <B |
| 595 | CLASS="command" |
| 596 | >global/banner.html.tmpl</B |
| 597 | >: |
| 598 | This contains the <SPAN |
| 599 | CLASS="QUOTE" |
| 600 | >"banner"</SPAN |
| 601 | >, the part of the header |
| 602 | that appears |
| 603 | at the top of all Bugzilla pages. The default banner is reasonably |
| 604 | barren, so you'll probably want to customize this to give your |
| 605 | installation a distinctive look and feel. It is recommended you |
| 606 | preserve the Bugzilla version number in some form so the version |
| 607 | you are running can be determined, and users know what docs to read. |
| 608 | </P |
| 609 | ><P |
| 610 | > <B |
| 611 | CLASS="command" |
| 612 | >global/footer.html.tmpl</B |
| 613 | >: |
| 614 | This defines the footer that goes on all Bugzilla pages. Editing |
| 615 | this is another way to quickly get a distinctive look and feel for |
| 616 | your Bugzilla installation. |
| 617 | </P |
| 618 | ><P |
| 619 | > <B |
| 620 | CLASS="command" |
| 621 | >global/variables.none.tmpl</B |
| 622 | >: |
| 623 | This defines a list of terms that may be changed in order to |
| 624 | <SPAN |
| 625 | CLASS="QUOTE" |
| 626 | >"brand"</SPAN |
| 627 | > the Bugzilla instance In this way, terms |
| 628 | like <SPAN |
| 629 | CLASS="QUOTE" |
| 630 | >"bugs"</SPAN |
| 631 | > can be replaced with <SPAN |
| 632 | CLASS="QUOTE" |
| 633 | >"issues"</SPAN |
| 634 | > |
| 635 | across the whole Bugzilla installation. The name |
| 636 | <SPAN |
| 637 | CLASS="QUOTE" |
| 638 | >"Bugzilla"</SPAN |
| 639 | > and other words can be customized as well. |
| 640 | </P |
| 641 | ><P |
| 642 | > <B |
| 643 | CLASS="command" |
| 644 | >list/table.html.tmpl</B |
| 645 | >: |
| 646 | This template controls the appearance of the bug lists created |
| 647 | by Bugzilla. Editing this template allows per-column control of |
| 648 | the width and title of a column, the maximum display length of |
| 649 | each entry, and the wrap behaviour of long entries. |
| 650 | For long bug lists, Bugzilla inserts a 'break' every 100 bugs by |
| 651 | default; this behaviour is also controlled by this template, and |
| 652 | that value can be modified here. |
| 653 | </P |
| 654 | ><P |
| 655 | > <B |
| 656 | CLASS="command" |
| 657 | >bug/create/user-message.html.tmpl</B |
| 658 | >: |
| 659 | This is a message that appears near the top of the bug reporting page. |
| 660 | By modifying this, you can tell your users how they should report |
| 661 | bugs. |
| 662 | </P |
| 663 | ><P |
| 664 | > <B |
| 665 | CLASS="command" |
| 666 | >bug/process/midair.html.tmpl</B |
| 667 | >: |
| 668 | This is the page used if two people submit simultaneous changes to the |
| 669 | same bug. The second person to submit their changes will get this page |
| 670 | to tell them what the first person did, and ask if they wish to |
| 671 | overwrite those changes or go back and revisit the bug. The default |
| 672 | title and header on this page read "Mid-air collision detected!" If |
| 673 | you work in the aviation industry, or other environment where this |
| 674 | might be found offensive (yes, we have true stories of this happening) |
| 675 | you'll want to change this to something more appropriate for your |
| 676 | environment. |
| 677 | </P |
| 678 | ><P |
| 679 | > <B |
| 680 | CLASS="command" |
| 681 | >bug/create/create.html.tmpl</B |
| 682 | > and |
| 683 | <B |
| 684 | CLASS="command" |
| 685 | >bug/create/comment.txt.tmpl</B |
| 686 | >: |
| 687 | You may not wish to go to the effort of creating custom fields in |
| 688 | Bugzilla, yet you want to make sure that each bug report contains |
| 689 | a number of pieces of important information for which there is not |
| 690 | a special field. The bug entry system has been designed in an |
| 691 | extensible fashion to enable you to add arbitrary HTML widgets, |
| 692 | such as drop-down lists or textboxes, to the bug entry page |
| 693 | and have their values appear formatted in the initial comment. |
| 694 | A hidden field that indicates the format should be added inside |
| 695 | the form in order to make the template functional. Its value should |
| 696 | be the suffix of the template filename. For example, if the file |
| 697 | is called <TT |
| 698 | CLASS="filename" |
| 699 | >create-cust.html.tmpl</TT |
| 700 | >, then |
| 701 | <TABLE |
| 702 | BORDER="0" |
| 703 | BGCOLOR="#E0E0E0" |
| 704 | WIDTH="100%" |
| 705 | ><TR |
| 706 | ><TD |
| 707 | ><FONT |
| 708 | COLOR="#000000" |
| 709 | ><PRE |
| 710 | CLASS="programlisting" |
| 711 | ><input type="hidden" name="format" value="cust"></PRE |
| 712 | ></FONT |
| 713 | ></TD |
| 714 | ></TR |
| 715 | ></TABLE |
| 716 | > |
| 717 | should be used inside the form. |
| 718 | </P |
| 719 | ><P |
| 720 | > |
| 721 | An example of this is the mozilla.org |
| 722 | <A |
| 723 | HREF="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&format=guided" |
| 724 | TARGET="_top" |
| 725 | >guided |
| 726 | bug submission form</A |
| 727 | >. The code for this comes with the Bugzilla |
| 728 | distribution as an example for you to copy. It can be found in the |
| 729 | files |
| 730 | <TT |
| 731 | CLASS="filename" |
| 732 | >create-guided.html.tmpl</TT |
| 733 | > and |
| 734 | <TT |
| 735 | CLASS="filename" |
| 736 | >comment-guided.html.tmpl</TT |
| 737 | >. |
| 738 | </P |
| 739 | ><P |
| 740 | > So to use this feature, create a custom template for |
| 741 | <TT |
| 742 | CLASS="filename" |
| 743 | >enter_bug.cgi</TT |
| 744 | >. The default template, on which you |
| 745 | could base it, is |
| 746 | <TT |
| 747 | CLASS="filename" |
| 748 | >custom/bug/create/create.html.tmpl</TT |
| 749 | >. |
| 750 | Call it <TT |
| 751 | CLASS="filename" |
| 752 | >create-<formatname>.html.tmpl</TT |
| 753 | >, and |
| 754 | in it, add widgets for each piece of information you'd like |
| 755 | collected - such as a build number, or set of steps to reproduce. |
| 756 | </P |
| 757 | ><P |
| 758 | > Then, create a template like |
| 759 | <TT |
| 760 | CLASS="filename" |
| 761 | >custom/bug/create/comment.txt.tmpl</TT |
| 762 | >, and call it |
| 763 | <TT |
| 764 | CLASS="filename" |
| 765 | >comment-<formatname>.txt.tmpl</TT |
| 766 | >. This |
| 767 | template should reference the form fields you have created using |
| 768 | the syntax <TT |
| 769 | CLASS="filename" |
| 770 | >[% form.<fieldname> %]</TT |
| 771 | >. When a |
| 772 | bug report is |
| 773 | submitted, the initial comment attached to the bug report will be |
| 774 | formatted according to the layout of this template. |
| 775 | </P |
| 776 | ><P |
| 777 | > For example, if your custom enter_bug template had a field |
| 778 | <TABLE |
| 779 | BORDER="0" |
| 780 | BGCOLOR="#E0E0E0" |
| 781 | WIDTH="100%" |
| 782 | ><TR |
| 783 | ><TD |
| 784 | ><FONT |
| 785 | COLOR="#000000" |
| 786 | ><PRE |
| 787 | CLASS="programlisting" |
| 788 | ><input type="text" name="buildid" size="30"></PRE |
| 789 | ></FONT |
| 790 | ></TD |
| 791 | ></TR |
| 792 | ></TABLE |
| 793 | > |
| 794 | and then your comment.txt.tmpl had |
| 795 | <TABLE |
| 796 | BORDER="0" |
| 797 | BGCOLOR="#E0E0E0" |
| 798 | WIDTH="100%" |
| 799 | ><TR |
| 800 | ><TD |
| 801 | ><FONT |
| 802 | COLOR="#000000" |
| 803 | ><PRE |
| 804 | CLASS="programlisting" |
| 805 | >BuildID: [% form.buildid %]</PRE |
| 806 | ></FONT |
| 807 | ></TD |
| 808 | ></TR |
| 809 | ></TABLE |
| 810 | > |
| 811 | then something like |
| 812 | <TABLE |
| 813 | BORDER="0" |
| 814 | BGCOLOR="#E0E0E0" |
| 815 | WIDTH="100%" |
| 816 | ><TR |
| 817 | ><TD |
| 818 | ><FONT |
| 819 | COLOR="#000000" |
| 820 | ><PRE |
| 821 | CLASS="programlisting" |
| 822 | >BuildID: 20020303</PRE |
| 823 | ></FONT |
| 824 | ></TD |
| 825 | ></TR |
| 826 | ></TABLE |
| 827 | > |
| 828 | would appear in the initial comment. |
| 829 | </P |
| 830 | ></DIV |
| 831 | ><DIV |
| 832 | CLASS="section" |
| 833 | ><H2 |
| 834 | CLASS="section" |
| 835 | ><A |
| 836 | NAME="template-http-accept" |
| 837 | >5.1.6. Configuring Bugzilla to Detect the User's Language</A |
| 838 | ></H2 |
| 839 | ><P |
| 840 | >Bugzilla honours the user's Accept: HTTP header. You can install |
| 841 | templates in other languages, and Bugzilla will pick the most appropriate |
| 842 | according to a priority order defined by you. Many |
| 843 | language templates can be obtained from <A |
| 844 | HREF="http://www.bugzilla.org/download.html#localizations" |
| 845 | TARGET="_top" |
| 846 | >http://www.bugzilla.org/download.html#localizations</A |
| 847 | >. Instructions |
| 848 | for submitting new languages are also available from that location. |
| 849 | </P |
| 850 | ><P |
| 851 | >After untarring the localizations (or creating your own) in the |
| 852 | <TT |
| 853 | CLASS="filename" |
| 854 | >BUGZILLA_ROOT/template</TT |
| 855 | > directory, |
| 856 | you must update the <VAR |
| 857 | CLASS="option" |
| 858 | >languages</VAR |
| 859 | > parameter to contain any |
| 860 | localizations you'd like to permit. You may also wish to set the |
| 861 | <VAR |
| 862 | CLASS="option" |
| 863 | >defaultlanguage</VAR |
| 864 | > parameter to something other than |
| 865 | <SPAN |
| 866 | CLASS="QUOTE" |
| 867 | >"en"</SPAN |
| 868 | > if you don't want Engish to be the default language. |
| 869 | </P |
| 870 | ></DIV |
| 871 | ></DIV |
| 872 | ><DIV |
| 873 | CLASS="NAVFOOTER" |
| 874 | ><HR |
| 875 | ALIGN="LEFT" |
| 876 | WIDTH="100%"><TABLE |
| 877 | SUMMARY="Footer navigation table" |
| 878 | WIDTH="100%" |
| 879 | BORDER="0" |
| 880 | CELLPADDING="0" |
| 881 | CELLSPACING="0" |
| 882 | ><TR |
| 883 | ><TD |
| 884 | WIDTH="33%" |
| 885 | ALIGN="left" |
| 886 | VALIGN="top" |
| 887 | ><A |
| 888 | HREF="customization.html" |
| 889 | ACCESSKEY="P" |
| 890 | >Prev</A |
| 891 | ></TD |
| 892 | ><TD |
| 893 | WIDTH="34%" |
| 894 | ALIGN="center" |
| 895 | VALIGN="top" |
| 896 | ><A |
| 897 | HREF="index.html" |
| 898 | ACCESSKEY="H" |
| 899 | >Home</A |
| 900 | ></TD |
| 901 | ><TD |
| 902 | WIDTH="33%" |
| 903 | ALIGN="right" |
| 904 | VALIGN="top" |
| 905 | ><A |
| 906 | HREF="cust-hooks.html" |
| 907 | ACCESSKEY="N" |
| 908 | >Next</A |
| 909 | ></TD |
| 910 | ></TR |
| 911 | ><TR |
| 912 | ><TD |
| 913 | WIDTH="33%" |
| 914 | ALIGN="left" |
| 915 | VALIGN="top" |
| 916 | >Customising Bugzilla</TD |
| 917 | ><TD |
| 918 | WIDTH="34%" |
| 919 | ALIGN="center" |
| 920 | VALIGN="top" |
| 921 | ><A |
| 922 | HREF="customization.html" |
| 923 | ACCESSKEY="U" |
| 924 | >Up</A |
| 925 | ></TD |
| 926 | ><TD |
| 927 | WIDTH="33%" |
| 928 | ALIGN="right" |
| 929 | VALIGN="top" |
| 930 | >Template Hooks</TD |
| 931 | ></TR |
| 932 | ></TABLE |
| 933 | ></DIV |
| 934 | ></BODY |
| 935 | ></HTML |
| 936 | > |