.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Ace::Browser::SearchSubs 3pm"
.TH Ace::Browser::SearchSubs 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Ace::Browser::SearchSubs \- Subroutines for AceBrowser search scripts
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&  use Ace;
\&  use Ace::Browser::AceSubs;
\&  use Ace::Browser::SearchSubs;
\&  use CGI qw(:standard);
\&
\&  my $form = p(start_form,
\&               textfield(\-name=>\*(Aqquery\*(Aq),
\&               end_form);
\&  AceSearchTable(\*(AqSearch for stuff\*(Aq,$form);
\&  ...
\&
\&  my $query  = param(\*(Aqquery\*(Aq);
\&  my $offset = AceSearchOffset;
\&  my ($objects,$count) = do_search($query,$offset);
\&  AceResultsTable($objects,$count,$offset,\*(AqHere are results\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Ace::Browser::SearchSubs exports a set of constants and subroutines
that are useful for creating AceBrowser search scripts.
.SS CONSTANTS
.IX Subsection "CONSTANTS"
This package exports the following constants:
.PP
.Vb 2
\&  MAXOBJECTS     The maximum number of objects that can be displayed
\&                 per page.
\&
\&  SEARCH_ICON    An icon to use for search links. This is deprecated.
\&                 Use Configuration\->Search_icon instead.
.Ve
.SS FUNCTIONS
.IX Subsection "FUNCTIONS"
These functions are exported:
.ie n .IP "$offset = \fBAceSearchOffset()\fR" 4
.el .IP "\f(CW$offset\fR = \fBAceSearchOffset()\fR" 4
.IX Item "$offset = AceSearchOffset()"
When the user is paging back and forth among a multi-page list of
results, this function returns the index of the first item to display.
.IP AceSearchTable([{hash}],$title,@contents) 4
.IX Item "AceSearchTable([{hash}],$title,@contents)"
Given a title and the HTML contents, this formats the search into a
table and gives it the background and foreground colors used elsewhere
for searches.  The formatted search is then printed.
.Sp
The HTML contents are usually a fill-out form.  For convenience, you
can provide the contents in multiple parts (lines or elements) and
they will be concatenated together.
.Sp
If the first argument is a hashref, then its contents will be passed
to \fBstart_form()\fR to override the form arguments.
.IP AceResultsTable($objects,$count,$offset,$title) 4
.IX Item "AceResultsTable($objects,$count,$offset,$title)"
This subroutine formats the results of a search into a pageable list
and prints out the resulting HTML.  The following arguments are required:
.Sp
.Vb 2
\& $objects   An array reference containing the objects to place in the
\&            table.
\&
\& $count     The total number of objects.
\&
\& $offset    The offset into the array, as returned by AceSearchOffset()
\&
\& $title     A title for the table.
.Ve
.Sp
The array reference should contain no more than MAXOBJECTS objects.
The AceDB query should be arranged in such a way that this is the
case.  A typical idiom is the following:
.Sp
.Vb 9
\&  my $offset = AceSearchOffset();
\&  my $query  = param(\*(Aqquery\*(Aq);
\&  my $count;
\&  my @objs = $db\->fetch(\-query=> $query,
\&                        \-count  => MAXOBJECTS,
\&                        \-offset => $offset,
\&                        \-total => \e$count
\&                       );
\&  AceResultsTable(\e@objs,$count,$offset,\*(AqHere are the results\*(Aq);
.Ve
.SH BUGS
.IX Header "BUGS"
Please report them.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Ace::Object, Ace::Browser::SiteDefs, Ace::Browsr::AceSubs,
the README.ACEBROWSER file.
.SH AUTHOR
.IX Header "AUTHOR"
Lincoln Stein <lstein@cshl.org>.
.PP
Copyright (c) 2001 Cold Spring Harbor Laboratory
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.  See DISCLAIMER.txt for
disclaimers of warranty.