1Ace::Browser::AceSubs(3U)ser Contributed Perl DocumentatiAocne::Browser::AceSubs(3)
2
3
4

NAME

6       Ace::Browser::AceSubs - Subroutines for AceBrowser
7

SYNOPSIS

9         use Ace;
10         use Ace::Browser::AceSubs;
11         use CGI qw(:standard);
12         use CGI::Cookie;
13
14         my $obj = GetAceObject() || AceNotFound();
15         PrintTop($obj);
16         print $obj->asHTML;
17         PrintBottom();
18

DESCRIPTION

20       Ace::Browser::AceSubs exports a set of routines that are useful for
21       creating search pages and displays for AceBrowser CGI pages. See
22       http://stein.cshl.org/AcePerl/AceBrowser.
23
24       The following subroutines are exported by default:
25
26         AceError
27         AceMissing
28         AceNotFound
29         Configuration
30         DoRedirect
31         GetAceObject
32         Object2URL
33         ObjectLink
34         OpenDatabase
35         PrintTop
36         PrintBottom
37         Url
38
39       The following subroutines are exported if explicitly requested:
40
41         AceAddCookie
42         AceInit
43         AceHeader
44         AceMultipleChoices
45         AceRedirect
46         DB_Name
47         Footer
48         Header
49         ResolveUrl
50         Style
51         Toggle
52         TypeSelector
53
54       To load the default subroutines load the module with:
55
56          use Ace::Browser::AceSubs;
57
58       To bring in a set of optionally routines, load the module with:
59
60          use Ace::Browser::AceSubs qw(AceInit AceRedirect);
61
62       To bring in all the default subroutines, plus some of the optional
63       ones:
64
65          use Ace::Browser::AceSubs qw(:DEFAULT AceInit AceRedirect);
66
67       There are two main types of AceBrowser scripts:
68
69       display scripts
70           These are called with the CGI parameters b<name> and b<class>,
71           corresponding to the name and class of an AceDB object to display.
72           The subroutine GetAceObject() will return the requested object, or
73           undef if the object does not exist.
74
75           To retrieve the parameters, use the CGI.pm param() method:
76
77             $name  = param('name');
78             $class = param('class');
79
80       search scripts
81           These are not called with any CGI parameters on their first
82           invocation, but can define their own parameter lists by creating
83           fill-out forms.  The AceBrowser system remembers the last search
84           performed by a search script in a cookie and regenerates the CGI
85           parameters the next time the user selects that search script.
86

SUBROUTINES

