1Ace::Browser::AceSubs(3U)ser Contributed Perl DocumentatiAocne::Browser::AceSubs(3)
2
6 Ace::Browser::AceSubs - Subroutines for AceBrowser
7
9 use Ace;
10 use Ace::Browser::AceSubs;
11 use CGI qw(:standard);
12 use CGI::Cookie;
13 my $obj = GetAceObject() ⎪⎪ AceNotFound();
15 PrintTop($obj);
16 print $obj->asHTML;
17 PrintBottom();
18
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 The following subroutines are exported by default:
25 AceError
27 AceMissing
28 AceNotFound
29 Configuration
30 DoRedirect
31 GetAceObject
32 Object2URL
33 ObjectLink
34 OpenDatabase
35 PrintTop
36 PrintBottom
37 Url
38 The following subroutines are exported if explicitly requested:
40 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 To load the default subroutines load the module with:
55 use Ace::Browser::AceSubs;
57 To bring in a set of optionally routines, load the module with:
59 use Ace::Browser::AceSubs qw(AceInit AceRedirect);
61 To bring in all the default subroutines, plus some of the optional
63 ones:
64 use Ace::Browser::AceSubs qw(:DEFAULT AceInit AceRedirect);
66 There are two main types of AceBrowser scripts:
68 display scripts
70 These are called with the CGI parameters b<name> and b<class>, cor‐
71 responding 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 To retrieve the parameters, use the CGI.pm param() method:
76 $name = param('name');
78 $class = param('class');
79 search scripts
81 These are not called with any CGI parameters on their first invoca‐
82 tion, but can define their own parameter lists by creating fill-out
83 forms. The AceBrowser system remembers the last search performed
84 by a search script in a cookie and regenerates the CGI parameters
85 the next time the user selects that search script.
86
88 The following sections describe the exported subroutines.
89 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 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 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 Ace‐
103 Header(). Cookies must be CGI::Cookie objects.
104 AceInit()
106 This subroutine initializes the AcePerl connection to the config‐
107 ured database. If the database cannot be opened, it generates an
108 error message and exits. This subroutine is not exported by
109 default, but is called by PrintTop() and Header() internally.
110 AceMissing([$class,$name])
112 This subroutine will print out an error message indicating that an
113 object is present in AceDB, but that the information the user
114 requested is absent. It will then exit the script. This is infre‐
115 quently encountered when following XREFed objects. If the class and
116 name of the object are not provided as arguments, they are taken
117 from CGI's param() function.
118 AceMultipleChoices($symbol,$report,$objects)
120 This function is called when a search has recovered multiple
121 objects and the user must make a choice among them. The user is
122 presented with an ordered list of the objects, and asked to click
123 on one of them.
124 The three arguements are:
126 $symbol The keyword or query string the user was searching
128 on, undef if none.
129 $report The symbolic name of the current display, or undef
131 if none.
132 $objects An array reference containing the Ace objects in
134 question.
135 This subroutine is not exported by default.
137 AceNotFound([$class,$name])
139 This subroutine will print out an error message indicating that the
140 requested object is not present in AceDB, even as a name. It will
141 then exit the script. If the class and name of the object are not
142 provided as arguments, they are taken from CGI's param() function.
143 ($uri,$physical_path) = AcePicRoot($directory)
145 This function returns the physical and URL paths of a temporary
146 directory in which the pic script can write pictures. Not exported
147 by default. Returns a two-element list containing the URL and
148 physical path.
149 AceRedirect($report,$object)
151 This function redirects the user to a named display script for
152 viewing an Ace object. It is used, for example, to convert a
153 request for a sequence into a request for a protein:
154 $obj = GetAceObject();
156 if ($obj->CDS) {
157 my $protein = $obj->Corresponding_protein;
158 AceRedirect('protein',$protein);
159 }
160 AceRedirect must be called b<before> PrintTop() or AceHeader().
162 It invokes exit(), so it will not return.
163 This subroutine is not exported by default. It differs from
165 DoRedirect() in that it displays a message to the user for two sec‐
166 onds before it generates the new page. It also allows the display
167 to be set explicitly, rather than determined automatically by the
168 AceBrowser system.
169 $configuration = Configuration()
171 The Configuration() function returns the Ace::Browser::SiteDefs
172 object for the current session. From this object you can retrieve
173 information from the configuration file.
174 $name = DB_Name()
176 This function returns the symbolic name of the current database,
177 for example "default".
178 DoRedirect($object)
180 This subroutine immediately redirects to the default display for
181 the Ace::Object indicated by $object and exits the script. It must
182 be called before PrintTop() or any other HTML-generating code. It
183 differs from AceRedirect() in that it generates a fast redirect
184 without alerting the user.
185 This function is not exported by default.
187 $footer = Footer()
189 This function returns the contents of the footer as a string, but
190 does not print it out. It is not exported by default.
191 $object = GetAceObject()
193 This function is called by display scripts to return the
194 Ace::Object.that the user wishes to view. It automatically opens
195 or refreshes the database, and performs the request using the val‐
196 ues of the "name" and "class" CGI variables.
197 If a single object is found, the function returns it as the func‐
199 tion result. If no objects are found, it returns undef. If more
200 than one object is found, the function invokes AceMultipleChoices()
201 and exits the script.
202 $html = Header()
204 This subroutine returns the boilerplate at the top of the HTML page
205 as a string, but does not print it out. It is not exported by
206 default.
207 $url = Object2URL($object)
209 $url = Object2URL($name,$class)
210 In its single-argument form, this function takes an AceDB Object
211 and returns an AceBrowser URL. The URL chosen is determined by the
212 configuration settings.
213 It is also possible to pass Object2URL an object name and class, in
215 the case that an AceDB object isn't available.
216 The return value is a URL.
218 $link = ObjectLink($object [,$link_text])
220 This function converts an AceDB object into a hypertext link. The
221 first argument is an Ace::Object. The second, optional argument is
222 the text to use for the link. If not provided, the object's name
223 becomes the link text.
224 This function is used extensively to create cross references
226 between Ace::Objects on AceBrowser pages.
227 Example:
229 my $author = $db->fetch(Author => 'Sulston JE');
231 print ObjectLink($author,$author->Full_name);
232 This will print out a link to a page that will display details on
234 the author page. The text of the link will be the value of the
235 Full_name tag.
236 $db = OpenDatabase()
238 This function opens the Acedb database designated by the configura‐
239 tion file. In modperl environments, this function caches database
240 handles and reuses them, pinging and reopening them in the case of
241 timeouts.
242 This function is not exported by default.
244 PrintTop($object,$class,$title,@html_headers)
246 The PrintTop() function generates all the boilerplate at the top of
247 a typical AceBrowser page, including the HTTP header information,
248 the page title, the navigation bar for searches, the web site ban‐
249 ner, the type selector for choosing alternative displays, and a
250 level-one header.
251 Call it with one or more arguments. The arguments are:
253 $object An AceDB object. The navigation bar and title will be
255 customized for the object.
256 $class If no AceDB object is available, then you can pass
258 a string containing the AceDB class that this page is
259 designed to display.
260 $title A title to use for the HTML page and the first level-one
262 header. If not provided, a generic title "Report for
263 Object" is generated.
264 @html_headers Additional HTML headers to pass to the the CGI.pm
266 start_html.
267 PrintBottom()
269 The PrintBottom() function outputs all the boilerplate at the bot‐
270 tom of a typical AceBrowser page. If a user-defined footer is
271 present in the configuration file, that is printed. Otherwise, the
272 method prints a horizontal rule followed by links to the site home
273 page, the AcePerl home page, the privacy policy, and the feedback
274 page.
275 $hashref = Style()
277 This subroutine returns a hashref containing a reference to the
278 configured stylesheet, in the following format:
279 { -src => '/ace/stylesheets/current_stylesheet.css' }
281 This hash is suitable for passing to the -style argument of
283 CGI.pm's start_html() function, or for use as an additional header
284 in PrintTop(). You may add locally-defined stylesheet elements to
285 the hash before calling start_html(). See the pic script for an
286 example of how this is done this.
287 This function is not exported by default.
289 $url = ResolveUrl($url,$param)
291 Given a URL and a set of parameters, this function does the neces‐
292 sary magic to add the symbolic database name to the end of the URL
293 (if needed) and then tack the parameters onto the end.
294 A typical call is:
296 $url = ResolveUrl('/cgi-bin/ace/generic/tree','name=fred;class=Author');
298 This function is not exported by default.
300 $boolean = Toggle($section,[$label,$object_count,$add_plu‐
302 ral,$add_count])
303 ($link,$bool) = Toggle($section,$label,$object_count,$add_plu‐
304 ral,$add_count)
305 The Toggle() subroutine makes it easy to create HTML sections that
306 open and close when the user selects a toggle icon (a yellow trian‐
307 gle).
308 Toggle() can be used to manage multiple collapsible HTML sections,
310 but each section must have a unique name. The required first argu‐
311 ment is the section name. Optional arguments are:
312 $label The text of the generated link, for example "sequence"
314 $object_count The number of objects that opening the section will reveal
316 $add_plural If true, the label will be pluralized when
318 appropriate
319 $add_count If true, the label will have the object count added
321 when appropriate
322 In a scalar context, Toggle() prints the link HTML and returns a
324 boolean flag. A true result indicates that the section is expanded
325 and should be generated. A false result indicates that the section
326 is collapsed.
327 In a list context, Toggle() returns a two-element list. The first
329 element is the HTML link that expands and contracts the section.
330 The second element is a boolean that indicates whether the section
331 is currently open or closed.
332 This example indicates typical usage:
334 my $sequence = GetAceObject();
336 print "sequence name = ",$sequence,"\n";
337 print "sequence clone = ",$sequence->Clone,"\n";
338 if (Toggle('dna','Sequence DNA')) {
339 print $sequence->asDNA;
340 }
341 An alternative way to do the same thing:
343 my $sequence = GetAceObject();
345 print "sequence name = ",$sequence,"\n";
346 print "sequence clone = ",$sequence->Clone,"\n";
347 my ($link,$open) = Toggle('dna','Sequence DNA');
348 print $link;
349 print $sequence->asDNA if $open;
350 $html = TypeSelector($name,$class)
352 This subroutine generates the HTML for the type selector navigation
353 bar. The links in the bar are dynamically generated based on the
354 values of $name and $class. This function is called by PrintTop().
355 It is not exported by default.
356 $url = Url($display,$params)
358 Given a symbolic display name, such as "tree" and a set of parame‐
359 ters, this function looks up its URL and then calls ResolveUrl() to
360 create a single Url.
361 When hard-coding relative URLs into AceBrowser scripts, it is
363 important to pass them through Url(). The reason for this is that
364 AceBrowser may need to attach the database name to the URL in order
365 to identify it.
366 Example:
368 my $url = Url('../sequence_dump',"name=$name;long_dump=yes");
370 print a({-href=>$url},'Dump this sequence');
371
373 Please report them.
374
376 Ace::Object, Ace::Browser::SiteDefs, Ace::Browsr::SearchSubs, the
377 README.ACEBROWSER file.
378
380 Lincoln Stein <lstein@cshl.org>.
381 Copyright (c) 2001 Cold Spring Harbor Laboratory
383 This library is free software; you can redistribute it and/or modify it
385 under the same terms as Perl itself. See DISCLAIMER.txt for dis‐
386 claimers of warranty.
387perl v5.8.8 2001-02-20 Ace::Browser::AceSubs(3)