1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
|
<HTML
><HEAD
><TITLE
>Template Hooks</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="The Bugzilla Guide - 2.17.7
Development Release"
HREF="index.html"><LINK
REL="UP"
TITLE="Customising Bugzilla"
HREF="customization.html"><LINK
REL="PREVIOUS"
TITLE="Template Customization"
HREF="cust-templates.html"><LINK
REL="NEXT"
TITLE="Customizing Who Can Change What"
HREF="cust-change-permissions.html"></HEAD
><BODY
CLASS="section"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The Bugzilla Guide - 2.17.7
Development Release</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="cust-templates.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 4. Customising Bugzilla</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="cust-change-permissions.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="cust-hooks"
></A
>4.2. Template Hooks</H1
><P
> 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.
</P
><P
> 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.
</P
><P
> 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
<TT
CLASS="literal"
>[% Hook.process("<TT
CLASS="varname"
>name</TT
>") %]</TT
>,
where <TT
CLASS="varname"
>name</TT
> is the unique (within that template)
name of the hook.
</P
><P
> 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. <B
CLASS="command"
>grep</B
>) to search the standard templates
for occurrences of <TT
CLASS="methodname"
>Hook.process</TT
> or browse
the directory tree in
<TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/extension/hook/</TT
>,
which contains a directory for each hook in the following location:
</P
><P
> <TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/</TT
>
</P
><P
> If there is no hook at the appropriate place within the Bugzilla template
you want to extend,
<A
HREF="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=User%20Interface"
TARGET="_top"
>file
a bug requesting one</A
>, specifying:
</P
><P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>the template for which you are requesting a hook;</TD
></TR
><TR
><TD
> 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);
</TD
></TR
><TR
><TD
>the purpose of the hook;</TD
></TR
><TR
><TD
>a link to information about your extension, if any.</TD
></TR
></TBODY
></TABLE
><P
></P
><P
> 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
<TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/extension/hook/</TT
>.
</P
><P
> 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.
</P
><P
> After making sure the hook you need exists (or getting it added if not),
add your extension template to the directory within the Bugzilla
directory tree corresponding to the hook.
</P
><P
> 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.
</P
><P
> For example, let's say you have an extension named Projman that adds
project management capabilities to Bugzilla. Projman has an
administration interface <TT
CLASS="filename"
>edit-projects.cgi</TT
>,
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.
</P
><P
> The navigation bar is generated by the template file
<TT
CLASS="filename"
>useful-links.html.tmpl</TT
>, which is located in
the <TT
CLASS="filename"
>global/</TT
> subdirectory on the standard Bugzilla
template path
<TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/default/</TT
>.
Looking in <TT
CLASS="filename"
>useful-links.html.tmpl</TT
>, you find
the following hook at the end of the list of standard Bugzilla
administration links:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>...
[% ', <a href="editkeywords.cgi">keywords</a>'
IF user.groups.editkeywords %]
[% Hook.process("edit") %]
...</PRE
></FONT
></TD
></TR
></TABLE
><P
> The corresponding directory for this hook is
<TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/</TT
>.
</P
><P
> You put a template named
<TT
CLASS="filename"
>projman-edit-projects.html.tmpl</TT
>
into that directory with the following content:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]</PRE
></FONT
></TD
></TR
></TABLE
><P
> Voila! The link now appears after the other administration links in the
navigation bar for users in the <TT
CLASS="literal"
>projman_admins</TT
> group.
</P
><P
> Notes:
</P
><P
></P
><UL
><LI
><P
> You may want to prefix your extension template names
with the name of your extension, e.g.
<TT
CLASS="filename"
>projman-foo.html.tmpl</TT
>,
so they do not conflict with the names of templates installed by
other extensions.
</P
></LI
><LI
><P
> 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
<TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/extension/</TT
>
directory. The <TT
CLASS="filename"
>extension/</TT
> directory, like the
<TT
CLASS="filename"
>default/</TT
> and <TT
CLASS="filename"
>custom/</TT
>
directories, is part of the template search path, so putting templates
there enables them to be found by the template processor.
</P
><P
> The template processor looks for templates first in the
<TT
CLASS="filename"
>custom/</TT
> directory (i.e. templates added by the
specific installation), then in the <TT
CLASS="filename"
>extension/</TT
>
directory (i.e. templates added by extensions), and finally in the
<TT
CLASS="filename"
>default/</TT
> directory (i.e. the standard Bugzilla
templates). Thus extension templates can override standard templates,
but installation-specific templates override both.
</P
><P
> 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.
</P
></LI
><LI
><P
> Installation customizers can also take advantage of hooks when adding
code to a Bugzilla template. To do so, create directories in
<TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/custom/hook/</TT
>
equivalent to the directories in
<TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/extension/hook/</TT
>
for the hooks you want to use, then place your customization templates
into those directories.
</P
><P
> 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.
</P
></LI
></UL
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="cust-templates.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="cust-change-permissions.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Template Customization</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="customization.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Customizing Who Can Change What</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
|