88       The following sections describe the exported subroutines.
89
90       AceError($message)
91           This subroutine will print out an error message and exit the
92           script.  The text of the message is taken from $message.
93
94       AceHeader()
95           This function prints the HTTP header and issues a number of cookies
96           used for maintaining AceBrowser state.  It is not exported by
97           default.
98
99       AceAddCookie(@cookies)
100           This subroutine, which must be called b<after> OpenDatabase()
101           and/or GetAceObject() and b<before> PrintTop(), will add one or
102           more cookies to the outgoing HTTP headers that are emitted by
103           AceHeader().  Cookies must be CGI::Cookie objects.
104
105       AceInit()
106           This subroutine initializes the AcePerl connection to the
107           configured database.  If the database cannot be opened, it
108           generates an error message and exits.  This subroutine is not
109           exported by default, but is called by PrintTop() and Header()
110           internally.
111
112       AceMissing([$class,$name])
113           This subroutine will print out an error message indicating that an
114           object is present in AceDB, but that the information the user
115           requested is absent. It will then exit the script. This is
116           infrequently encountered when following XREFed objects. If the
117           class and name of the object are not provided as arguments, they
118           are taken from CGI's param() function.
119
120       AceMultipleChoices($symbol,$report,$objects)
121           This function is called when a search has recovered multiple
122           objects and the user must make a choice among them.  The user is
123           presented with an ordered list of the objects, and asked to click
124           on one of them.
125
126           The three arguements are:
127
128              $symbol   The keyword or query string the user was searching
129                        on, undef if none.
130
131              $report   The symbolic name of the current display, or undef
132                        if none.
133
134              $objects  An array reference containing the Ace objects in
135                        question.
136
137           This subroutine is not exported by default.
138
139       AceNotFound([$class,$name])
140           This subroutine will print out an error message indicating that the
141           requested object is not present in AceDB, even as a name. It will
142           then exit the script. If the class and name of the object are not
143           provided as arguments, they are taken from CGI's param() function.
144
145       ($uri,$physical_path) = AcePicRoot($directory)
146           This function returns the physical and URL paths of a temporary
147           directory in which the pic script can write pictures.  Not exported
148           by default.  Returns a two-element list containing the URL and
149           physical path.
150
151       AceRedirect($report,$object)
152           This function redirects the user to a named display script for
153           viewing an Ace object.  It is used, for example, to convert a
154           request for a sequence into a request for a protein:
155
156             $obj = GetAceObject();
157             if ($obj->CDS) {
158               my $protein = $obj->Corresponding_protein;
159               AceRedirect('protein',$protein);
160             }
161
162           AceRedirect must be called b<before> PrintTop() or  AceHeader().
163           It invokes exit(), so it will not return.
164
165           This subroutine is not exported by default.  It differs from
166           DoRedirect() in that it displays a message to the user for two
167           seconds before it generates the new page. It also allows the
168           display to be set explicitly, rather than determined automatically
169           by the AceBrowser system.
170
171       $configuration = Configuration()
172           The Configuration() function returns the Ace::Browser::SiteDefs
173           object for the current session.  From this object you can retrieve
174           information from the configuration file.
175
176       $name = DB_Name()
177           This function returns the symbolic name of the current database,
178           for example "default".
179
180       DoRedirect($object)
181           This subroutine immediately redirects to the default display for
182           the Ace::Object indicated by $object and exits the script.  It must
183           be called before PrintTop() or any other HTML-generating code.  It
184           differs from AceRedirect() in that it generates a fast redirect
185           without alerting the user.
186
187           This function is not exported by default.
188
189       $footer = Footer()
190           This function returns the contents of the footer as a string, but
191           does not print it out.  It is not exported by default.
192
193       $object = GetAceObject()
194           This function is called by display scripts to return the
195           Ace::Object.that the user wishes to view.  It automatically opens
196           or refreshes the database, and performs the request using the
197           values of the "name" and "class" CGI variables.
198
199           If a single object is found, the function returns it as the
200           function result.  If no objects are found, it returns undef.  If
201           more than one object is found, the function invokes
202           AceMultipleChoices() and exits the script.
203
204       $html = Header()
205           This subroutine returns the boilerplate at the top of the HTML page
206           as a string, but does not print it out.  It is not exported by
207           default.
208
209       $url = Object2URL($object)
210       $url = Object2URL($name,$class)
211           In its single-argument form, this function takes an AceDB Object
212           and returns an AceBrowser URL.  The URL chosen is determined by the
213           configuration settings.
214
215           It is also possible to pass Object2URL an object name and class, in
216           the case that an AceDB object isn't available.
217
218           The return value is a URL.
219
220       $link = ObjectLink($object [,$link_text])
221           This function converts an AceDB object into a hypertext link.  The
222           first argument is an Ace::Object.  The second, optional argument is
223           the text to use for the link.  If not provided, the object's name
224           becomes the link text.
225
226           This function is used extensively to create cross references
227           between Ace::Objects on AceBrowser pages.
228
229           Example:
230
231             my $author = $db->fetch(Author => 'Sulston JE');
232             print ObjectLink($author,$author->Full_name);
233
234           This will print out a link to a page that will display details on
235           the author page.  The text of the link will be the value of the
236           Full_name tag.
237
238       $db = OpenDatabase()
239           This function opens the Acedb database designated by the
240           configuration file.  In modperl environments, this function caches
241           database handles and reuses them, pinging and reopening them in the
242           case of timeouts.
243
244           This function is not exported by default.
245
246       PrintTop($object,$class,$title,@html_headers)
247           The PrintTop() function generates all the boilerplate at the top of
248           a typical AceBrowser page, including the HTTP header information,
249           the page title, the navigation bar for searches, the web site
250           banner, the type selector for choosing alternative displays, and a
251           level-one header.
252
253           Call it with one or more arguments.  The arguments are:
254
255             $object    An AceDB object.  The navigation bar and title will be
256                        customized for the object.
257
258             $class     If no AceDB object is available, then you can pass
259                        a string containing the AceDB class that this page is
260                        designed to display.
261
262             $title     A title to use for the HTML page and the first level-one
263                        header.  If not provided, a generic title "Report for
264                        Object" is generated.
265
266             @html_headers  Additional HTML headers to pass to the the CGI.pm
267                        start_html.
268
269       PrintBottom()
270           The PrintBottom() function outputs all the boilerplate at the
271           bottom of a typical AceBrowser page.  If a user-defined footer is
272           present in the configuration file, that is printed.  Otherwise, the
273           method prints a horizontal rule followed by links to the site home
274           page, the AcePerl home page, the privacy policy, and the feedback
275           page.
276
277       $hashref = Style()
278           This subroutine returns a hashref containing a reference to the
279           configured stylesheet, in the following format:
280
281             { -src => '/ace/stylesheets/current_stylesheet.css' }
282
283           This hash is suitable for passing to the -style argument of
284           CGI.pm's start_html() function, or for use as an additional header
285           in PrintTop().  You may add locally-defined stylesheet elements to
286           the hash before calling start_html().  See the pic script for an
287           example of how this is done this.
288
289           This function is not exported by default.
290
291       $url = ResolveUrl($url,$param)
292           Given a URL and a set of parameters, this function does the
293           necessary magic to add the symbolic database name to the end of the
294           URL (if needed) and then tack the parameters onto the end.
295
296           A typical call is:
297
298             $url = ResolveUrl('/cgi-bin/ace/generic/tree','name=fred;class=Author');
299
300           This function is not exported by default.
301
302       $boolean =
303       Toggle($section,[$label,$object_count,$add_plural,$add_count])
304       ($link,$bool) =
305       Toggle($section,$label,$object_count,$add_plural,$add_count)
306           The Toggle() subroutine makes it easy to create HTML sections that
307           open and close when the user selects a toggle icon (a yellow
308           triangle).
309
310           Toggle() can be used to manage multiple collapsible HTML sections,
311           but each section must have a unique name.  The required first
312           argument is the section name.  Optional arguments are:
313
314             $label         The text of the generated link, for example "sequence"
315
316             $object_count  The number of objects that opening the section will reveal
317
318             $add_plural    If true, the label will be pluralized when
319                            appropriate
320
321             $add_count     If true, the label will have the object count added
322                            when appropriate
323
324           In a scalar context, Toggle() prints the link HTML and returns a
325           boolean flag.  A true result indicates that the section is expanded
326           and should be generated.  A false result indicates that the section
327           is collapsed.
328
329           In a list context, Toggle() returns a two-element list.  The first
330           element is the HTML link that expands and contracts the section.
331           The second element is a boolean that indicates whether the section
332           is currently open or closed.
333
334           This example indicates typical usage:
335
336             my $sequence = GetAceObject();
337             print "sequence name = ",$sequence,"\n";
338             print "sequence clone = ",$sequence->Clone,"\n";
339             if (Toggle('dna','Sequence DNA')) {
340                 print $sequence->asDNA;
341             }
342
343           An alternative way to do the same thing:
344
345             my $sequence = GetAceObject();
346             print "sequence name = ",$sequence,"\n";
347             print "sequence clone = ",$sequence->Clone,"\n";
348             my ($link,$open) = Toggle('dna','Sequence DNA');
349             print $link;
350             print $sequence->asDNA if $open;
351
352       $html = TypeSelector($name,$class)
353           This subroutine generates the HTML for the type selector navigation
354           bar.  The links in the bar are dynamically generated based on the
355           values of $name and $class.  This function is called by PrintTop().
356           It is not exported by default.
357
358       $url = Url($display,$params)
359           Given a symbolic display name, such as "tree" and a set of
360           parameters, this function looks up its URL and then calls
361           ResolveUrl() to create a single Url.
362
363           When hard-coding relative URLs into AceBrowser scripts, it is
364           important to pass them through Url().  The reason for this is that
365           AceBrowser may need to attach the database name to the URL in order
366           to identify it.
367
368           Example:
369
370             my $url = Url('../sequence_dump',"name=$name;long_dump=yes");
371             print a({-href=>$url},'Dump this sequence');
372

BUGS

374       Please report them.
375

SEE ALSO

377       Ace::Object, Ace::Browser::SiteDefs, Ace::Browsr::SearchSubs, the
378       README.ACEBROWSER file.
379

AUTHOR

381       Lincoln Stein <lstein@cshl.org>.
382
383       Copyright (c) 2001 Cold Spring Harbor Laboratory
384
385       This library is free software; you can redistribute it and/or modify it
386       under the same terms as Perl itself.  See DISCLAIMER.txt for
387       disclaimers of warranty.
388
389
390
391perl v5.32.0                      2020-07-28          Ace::Browser::AceSubs(3)
Impressum