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>,
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 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
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
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
103 AceHeader(). Cookies must be CGI::Cookie objects.
104 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 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 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 The three arguements are:
127 $symbol The keyword or query string the user was searching
129 on, undef if none.
130 $report The symbolic name of the current display, or undef
132 if none.
133 $objects An array reference containing the Ace objects in
135 question.
136 This subroutine is not exported by default.
138 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 ($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 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 $obj = GetAceObject();
157 if ($obj->CDS) {
158 my $protein = $obj->Corresponding_protein;
159 AceRedirect('protein',$protein);
160 }
161 AceRedirect must be called b<before> PrintTop() or AceHeader().
163 It invokes exit(), so it will not return.
164 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 $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 $name = DB_Name()
177 This function returns the symbolic name of the current database,
178 for example "default".
179 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 This function is not exported by default.
188 $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 $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 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 $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 $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 It is also possible to pass Object2URL an object name and class, in
216 the case that an AceDB object isn't available.
217 The return value is a URL.
219 $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 This function is used extensively to create cross references
227 between Ace::Objects on AceBrowser pages.
228 Example:
230 my $author = $db->fetch(Author => 'Sulston JE');
232 print ObjectLink($author,$author->Full_name);
233 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 $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 This function is not exported by default.
245 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 Call it with one or more arguments. The arguments are:
254 $object An AceDB object. The navigation bar and title will be
256 customized for the object.
257 $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 $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 @html_headers Additional HTML headers to pass to the the CGI.pm
267 start_html.
268 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 $hashref = Style()
278 This subroutine returns a hashref containing a reference to the
279 configured stylesheet, in the following format:
280 { -src => '/ace/stylesheets/current_stylesheet.css' }
282 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 This function is not exported by default.
290 $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 A typical call is:
297 $url = ResolveUrl('/cgi-bin/ace/generic/tree','name=fred;class=Author');
299 This function is not exported by default.
301 $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 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 $label The text of the generated link, for example "sequence"
315 $object_count The number of objects that opening the section will reveal
317 $add_plural If true, the label will be pluralized when
319 appropriate
320 $add_count If true, the label will have the object count added
322 when appropriate
323 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 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 This example indicates typical usage:
335 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 An alternative way to do the same thing:
344 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 $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 $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 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 Example:
369 my $url = Url('../sequence_dump',"name=$name;long_dump=yes");
371 print a({-href=>$url},'Dump this sequence');
372
374 Please report them.
375
377 Ace::Object, Ace::Browser::SiteDefs, Ace::Browsr::SearchSubs, the
378 README.ACEBROWSER file.
379
381 Lincoln Stein <lstein@cshl.org>.
382 Copyright (c) 2001 Cold Spring Harbor Laboratory
384 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.
388perl v5.12.0 2005-04-20 Ace::Browser::AceSubs(3)