1NAME
2 HTML::Template::Associate - Associate relevant packages with HTML::Template
3
4SYNOPSIS
5 #Example usage with FormValidator as the target
6
7 use CGI qw/:standard/;
8 use Data::FormValidator;
9 use HTML::Template;
10 use HTML::Template::Associate;
11
12 my $cgi = CGI->new;
13 #for testing purposes we can add some input to our cgi object
14 $cgi->param( 'fullname', 'John Doe' );
15 $cgi->param( 'phone', 6041112222 );
16 $cgi->param( 'email', 'invalid@email' );
17
18 my $input_profile = {
19 optional => [ qw( company fax country ) ],
20 required => [ qw( fullname phone email address city state zipcode ) ],
21 constraints => {
22 email => 'email',
23 fax => 'american_phone',
24 phone => 'american_phone',
25 zipcode => '/^\s*\d{5}(?:[-]\d{4})?\s*$/',
26 state => "state",
27 },
28 defaults => { country => "Canada" },
29 msgs => {
30 prefix=> 'error_',
31 missing => 'Not Here!',
32 invalid => 'Problematic!',
33 invalid_seperator => ' <br /> ',
34 format => 'ERROR: %s',
35 any_errors => 'some_errors',
36 }
37 };
38
39 my $validator = Data::FormValidator->new;
40 my $results = $validator->check ( scalar $cgi->Vars, $input_profile );
41
42 my $associate = HTML::Template::Associate->new( {
43 target => 'FormValidator',
44 results => $results,
45 extra_arguments => [ $validator ] #not needed but just illustrated
46 } );
47
48 my $template = HTML::Template->new(
49 filename => 'test.tmpl',
50 associate => [ $cgi, $associate ]
51 );
52
53 print $template->output;
54
55 #and in our test.tmpl file we could have
56
57 Valid Fields:<br>
58 <TMPL_LOOP NAME=VALID_FIELDS>
59 Field Name: <TMPL_VAR NAME=FIELD_NAME><br>
60 Field Value: <TMPL_VAR NAME=FIELD_VALUE><br>
61 </TMPL_LOOP>
62
63 Missing Fields:<br>
64 <TMPL_LOOP NAME=MISSING_FIELDS>
65 Field Name: <TMPL_VAR NAME=FIELD_NAME><br>
66 Field Value: <TMPL_VAR NAME=FIELD_VALUE><br>
67 </TMPL_LOOP>
68
69 <TMPL_IF NAME=INVALID_phone>
70 Phone: <TMPL_VAR NAME="phone"> you supplied is invalid.
71 </TMPL_IF>
72
73 <TMPL_IF NAME=MISSING_city>
74 City name is missing, please fix this.
75 </TMPL_IF>
76
77 <!-- We can also access our normal field names
78 since $cgi object was passed as associate as well -->
79
80 I think <TMPL_VAR NAME=country> is very big country.
81
82 <!-- Optional use of Data::FormValidator::Results msgs interface -->
83
84 Message Fields:
85
86 <TMPL_LOOP NAME=MSGS_FIELDS>
87 Field Name: <TMPL_VAR NAME=FIELD_NAME><br>
88 Field Value: <TMPL_VAR NAME=FIELD_VALUE><br>
89 </TMPL_LOOP>
90
91 <TMPL_IF NAME=MSGS_error_city>
92 Our default error message set in the profiling code is:
93 <TMPL_VAR NAME=MSGS_error_city>
94 </TMPL_IF>
95
96 #Example usage with DBI as the target
97 use DBI;
98 use HTML::Template;
99 use HTML::Template::Associate;
100
101 #initiliaze your $dbh ...
102
103 my $results_foo = $dbh->selectall_hashref (
104 'SELECT foo FROM bar WHERE baz = ?',
105 'foo_id',
106 {},
107 $baz
108 );
109
110 my $results_bar = $dbh->selectall_hashref (
111 'SELECT foo, bar FROM bar WHERE baz = ?',
112 [ 'foo_id', 'bar_id' ] ,
113 {},
114 $baz
115 );
116
117 my $results_moo = $dbh->selectrow_hashref ( 'SELECT x, y FROM z LIMIT 1' );
118
119 my @results_array = $dbh->selectrow_array ( 'SELECT x FROM z' );
120
121 my $associate = HTML::Template::Associate->new( {
122 target => 'DBI',
123 create => [ {
124 results => $results_foo,
125 name => 'my_loop',
126 type => 'selectall_hashref'
127 }, {
128 results => $results_bar,
129 name => 'my_other_loop',
130 type => 'selectall_hashref'
131 }, {
132 results => $results_moo,
133 type => 'selectrow_hashref',
134 name => 'my_params'
135 }, {
136 results => \@results_array,
137 type => 'selectrow_array',
138 name => 'my_array_params'
139 }
140 ]
141 } );
142
143 my $template = HTML::Template->new (
144 filename => 'test.tmpl',
145 associate => [ $associate ],
146 die_on_bad_params => 0
147 );
148
149 print $template->output();
150
151 #sample.tmpl
152
153 <!-- TMPL_LOOP NAME="my_loop" -->
154 Foo is:<!-- TMPL_VAR NAME="foo" -->
155 <!-- /TMPL_LOOP -->
156
157 <!-- TMPL_LOOP NAME="my_other_loop" -->
158 Foo is:<!-- TMPL_VAR NAME="foo" -->
159 Bar is:<!-- TMPL_VAR NAME="bar" -->
160 <!-- /TMPL_LOOP -->
161
162 x is:<!-- TMPL_VAR NAME="my_params.x" -->
163 y is:<!-- TMPL_VAR NAME="my_params.y" -->
164
165 x via $dbh->selectrow_array is:<!-- TMPL_VAR NAME="my_array_params.0 -->
166
167DESCRIPTION
168 HTML::Template::Associate bridges gap between HTML::Template and
169 other modules that can be used in conjunction with it to do something
170 useful together, like for example Data::FormValidator that can verify
171 form inputs.
172
173 The idea is that every associate object can map required data structure
174 onto the one which corresponds to the one found in HTML::Template.
175 The factory will then instantiate the target class and user can then make
176 it available to HTML::Template via associate argument during object
177 construction. The data structures then become automatically visible to
178 your templates.
179
180 This module is abstract class it provides no mapping functionality
181 whatsoever, but rather defines common interface to all associate
182 objects underneath it and acts as a object production factory.
183 You should however use this module whenever you wish to access a
184 concrete associate class that provides functionality you desire.
185
186USAGE
187 #where $results = Data::FormValidator::Results; for example
188 my $associate = HTML::Template::Associate->new( {
189 target => 'FormValidator',
190 results => $results
191 } );
192
193 Target is always last portion of your full class name, so if
194 you had HTML::Template::Associate::XYZ the target would be XYZ
195
196BUGS
197 Maybe. If you see any make sure you let me know.
198
199SUPPORT
200AUTHOR
201 Alex Pavlovic
202 alex.pavlovic@taskforce-1.com
203 http://www.taskforce-1.com
204
205COPYRIGHT
206 This program is free software; you can redistribute
207 it and/or modify it under the same terms as Perl itself.
208
209 The full text of the license can be found in the
210 LICENSE file included with this module.
211
212SEE ALSO
213 HTML::Template::Associate::FormValidator HTML::Template::Associate::DBI perl(1).
214
215 new
216 Usage : my $associate = HTML::Template::Associate->new ( $target_arguments );
217 Purpose : Constructs new Associate object
218 Returns : Associate instance
219 Argument : Refer to the target
220 Throws : Error in case target does not exist
221 Comments : None
222
223 param
224 Usage : my $MyParam = $associate->param('MyParam');
225 Purpose : Retrieves param in a form suitable for access by HTML::Template
226 Returns : Single param or arrays suitable for loops
227 Argument : Parameter name and optional value if setting it
228 Throws : Error in case subroutine was not implemented in concrete class
229 Comments : This subroutine should be redefined in concrete class
230
231 init
232 Usage : $self->init ( $params );
233 Purpose : Provides basic initiliazation for the target class
234 Returns : true or false depending on whether initilization was succesful
235 Argument : hash of parameters passed to factory during object construction
236 Throws : Error in case subroutine was not implemented in concrete class
237 Comments : This subroutine should be redefined in concrete class
238
239 error
240 Purpose : Used internally to die on errors
241
242