[Bio] / FigKernelPackages / TemplateObject.pm Repository:
ViewVC logotype

Annotation of /FigKernelPackages/TemplateObject.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.5 - (view) (download) (as text)

1 : parrello 1.1 #!/usr/bin/perl -w
2 :    
3 :     # -*- perl -*-
4 :     #
5 :     # Copyright (c) 2003-2006 University of Chicago and Fellowship
6 :     # for Interpretations of Genomes. All Rights Reserved.
7 :     #
8 :     # This file is part of the SEED Toolkit.
9 :     #
10 :     # The SEED Toolkit is free software. You can redistribute
11 :     # it and/or modify it under the terms of the SEED Toolkit
12 :     # Public License.
13 :     #
14 :     # You should have received a copy of the SEED Toolkit Public License
15 :     # along with this program; if not write to the University of Chicago
16 :     # at info@ci.uchicago.edu or the Fellowship for Interpretation of
17 :     # Genomes at veronika@thefig.info or download a copy from
18 :     # http://www.theseed.org/LICENSE.TXT.
19 :     #
20 :    
21 :     package TemplateObject;
22 :    
23 :     use strict;
24 :     use Tracer;
25 :     use PageBuilder;
26 :     use FIG_CGI;
27 :     use FigWebServices::SeedComponents::Framework;
28 :    
29 :     =head1 Template Object Manager
30 :    
31 :     =head2 Introduction
32 :    
33 :     The template object manager is used to build HTML in the presence or absence of a
34 :     template. The constructor looks for a template and remembers whether or not
35 :     it found one. To add HTML to the object, you call the L</add> method with a
36 :     variable name and the HTML to add. The example below puts the results of
37 :     the C<build_html> method into the template C<$to> with the name C<frog>.
38 :    
39 :     $to->add(frog => build_html($thing));
40 :    
41 :     Once all the HTML is added, you call finish to generate the web page.
42 :    
43 :     print $to->finish();
44 :    
45 :     If no template exists, the HTML will be output in the order in which
46 :     it was added to the template object. If a template does exist, the
47 :     HTML assigned to each name will be substituted for the variable with
48 :     that name.
49 :    
50 :     Sometimes extra text is needed in raw mode. If you code
51 :    
52 :     $to->add($text);
53 :    
54 :     the text is discarded in template mode and accumulated in raw mode. If
55 :     you're doing complicated computation, you can get a faster result using
56 :     an IF construct.
57 :    
58 :     $to->add(build_html($data)) if $to->raw;
59 :    
60 :     This bypasses the call to C<build_html> unless it is necessary.
61 :    
62 :     The template facility used is the PERL C<HTML::Template> facility, so
63 :     anything that follows the format of that facility will work. The
64 :     most common use of the facility is simple variable substition. In
65 : parrello 1.4 the fragment below, the variable is named C<topic>.
66 : parrello 1.1
67 :     <p>This page tells how to do <TMPL_VAR NAME=TOPIC>.
68 :    
69 :     If the following call was made at some point prior to finishing
70 :    
71 :     $to->add(topic => "subsystem annotation");
72 :    
73 :     The result would be
74 :    
75 :     <p>This page tells how to do subsystem annotation.
76 :    
77 :     Almost all templates are stored in files. Some are stored in the server's
78 :     file system and some are stored on remote servers. Regardless of the
79 :     location, a template file name consists of a base name, a type, and
80 :     a request code. If no request code is specified, the template name
81 :     is I<base>C<_tmpl.>I<type>. If a request code is specified, the template name is
82 :     I<base>C<_tmpl_>I<request>C<.>I<type>. This allows the templates to
83 :     be tailored to different versions of the calling script.
84 :    
85 :     The following constructor starts the template for the protein page.
86 :    
87 :     my $to = TemplateObject->new($cgi, php => 'Protein', $cgi->param('request'));
88 :    
89 :     If the CGI object indicates Sprout is active, the template object will look
90 :     for a template file at the C<$FIG_Config::template_url> directory. If no
91 :     template URL is specified, it will look for the template file in the
92 :     C<$FIG_Config::fig/CGI/Html> directory. The template file is presumed to have
93 :     a type suffix of C<php>. If the template is coming from a web server, any
94 :     include files or other PHP commands will already have been executed by the time
95 :     the file reaches us. If the template is coming from the file system, the
96 :     suffix has no operational effect: the template file is read in unaltered.
97 :    
98 :     =cut
99 :    
100 :     #: Constructor TemplateObject->new();
101 :    
102 :     =head2 Public Methods
103 :    
104 :     =head3 new
105 :    
106 :     C<< my $to = FIG_CGI->new($cgi, $type => $name, $request); >>
107 :    
108 :     Construct a new template object for the current script.
109 :    
110 :     Currently, only Sprout uses templates.
111 :    
112 :     A template name consists of a base, a type, and a request code. If no
113 :     request code is specified, the template name is I<base>C<_tmpl.>I<type>.
114 :     If a request code is specified, the template name is
115 :     I<base>C<_tmpl_>I<request>C<.>I<type>. This allows the templates to be
116 :     tailored to different versions of the calling script.
117 :    
118 :     =over 4
119 :    
120 :     =item cgi
121 :    
122 :     CGI object for the current script.
123 :    
124 :     =item type
125 :    
126 :     Template type, usually either C<php> or C<html>. The template type is used as
127 :     the file name suffix.
128 :    
129 :     =item name
130 :    
131 :     Base name of the template.
132 :    
133 :     =item request (optional)
134 :    
135 :     Request code for the script. If specified, the request code is joined to the
136 :     base name to compute the template name.
137 :    
138 :     =back
139 :    
140 :     =cut
141 :    
142 :     sub new {
143 :     # Get the parameters.
144 :     my ($class, $cgi, $type, $name, $request) = @_;
145 :     # Declare the template name variable.
146 :     my $template = "";
147 :     # Check for Sprout mode.
148 :     if (is_sprout($cgi)) {
149 :     # Here we're in Sprout, so we have a template. First, we compute
150 :     # the template name.
151 :     my $requestPart = ($request ? "_$request" : "");
152 : parrello 1.4 $template = "${name}_tmpl$requestPart.$type";
153 : parrello 1.1 # Now we need to determine the template type and prefix the source location
154 :     # onto it.
155 :     if ($FIG_Config::template_url) {
156 :     $template = "$FIG_Config::template_url/$template";
157 :     } else {
158 :     $template = "<<$FIG_Config::fig/CGI/Html";
159 :     }
160 :     }
161 :     # Now $template is either a null string (FALSE) or the name of the
162 :     # template (TRUE). We are ready to create the return object.
163 : parrello 1.2 my $retVal = { template => $template,
164 :     cgi => $cgi,
165 :     };
166 : parrello 1.1 # Next we add the object that will be accepting the HTML strings.
167 :     if ($template) {
168 :     $retVal->{varHash} = {};
169 :     } else {
170 :     $retVal->{html} = [];
171 :     }
172 :     # Return the result.
173 :     bless $retVal, $class;
174 :     return $retVal;
175 :     }
176 :    
177 :     =head3 mode
178 :    
179 :     C<< my $flag = $to->mode(); >>
180 :    
181 :     Return TRUE if a template is active, else FALSE.
182 :    
183 :     =cut
184 :    
185 :     sub mode {
186 :     # Get the parameters.
187 :     my ($self) = @_;
188 :     # Return the result.
189 :     return ($self->{template} ? 1 : 0);
190 :     }
191 :    
192 :     =head3 raw
193 :    
194 :     C<< my $flag = $to->raw(); >>
195 :    
196 :     Return TRUE if we're accumulating raw HTML, else FALSE.
197 :    
198 :     =cut
199 :    
200 :     sub raw {
201 :     # Get the parameters.
202 :     my ($self) = @_;
203 :     # Return the result.
204 :     return ($self->{template} ? 0 : 1);
205 :     }
206 :    
207 :     =head3 add
208 :    
209 :     C<< $to->add($name => $html); >>
210 :    
211 :     or
212 :    
213 :     C<< $to->add($html); >>
214 :    
215 :     Add HTML to the template data using the specified name. If a template is in effect, the
216 :     data will be put into a variable hash. If raw HTML is being accumulated, the data will
217 :     be added to the end of the HTML list. In the second form (without the name), the
218 :     text is discarded in template mode and added to the HTML in raw mode.
219 :    
220 :     =over 4
221 :    
222 :     =item name (optional)
223 :    
224 :     Name of the variable to be replaced by the specified HTML. If omitted, the HTML is
225 :     discarded if we are in template mode.
226 :    
227 :     =item html
228 :    
229 :     HTML string to be put into the output stream. Note that if it is guaranteed that a template
230 :     is to be used, references to lists of text or hashes may also be passed in, depending on
231 :     the features used by the template.
232 :    
233 :     =back
234 :    
235 :     =cut
236 :    
237 :     sub add {
238 :     # Get the parameters.
239 :     my ($self, $name, $html) = @_;
240 :     # Adjust the parameters if no name was specified.
241 :     if (! defined($html)) {
242 :     $html = $name;
243 :     $name = "";
244 :     }
245 :     # Check the mode.
246 :     if ($self->mode) {
247 :     # Here we're using a template. We only proceed if a name was specified.
248 :     if ($name) {
249 :     $self->{varHash}->{$name} = $html;
250 :     }
251 :     } else {
252 :     # No template: we're just accumulating the HTML in a list.
253 :     push @{$self->{html}}, $html;
254 :     }
255 :     }
256 :    
257 : parrello 1.3 =head3 append
258 :    
259 :     C<< $to->append($name, $html); >>
260 :    
261 :     Append HTML to a named variable. Unlike L</add>, this method will not destroy a
262 :     variable's existing value; instead, it will concatenate the new data at the end of the
263 :     old.
264 :    
265 :     =over 4
266 :    
267 :     =item name
268 :    
269 :     Name of the variable to which the HTML text is to be appended.
270 :    
271 :     =item html
272 :    
273 :     HTML text to append.
274 :    
275 :     =back
276 :    
277 :     =cut
278 :    
279 :     sub append {
280 :     # Get the parameters.
281 :     my ($self, $name, $html) = @_;
282 :     # Check the mode.
283 :     if ($self->mode) {
284 :     # Template mode, so we check for the variable.
285 :     my $hash = $self->{varHash};
286 :     if (exists $hash->{$name}) {
287 :     $hash->{$name} .= $html;
288 :     } else {
289 :     $hash->{$name} = $html;
290 :     }
291 :     } else {
292 :     # Raw mode.
293 :     push @{$self->{html}}, $html;
294 :     }
295 :     }
296 :    
297 : parrello 1.1 =head3 titles
298 :    
299 :     C<< to->titles($parameters); >>
300 :    
301 :     If no template is in use, generate the plain SEED header. If a template is in
302 :     use, get the version, peg ID, and message of the day for use in the template.
303 :    
304 :     This subroutine provides a uniform method for starting a web page regardless
305 :     of mode.
306 :    
307 :     =over 4
308 :    
309 :     =item parameters
310 :    
311 :     Reference to a hash containing the heading parameters. These are as follows.
312 :    
313 : parrello 1.5 =over 8
314 : parrello 1.1
315 :     =item fig_object
316 :    
317 :     Fig-like object used to access the data store.
318 :    
319 :     =item peg_id
320 :    
321 :     ID of the current protein.
322 :    
323 :     =item table_style
324 :    
325 :     Style to use for tables.
326 :    
327 :     =item fig_disk
328 :    
329 :     Directory of the FIG disk.
330 :    
331 :     =item form_target
332 :    
333 :     Target script for most forms.
334 :    
335 :     =back
336 :    
337 :     =back
338 :    
339 :     =cut
340 :    
341 :     sub titles {
342 :     # Get the parameters.
343 :     my ($self, $parameters) = @_;
344 :     if ($self->{template}) {
345 :     # In template mode, we get useful stuff from the framework. First, the message
346 :     # of the day.
347 :     $self->add(motd => FigWebServices::SeedComponents::Framework::get_motd($parameters));
348 :     # Now the version.
349 :     $self->add(version =>
350 :     FigWebServices::SeedComponents::Framework::get_version({fig => $parameters->{fig_object},
351 :     fig_disk => $parameters->{fig_disk}}));
352 : parrello 1.2 # Next, the location tag.
353 :     $self->add(location_tag => $self->{cgi}->url());
354 : parrello 1.1 # Finally the protein (if any).
355 :     if (exists $parameters->{peg_id}) {
356 :     $self->add(feature_id => $parameters->{peg_id});
357 :     }
358 :     } else {
359 :     # No template, so we pull in the plain header.
360 :     $self->add(header => FigWebServices::SeedComponents::Framework::get_plain_header($parameters));
361 :     }
362 :     }
363 :    
364 :     =head3 finish
365 :    
366 :     C<< my $webPage = $to->finish(); >>
367 :    
368 :     Format the template information into a web page. The HTML passed in by the L</add> methods
369 :     is assembled into the proper form and returned to the caller.
370 :    
371 :     =cut
372 :    
373 :     sub finish {
374 :     # Get the parameters.
375 :     my ($self) = @_;
376 :     # Declare the return variable.
377 :     my $retVal;
378 :     # Check the mode.
379 :     if ($self->{template}) {
380 :     # Here we have to process a template.
381 :     $retVal = PageBuilder::Build($self->{template}, $self->{varHash}, "Html");
382 :     } else {
383 :     # Here we need to assemble raw HTML in sequence. First, we check for the
384 :     # closing HTML tags. If the last line is a body close, we only need to add
385 :     # the html close. If it's not a body close or an html close, we need to
386 :     # add both tags.
387 :     my @html = @{$self->{html}};
388 :     if ($html[$#html] =~ m!/body!i) {
389 :     push @html, "</html>";
390 :     } elsif ($html[$#html] !~ m!/html!i) {
391 :     push @html, "</body></html>";
392 :     }
393 :     # Join the lines together to make a page.
394 :     $retVal = join("\n", @html);
395 :     }
396 :     # Return the result.
397 :     return $retVal;
398 :     }
399 :    
400 :     1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3