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
|
Gnatsweb
Web interface to GNATS
The GNU Problem Report Management System
Customizing Gnatsweb 4
Using Callbacks
===============
Callbacks provide a more powerful way of customizing Gnatsweb than the
configuration variable approach detailed in CUSTOMIZE.vars. By
default, the gnatsweb.pl script provides "callback hooks" in several
places where it is expected that sites may want to modify behaviour,
such as providing extra buttons or functionality on the main page,
extra explanatory text in the Edit and Create PR pages and so on.
Basic knowledge of Perl is required in order to use callbacks.
Callback hooks generally look like this:
result = cb('reason', arg1, arg2, ...);
The cb subroutine in turn calls the site_callback subroutine in the
site configuration file, by default gnatsweb-site.pl and passes the
reason and the args. The site_callback routine typically consists of
a series of if statements which are used for selecting which subblock of
site_callback to execute, based on the passed reason. See the file
gnatsweb-site-example.pl for an example of this.
The called block of code returns a result which can then be used in
the calling gnatsweb.pl routine. If cb is called with a reason that
is not defined in the site configuration file, undef is returned.
A typical application for this is adding extra text or form buttons to
Gnatsweb pages. An example illustrates this:
In the main_page subroutine of gnatsweb.pl, you will find two lines
reading
my $top_buttons_html = cb('main_page_top_buttons') || '';
print $top_buttons_html;
This basically means that we can define a block of code in the site
file which returns HTML which will then be added to the top of the
main page. The example file gnatsweb-site-example.pl contains such a
block:
if ($reason eq 'main_page_top_buttons')
{
my $html = one_line_form('Open Support Issue:',
$q->submit(-name=>'cmd', -value=>'create'),
$q->hidden(-name=>'Class', -default=>'support'),
$q->hidden(-name=>'Submitter-Id',
-default=>'internal'));
return $html;
}
This block returns the HTML for an additional 'create' button which
takes the user to the Create PR page with Class set to 'support' and
Submitter-Id set to 'internal'.
Using the default callback hooks
================================
As previously mentioned, Gnatsweb contains several default hooks which
allow you to customize key parts of Gnatsweb behaviour. The callback
reasons and their intended use is listed below, and examples of how
some of them can be used can be found in the gnatsweb-site-example.pl
file of the Gnatsweb distribution.
Reason: page_start_html
Called from: page_start_html
With parameters: $title
When this reason is defined in site_callback, the top banner and the
button bar are replaced by the returned HTML. $title is the page
title.
Reason: page_heading
Called from: page_heading
With parameters: $title, $heading
The page heading (by default a simple H1), is replaced by the returned
HTML. $title is the page title and $heading is the page heading.
Reason: main_page_top_buttons
Called from: main_page
With parameters: none
The HTML code returned is added above the first default button of the
main page. An example of this can be found in the
gnatsweb-site-example.pl file of the Gnatsweb distribution.
Reason: main_page_bottom_buttons
Called from: main_page
With parameters: none
Same as main_page_top_buttons, but the returned HTML is added below
the last default button on the main page. A fairly advanced example
of this can be found in gnatsweb-site-example.pl.
Reason: page_footer
Called from: page_footer
With parameters: $title
The HTML returned is added before the end of each page. $title is the
page title.
Reason: page_end_html
Called from: page_end_html
With parameters: $title
The HTML returned is printed together with the end BODY and HTML tags
on each page.
Reason: login_page_text
Called from: login_page
With parameters: none
The HTML returned is printed between the heading and the
username/password fields on the login page.
Reason: initialize
Called from: initialize
With parameters: none
The initialize subroutine of gnatsweb.pl takes care of logging into
GNATS and initializing certain globals, such as database access level
and valid categories and submitters for the current database. This
callback hook is located at the end of initialize, so here you can add
commands and have them sent to the GNATS daemon each time a session is
initiated. You can also use this callback for such things as
restricting the list of valid categories or submitters. The return
value of this callback is thrown away.
Reason: cmd
Called from: main
With parameters: $cmd
Each time Gnatsweb is invoked, a command is passed to indicate what
action Gnatsweb should take. For instance, if you click the 'advanced
query' button on the main page, the browser passes the parameter
'advanced query' as part of the HTTP request to the web server. The
'main' subroutine is basically a big switch which calls the
subroutines associated with each command. The 'cmd' callback provides
a way to extend funtionality by adding commands, an explanatory
example can be found in the gnatsweb-site-example.pl file of the
Gnatsweb distribution. $cmd is the passed command name.
Reason: edit_intro_'fieldname'
Called from: edit
With parameters: $field_number
The returned HTML is inserted above the given field in the Edit PR
page. Note that the fieldname should be the name of the field that is
specified in the dbconfig file. An example, inserting a notice above
the 'Description' field is included in the gnatsweb-site-example.pl
file. The $field_number parameter is JavaScript-related -- look in
the gnatsweb.pl file for details.
Reason: sendpr_intro_'fieldname'
Called from: sendpr
With parameters: $field_number
Same as edit_intro_'fieldname', but the returned HTML is inserted on
the Create PR page.
Adding your own callback hooks
==============================
Adding your own callbacks is as easy as inventing your own unique
'reason', inserting the appropriate call to cb in gnatsweb.pl and
writing the corresponding block of code inside site_callback in your
own site configuration file (by default gnatsweb-site.pl). This is
the recommended way to add your own customizations, since upgrading
Gnatsweb later on will only require that you carry the cb calls over
to the new gnatsweb.pl.
|
