File Coverage

blib/lib/Template/Flute.pm
Criterion Covered Total %
statement 19 21 90.4
branch n/a
condition n/a
subroutine 7 7 100.0
pod n/a
total 26 28 92.8


line stmt bran cond sub pod time code
1             package Template::Flute;
2              
3 1     1   13678 use strict;
  1         2  
  1         25  
4 1     1   3 use warnings;
  1         1  
  1         22  
5              
6 1     1   3 use Carp;
  1         4  
  1         62  
7 1     1   455 use Module::Runtime qw/use_module/;
  1         1241  
  1         4  
8 1     1   37 use Scalar::Util qw/blessed/;
  1         1  
  1         58  
9 1     1   352 use Template::Flute::Utils;
  1         1  
  1         22  
10 1     1   356 use Template::Flute::Specification::XML;
  0            
  0            
11             use Template::Flute::HTML;
12             use Template::Flute::Iterator;
13             use Template::Flute::Iterator::Cache;
14             use Template::Flute::Increment;
15             use Template::Flute::Pager;
16             use Template::Flute::Paginator;
17             use Template::Flute::Types -types;
18              
19             use Moo;
20             use namespace::clean;
21              
22             =head1 NAME
23              
24             Template::Flute - Modern designer-friendly HTML templating Engine
25              
26             =head1 VERSION
27              
28             Version 0.023
29              
30             =cut
31              
32             our $VERSION = '0.023';
33              
34             =head1 SYNOPSIS
35              
36             use Template::Flute;
37              
38             my ($cart, $flute, %values);
39              
40             $cart = [{...},{...}];
41             $values{cost} = ...
42              
43             $flute = new Template::Flute(specification_file => 'cart.xml',
44             template_file => 'cart.html',
45             iterators => {cart => $cart},
46             values => \%values,
47             autodetect => {
48             disable => [qw/Foo::Bar/],
49             }
50             );
51              
52             print $flute->process();
53              
54             =head1 DESCRIPTION
55              
56             Template::Flute enables you to completely separate web design and programming
57             tasks for dynamic web applications.
58              
59             Templates are designed to be designer-friendly; there's no inline code or mini
60             templating language for your designers to learn - instead, standard HTML and CSS
61             classes are used, leading to HTML that can easily be understood and edited by
62             WYSIWYG editors and hand-coding designers alike.
63              
64             An example is easier than a wordy description:
65              
66             Given the following template snippet:
67              
68            
Mr A Test
69            
someone@example.com
70              
71             and the following specification:
72              
73            
74            
75            
76            
77              
78             Processing the above as follows:
79              
80             $flute = Template::Flute->new(
81             template_file => 'template.html',
82             specification_file => 'spec.xml',
83             );
84             $flute->set_values({
85             customer_name => 'Bob McTest',
86             email => 'bob@example.com',
87             });;
88             print $flute->process;
89              
90             The resulting output would be:
91              
92            
Bob McTest
93            
94              
95              
96             In other words, rather than including a templating language within your
97             templates which your designers must master and which could interfere with
98             previews in WYSIWYG tools, CSS selectors in the template are tied to your
99             data structures or objects by a specification provided by the programmer.
100              
101              
102             =head2 Workflow
103              
104             The easiest way to use Template::Flute is to pass all necessary parameters to
105             the constructor and call the process method to generate the HTML.
106              
107             You can also break it down in separate steps:
108              
109             =over 4
110              
111             =item 1. Parse specification
112              
113             Parse specification based on your specification format (e.g with
114             L or L.).
115              
116             $xml_spec = new Template::Flute::Specification::XML;
117             $spec = $xml_spec->parse(q{
118            
119            
120            
121            
122            
123            
124             });
125              
126             =item 2. Parse template
127              
128             Parse template with L object.
129              
130             $template = new Template::Flute::HTML;
131             $template->parse(q{
132            
133             Cart Example
134            
135            
136            
137            
138             Name
139             Quantity
140             Price
141            
142            
143             Sample Book
144            
145             $1
146            
147            
Total
148            
149            
150             $10
151            
152            
153             },
154             $spec);
155              
156             =item 3. Produce HTML output
157              
158             $flute = new Template::Flute(template => $template,
159             iterators => {cart => $cart},
160             values => {cost => '84.94'});
161             $flute->process();
162              
163             =back
164              
165             =head1 CONSTRUCTOR
166              
167             =head2 new
168              
169             Create a Template::Flute object with the following parameters:
170              
171             =over 4
172              
173             =item specification_file
174              
175             Specification file name.
176              
177             =item specification_parser
178              
179             Select specification parser. This can be either the full class name
180             like C or the last part for classes residing
181             in the Template::Flute::Specification namespace.
182              
183             =item specification
184              
185             Specification object or specification as string.
186              
187             =item template_file
188              
189             HTML template file.
190              
191             =item template
192              
193             L object or template as string.
194              
195             =item filters
196              
197             Hash reference of filter functions.
198              
199             =item i18n
200              
201             L object.
202              
203             =item translate_attributes
204              
205             An arrayref of attribute names to translate. If the name has a dot, it
206             is interpreted as tagname + attribute, so C" will
207             unconditionally translate all the placeholders, while
208             C only the placeholder found on the input tag.
209              
210             Additional dotted values compose conditions for attributes. E.g.
211             C means all the value attributes with
212             attribute C set to C.
213              
214             Defaults to C<['input.value.type.submit', 'placeholder']>
215              
216             =item iterators
217              
218             Hash references of iterators.
219              
220             =item values
221              
222             Hash reference of values to be used by the process method.
223              
224             =item auto_iterators
225              
226             Builds iterators automatically from values.
227              
228             =item autodetect
229              
230             A configuration option. It should be an hashref with a key C
231             and a value with an arrayref with a list of B for objects
232             which should be considered plain hashrefs instead. Example:
233              
234             my $flute = Template::Flute->new(....
235             autodetect => { disable => [qw/My::Object/] },
236             ....
237             );
238              
239             Doing so, if you pass a value holding a C object, and you have a specification with something like this:
240              
241            
242            
243            
244              
245             The value will be C<$object->{method}>, not C<$object->$method>.
246              
247             The object is checked with C.
248              
249             Classical example: C.
250              
251             =item uri
252              
253             Base URI for your template. This adjusts the links in the HTML tags
254             C, C, C, C and C