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.