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

Annotation of /FigKernelPackages/TemplateObject.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (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 :     the fragment below, the variable is named Ctopic>.
66 :    
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 :     $template = "${name}_tmpl$request.$type";
153 :     # 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 :     my $retVal = { template => $template };
164 :     # Next we add the object that will be accepting the HTML strings.
165 :     if ($template) {
166 :     $retVal->{varHash} = {};
167 :     } else {
168 :     $retVal->{html} = [];
169 :     }
170 :     # Return the result.
171 :     bless $retVal, $class;
172 :     return $retVal;
173 :     }
174 :    
175 :     =head3 mode
176 :    
177 :     C<< my $flag = $to->mode(); >>
178 :    
179 :     Return TRUE if a template is active, else FALSE.
180 :    
181 :     =cut
182 :    
183 :     sub mode {
184 :     # Get the parameters.
185 :     my ($self) = @_;
186 :     # Return the result.
187 :     return ($self->{template} ? 1 : 0);
188 :     }
189 :    
190 :     =head3 raw
191 :    
192 :     C<< my $flag = $to->raw(); >>
193 :    
194 :     Return TRUE if we're accumulating raw HTML, else FALSE.
195 :    
196 :     =cut
197 :    
198 :     sub raw {
199 :     # Get the parameters.
200 :     my ($self) = @_;
201 :     # Return the result.
202 :     return ($self->{template} ? 0 : 1);
203 :     }
204 :    
205 :     =head3 add
206 :    
207 :     C<< $to->add($name => $html); >>
208 :    
209 :     or
210 :    
211 :     C<< $to->add($html); >>
212 :    
213 :     Add HTML to the template data using the specified name. If a template is in effect, the
214 :     data will be put into a variable hash. If raw HTML is being accumulated, the data will
215 :     be added to the end of the HTML list. In the second form (without the name), the
216 :     text is discarded in template mode and added to the HTML in raw mode.
217 :    
218 :     =over 4
219 :    
220 :     =item name (optional)
221 :    
222 :     Name of the variable to be replaced by the specified HTML. If omitted, the HTML is
223 :     discarded if we are in template mode.
224 :    
225 :     =item html
226 :    
227 :     HTML string to be put into the output stream. Note that if it is guaranteed that a template
228 :     is to be used, references to lists of text or hashes may also be passed in, depending on
229 :     the features used by the template.
230 :    
231 :     =back
232 :    
233 :     =cut
234 :    
235 :     sub add {
236 :     # Get the parameters.
237 :     my ($self, $name, $html) = @_;
238 :     # Adjust the parameters if no name was specified.
239 :     if (! defined($html)) {
240 :     $html = $name;
241 :     $name = "";
242 :     }
243 :     # Check the mode.
244 :     if ($self->mode) {
245 :     # Here we're using a template. We only proceed if a name was specified.
246 :     if ($name) {
247 :     $self->{varHash}->{$name} = $html;
248 :     }
249 :     } else {
250 :     # No template: we're just accumulating the HTML in a list.
251 :     push @{$self->{html}}, $html;
252 :     }
253 :     }
254 :    
255 :     =head3 titles
256 :    
257 :     C<< to->titles($parameters); >>
258 :    
259 :     If no template is in use, generate the plain SEED header. If a template is in
260 :     use, get the version, peg ID, and message of the day for use in the template.
261 :    
262 :     This subroutine provides a uniform method for starting a web page regardless
263 :     of mode.
264 :    
265 :     =over 4
266 :    
267 :     =item parameters
268 :    
269 :     Reference to a hash containing the heading parameters. These are as follows.
270 :    
271 :     =over 4
272 :    
273 :     =item fig_object
274 :    
275 :     Fig-like object used to access the data store.
276 :    
277 :     =item peg_id
278 :    
279 :     ID of the current protein.
280 :    
281 :     =item table_style
282 :    
283 :     Style to use for tables.
284 :    
285 :     =item fig_disk
286 :    
287 :     Directory of the FIG disk.
288 :    
289 :     =item form_target
290 :    
291 :     Target script for most forms.
292 :    
293 :     =back
294 :    
295 :     =back
296 :    
297 :     =cut
298 :    
299 :     sub titles {
300 :     # Get the parameters.
301 :     my ($self, $parameters) = @_;
302 :     if ($self->{template}) {
303 :     # In template mode, we get useful stuff from the framework. First, the message
304 :     # of the day.
305 :     $self->add(motd => FigWebServices::SeedComponents::Framework::get_motd($parameters));
306 :     # Now the version.
307 :     $self->add(version =>
308 :     FigWebServices::SeedComponents::Framework::get_version({fig => $parameters->{fig_object},
309 :     fig_disk => $parameters->{fig_disk}}));
310 :     # Finally the protein (if any).
311 :     if (exists $parameters->{peg_id}) {
312 :     $self->add(feature_id => $parameters->{peg_id});
313 :     }
314 :     } else {
315 :     # No template, so we pull in the plain header.
316 :     $self->add(header => FigWebServices::SeedComponents::Framework::get_plain_header($parameters));
317 :     }
318 :     }
319 :    
320 :     =head3 finish
321 :    
322 :     C<< my $webPage = $to->finish(); >>
323 :    
324 :     Format the template information into a web page. The HTML passed in by the L</add> methods
325 :     is assembled into the proper form and returned to the caller.
326 :    
327 :     =cut
328 :    
329 :     sub finish {
330 :     # Get the parameters.
331 :     my ($self) = @_;
332 :     # Declare the return variable.
333 :     my $retVal;
334 :     # Check the mode.
335 :     if ($self->{template}) {
336 :     # Here we have to process a template.
337 :     $retVal = PageBuilder::Build($self->{template}, $self->{varHash}, "Html");
338 :     } else {
339 :     # Here we need to assemble raw HTML in sequence. First, we check for the
340 :     # closing HTML tags. If the last line is a body close, we only need to add
341 :     # the html close. If it's not a body close or an html close, we need to
342 :     # add both tags.
343 :     my @html = @{$self->{html}};
344 :     if ($html[$#html] =~ m!/body!i) {
345 :     push @html, "</html>";
346 :     } elsif ($html[$#html] !~ m!/html!i) {
347 :     push @html, "</body></html>";
348 :     }
349 :     # Join the lines together to make a page.
350 :     $retVal = join("\n", @html);
351 :     }
352 :     # Return the result.
353 :     return $retVal;
354 :     }
355 :    
356 :     1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3