4 use warnings FATAL => 'all';
6 use HTML::Zoom::ZConfig;
7 use HTML::Zoom::MatchWithoutFilter;
8 use HTML::Zoom::ReadFH;
9 use HTML::Zoom::Transform;
12 my ($class, $args) = @_;
14 $new->{zconfig} = HTML::Zoom::ZConfig->new($args->{zconfig}||{});
18 sub zconfig { shift->_self_or_new->{zconfig} }
21 ref($_[0]) ? $_[0] : $_[0]->new
25 bless({ %{$_[0]}, %{$_[1]} }, ref($_[0]));
29 my $self = shift->_self_or_new;
31 initial_events => $self->zconfig->parser->html_to_events($_[0])
36 my $self = shift->_self_or_new;
38 $self->from_html(do { local (@ARGV, $/) = ($filename); <> });
43 die "No events to build from - forgot to call from_html?"
44 unless $self->{initial_events};
45 my $sutils = $self->zconfig->stream_utils;
46 my $stream = $sutils->stream_from_array(@{$self->{initial_events}});
47 foreach my $filter_spec (@{$self->{filters}||[]}) {
48 $stream = HTML::Zoom::Transform->new({
49 selector => $filter_spec->[0],
50 filters => [ $filter_spec->[1] ],
51 zconfig => $self->zconfig,
52 })->apply_to_stream($stream);
53 #$stream = $sutils->wrap_with_filter($stream, @{$filter_spec});
59 HTML::Zoom::ReadFH->from_zoom(shift);
64 $self->zconfig->stream_utils->stream_to_array($self->to_stream);
69 my ($self, $code) = @_;
76 $self->zconfig->producer->html_from_stream($self->to_stream);
81 ref($self)->new($self)->from_html($self->to_html);
85 my $self = shift->_self_or_new;
86 my ($selector, $filter) = @_;
87 my $match = $self->parse_selector($selector);
89 filters => [ @{$self->{filters}||[]}, [ $match, $filter ] ]
94 my $self = shift->_self_or_new;
96 my $match = $self->parse_selector($selector);
97 return HTML::Zoom::MatchWithoutFilter->construct(
98 $self, $match, $self->zconfig->filter_builder,
102 # There's a bug waiting to happen here: if you do something like
104 # $zoom->select('.foo')
105 # ->remove_attribute(class => 'foo')
107 # ->well_anything_really
109 # the second action won't execute because it doesn't match anymore.
110 # Ideally instead we'd merge the match subs but that's more complex to
111 # implement so I'm deferring it for the moment.
115 die "Can't call ->then without a previous filter"
116 unless $self->{filters};
117 $self->select($self->{filters}->[-1][0]);
121 my ($self, $selector) = @_;
122 return $selector if ref($selector); # already a match sub
123 $self->zconfig->selector_parser->parse_selector($selector);
130 HTML::Zoom - selector based streaming template engine
136 my $template = <<HTML;
139 <title>Hello people</title>
142 <h1 id="greeting">Placeholder</h1>
145 <p>Name: <span class="name">Bob</span></p>
146 <p>Age: <span class="age">23</span></p>
148 <hr class="between" />
154 my $output = HTML::Zoom
155 ->from_html($template)
156 ->select('title, #greeting')->replace_content('Hello world & dog!')
157 ->select('#list')->repeat_content(
160 $_->select('.name')->replace_content('Matt')
161 ->select('.age')->replace_content('26')
164 $_->select('.name')->replace_content('Mark')
165 ->select('.age')->replace_content('0x29')
168 $_->select('.name')->replace_content('Epitaph')
169 ->select('.age')->replace_content('<redacted>')
172 { repeat_between => '.between' }
186 <title>Hello world & dog!</title>
189 <h1 id="greeting">Hello world & dog!</h1>
192 <p>Name: <span class="name">Matt</span></p>
193 <p>Age: <span class="age">26</span></p>
195 <hr class="between" />
197 <p>Name: <span class="name">Mark</span></p>
198 <p>Age: <span class="age">0x29</span></p>
200 <hr class="between" />
202 <p>Name: <span class="name">Epitaph</span></p>
203 <p>Age: <span class="age"><redacted></span></p>
213 is($output, $expect, 'Synopsis code works ok');
217 =head1 DANGER WILL ROBINSON
219 This is a 0.9 release. That means that I'm fairly happy the API isn't going
220 to change in surprising and upsetting ways before 1.0 and a real compatibility
221 freeze. But it also means that if it turns out there's a mistake the size of
222 a politician's ego in the API design that I haven't spotted yet there may be
223 a bit of breakage between here and 1.0. Hopefully not though. Appendages
224 crossed and all that.
226 Worse still, the rest of the distribution isn't documented yet. I'm sorry.
227 I suck. But lots of people have been asking me to ship this, docs or no, so
228 having got this class itself at least somewhat documented I figured now was
229 a good time to cut a first real release.
233 HTML::Zoom is a lazy, stream oriented, streaming capable, mostly functional,
234 CSS selector based semantic templating engine for HTML and HTML-like
237 Which is, on the whole, a bit of a mouthful. So let me step back a moment
238 and explain why you care enough to understand what I mean:
242 HTML::Zoom is the cure for JQuery envy. When your javascript guy pushes a
243 piece of data into a document by doing:
245 $('.username').replaceAll(username);
247 In HTML::Zoom one can write
249 $zoom->select('.username')->replace_content($username);
251 which is, I hope, almost as clear, hampered only by the fact that Zoom can't
252 assume a global document and therefore has nothing quite so simple as the
253 $() function to get the initial selection.
255 L<HTML::Zoom::SelectorParser> implements a subset of the JQuery selector
256 specification, and will continue to track that rather than the W3C standards
257 for the forseeable future on grounds of pragmatism. Also on grounds of their
258 spec is written in EN_US rather than EN_W3C, and I read the former much better.
260 I am happy to admit that it's very, very much a subset at the moment - see the
261 L<HTML::Zoom::SelectorParser> POD for what's currently there, and expect more
262 and more to be supported over time as we need it and patch it in.
264 =head2 CLEAN TEMPLATES
266 HTML::Zoom is the cure for messy templates. How many times have you looked at
269 <form action="/somewhere">
270 [% FOREACH field IN fields %]
271 <label for="[% field.id %]">[% field.label %]</label>
272 <input name="[% field.name %]" type="[% field.type %]" value="[% field.value %]" />
276 and despaired of the fact that neither the HTML structure nor the logic are
277 remotely easy to read? Fortunately, with HTML::Zoom we can separate the two
280 <form class="myform" action="/somewhere">
285 $zoom->select('.myform')->repeat_content([
286 map { my $field = $_; sub {
289 ->add_attribute( for => $field->{id} )
291 ->replace_content( $field->{label} )
294 ->add_attribute( name => $field->{name} )
296 ->add_attribute( type => $field->{type} )
298 ->add_attribute( value => $field->{value} )
303 This is, admittedly, very much not shorter. However, it makes it extremely
304 clear what's happening and therefore less hassle to maintain. Especially
305 because it allows the designer to fiddle with the HTML without cutting
306 himself on sharp ELSE clauses, and the developer to add available data to
307 the template without getting angle bracket cuts on sensitive parts.
309 Better still, HTML::Zoom knows that it's inserting content into HTML and
310 can escape it for you - the example template should really have been:
312 <form action="/somewhere">
313 [% FOREACH field IN fields %]
314 <label for="[% field.id | html %]">[% field.label | html %]</label>
315 <input name="[% field.name | html %]" type="[% field.type | html %]" value="[% field.value | html %]" />
319 and frankly I'll take slightly more code any day over *that* crawling horror.
321 (addendum: I pick on L<Template Toolkit|Template> here specifically because
322 it's the template system I hate the least - for text templating, I don't
323 honestly think I'll ever like anything except the next version of Template
324 Toolkit better - but HTML isn't text. Zoom knows that. Do you?)
326 =head2 PUTTING THE FUN INTO FUNCTIONAL
328 The principle of HTML::Zoom is to provide a reusable, functional container
329 object that lets you build up a set of transforms to be applied; every method
330 call you make on a zoom object returns a new object, so it's safe to do so
331 on one somebody else gave you without worrying about altering state (with
332 the notable exception of ->next for stream objects, which I'll come to later).
336 my $z2 = $z1->select('.name')->replace_content($name);
338 my $z3 = $z2->select('.title')->replace_content('Ms.');
340 each time produces a new Zoom object. If you want to package up a set of
341 transforms to re-use, HTML::Zoom provides an 'apply' method:
343 my $add_name = sub { $_->select('.name')->replace_content($name) };
345 my $same_as_z2 = $z1->apply($add_name);
347 =head2 LAZINESS IS A VIRTUE
349 HTML::Zoom does its best to defer doing anything until it's absolutely
350 required. The only point at which it descends into state is when you force
351 it to create a stream, directly by:
353 my $stream = $zoom->to_stream;
355 while (my $evt = $stream->next) {
356 # handle zoom event here
361 my $final_html = $zoom->to_html;
363 my $fh = $zoom->to_fh;
365 while (my $chunk = $fh->getline) {
369 Better still, the $fh returned doesn't create its stream until the first
370 call to getline, which means that until you call that and force it to be
371 stateful you can get back to the original stateless Zoom object via:
373 my $zoom = $fh->to_zoom;
375 which is exceedingly handy for filtering L<Plack> PSGI responses, among other
378 Because HTML::Zoom doesn't try and evaluate everything up front, you can
379 generally put things together in whatever order is most appropriate. This
382 my $start = HTML::Zoom->from_html($html);
384 my $zoom = $start->select('div')->replace_content('THIS IS A DIV!');
388 my $start = HTML::Zoom->select('div')->replace_content('THIS IS A DIV!');
390 my $zoom = $start->from_html($html);
392 will produce equivalent final $zoom objects, thus proving that there can be
393 more than one way to do it without one of them being a
394 L<bait and switch|Switch>.
396 =head2 STOCKTON TO DARLINGTON UNDER STREAM POWER
398 HTML::Zoom's execution always happens in terms of streams under the hood
399 - that is, the basic pattern for doing anything is -
401 my $stream = get_stream_from_somewhere
403 while (my ($evt) = $stream->next) {
404 # do something with the event
407 More importantly, all selectors and filters are also built as stream
408 operations, so a selector and filter pair is effectively:
412 my $next_evt = $self->parent_stream->next;
413 if ($self->selector_matches($next_evt)) {
414 return $self->apply_filter_to($next_evt);
420 Internally, things are marginally more complicated than that, but not enough
421 that you as a user should normally need to care.
423 In fact, an HTML::Zoom object is mostly just a container for the relevant
424 information from which to build the final stream that does the real work. A
425 stream built from a Zoom object is a stream of events from parsing the
426 initial HTML, wrapped in a filter stream per selector/filter pair provided
429 The upshot of this is that the application of filters works just as well on
430 streams as on the original Zoom object - in fact, when you run a
431 L</repeat_content> operation your subroutines are applied to the stream for
432 that element of the repeat, rather than constructing a new zoom per repeat
437 $_->select('div')->replace_content('I AM A DIV!');
439 works on both HTML::Zoom objects themselves and HTML::Zoom stream objects and
440 shares sufficient of the implementation that you can generally forget the
441 difference - barring the fact that a stream already has state attached so
442 things like to_fh are no longer available.
444 =head2 POP! GOES THE WEASEL
446 ... and by Weasel, I mean layout.
448 HTML::Zoom's filehandle object supports an additional event key, 'flush',
449 that is transparent to the rest of the system but indicates to the filehandle
450 object to end a getline operation at that point and return the HTML so far.
452 This means that in an environment where streaming output is available, such
453 as a number of the L<Plack> PSGI handlers, you can add the flush key to an
454 event in order to ensure that the HTML generated so far is flushed through
455 to the browser right now. This can be especially useful if you know you're
456 about to call a web service or a potentially slow database query or similar
457 to ensure that at least the header/layout of your page renders now, improving
458 perceived user responsiveness while your application waits around for the
461 This is currently exposed by the 'flush_before' option to the collect filter,
462 which incidentally also underlies the replace and repeat filters, so to
463 indicate we want this behaviour to happen before a query is executed we can
464 write something like:
466 $zoom->select('.item')->repeat(sub {
467 if (my $row = $db_thing->next) {
468 return sub { $_->select('.item-name')->replace_content($row->name) }
472 }, { flush_before => 1 });
474 which should have the desired effect given a sufficiently lazy $db_thing (for
475 example a L<DBIx::Class::ResultSet> object).
477 =head2 A FISTFUL OF OBJECTS
479 At the core of an HTML::Zoom system lurks an L<HTML::Zoom::ZConfig> object,
480 whose purpose is to hang on to the various bits and pieces that things need
481 so that there's a common way of accessing shared functionality.
483 Were I a computer scientist I would probably call this an "Inversion of
484 Control" object - which you'd be welcome to google to learn more about, or
485 you can just imagine a computer scientist being suspended upside down over
486 a pit. Either way works for me, I'm a pure maths grad.
488 The ZConfig object hangs on to one each of the following for you:
492 =item * An HTML parser, normally L<HTML::Zoom::Parser::BuiltIn>
494 =item * An HTML producer (emitter), normally L<HTML::Zoom::Producer::BuiltIn>
496 =item * An object to build event filters, normally L<HTML::Zoom::FilterBuilder>
498 =item * An object to parse CSS selectors, normally L<HTML::Zoom::SelectorParser>
500 =item * An object to build streams, normally L<HTML::Zoom::StreamUtils>
504 In theory you could replace any of these with anything you like, but in
505 practice you're probably best restricting yourself to subclasses, or at
506 least things that manage to look like the original if you squint a bit.
508 If you do something more clever than that, or find yourself overriding things
509 in your ZConfig a lot, please please tell us about it via one of the means
510 mentioned under L</SUPPORT>.
512 =head2 SEMANTIC DIDACTIC
514 Some will argue that overloading CSS selectors to do data stuff is a terrible
515 idea, and possibly even a step towards the "Concrete Javascript" pattern
516 (which I abhor) or Smalltalk's Morphic (which I ignore, except for the part
517 where it keeps reminding me of the late, great Tony Hart's plasticine friend).
519 To which I say, "eh", "meh", and possibly also "feh". If it really upsets
520 you, either use extra classes for this (and remove them afterwards) or
521 use special fake elements or, well, honestly, just use something different.
522 L<Template::Semantic> provides a similar idea to zoom except using XPath
523 and XML::LibXML transforms rather than a lightweight streaming approach -
524 maybe you'd like that better. Or maybe you really did want
525 L<Template Toolkit|Template> after all. It is still damn good at what it does,
528 So far, however, I've found that for new sites the designers I'm working with
529 generally want to produce nice semantic HTML with classes that represent the
530 nature of the data rather than the structure of the layout, so sharing them
531 as a common interface works really well for us.
533 In the absence of any evidence that overloading CSS selectors has killed
534 children or unexpectedly set fire to grandmothers - and given microformats
535 have been around for a while there's been plenty of opportunity for
536 octagenarian combustion - I'd suggest you give it a try and see if you like it.
538 =head2 GET THEE TO A SUMMARY!
542 HTML::Zoom is a lazy, stream oriented, streaming capable, mostly functional,
543 CSS selector based semantic templating engine for HTML and HTML-like
546 But I said that already. Although hopefully by now you have some idea what I
547 meant when I said it. If you didn't have any idea the first time. I mean, I'm
548 not trying to call you stupid or anything. Just saying that maybe it wasn't
549 totally obvious without the explanation. Or something.
553 Maybe we should just move on to the method docs.
559 my $zoom = HTML::Zoom->new;
561 my $zoom = HTML::Zoom->new({ zconfig => $zconfig });
563 Create a new empty Zoom object. You can optionally pass an
564 L<HTML::Zoom::ZConfig> instance if you're trying to override one or more of
565 the default components.
567 This method isn't often used directly since several other methods can also
568 act as constructors, notable L</select> and L</from_html>
572 my $zconfig = $zoom->zconfig;
574 Retrieve the L<HTML::Zoom::ZConfig> instance used by this Zoom object. You
575 shouldn't usually need to call this yourself.
579 my $zoom = HTML::Zoom->from_html($html);
581 my $z2 = $z1->from_html($html);
583 Parses the HTML using the current zconfig's parser object and returns a new
584 zoom instance with that as the source HTML to be transformed.
588 my $zoom = HTML::Zoom->from_file($file);
590 my $z2 = $z1->from_file($file);
592 Convenience method - slurps the contents of $file and calls from_html with it.
596 my $stream = $zoom->to_stream;
598 while (my ($evt) = $stream->next) {
601 Creates a stream, starting with a stream of the events from the HTML supplied
602 via L</from_html> and then wrapping it in turn with each selector+filter pair
603 that have been applied to the zoom object.
607 my $fh = $zoom->to_fh;
609 call_something_expecting_a_filehandle($fh);
611 Returns an L<HTML::Zoom::ReadFH> instance that will create a stream the first
612 time its getline method is called and then return all HTML up to the next
613 event with 'flush' set.
615 You can pass this filehandle to compliant PSGI handlers (and probably most
622 Runs the zoom object's transforms without doing anything with the results.
624 Normally used to get side effects of a zoom run - for example when using
625 L<HTML::Zoom::FilterBuilder/collect> to slurp events for scraping or layout.
629 my $z2 = $z1->apply(sub {
630 $_->select('div')->replace_content('I AM A DIV!') })
633 Sets $_ to the zoom object and then runs the provided code. Basically syntax
634 sugar, the following is entirely equivalent:
637 shift->select('div')->replace_content('I AM A DIV!') })
640 my $z2 = $sub->($z1);
644 my $html = $zoom->to_html;
646 Runs the zoom processing and returns the resulting HTML.
650 my $z2 = $z1->memoize;
652 Creates a new zoom whose source HTML is the results of the original zoom's
653 processing. Effectively syntax sugar for:
655 my $z2 = HTML::Zoom->from_html($z1->to_html);
657 but preserves your L<HTML::Zoom::ZConfig> object.
661 my $zoom = HTML::Zoom->with_filter(
662 'div', $filter_builder->replace_content('I AM A DIV!')
665 my $z2 = $z1->with_filter(
666 'div', $filter_builder->replace_content('I AM A DIV!')
669 Lower level interface than L</select> to adding filters to your zoom object.
671 In normal usage, you probably don't need to call this yourself.
675 my $zoom = HTML::Zoom->select('div')->replace_content('I AM A DIV!');
677 my $z2 = $z1->select('div')->replace_content('I AM A DIV!');
679 Returns an intermediary object of the class L<HTML::Zoom::MatchWithoutFilter>
680 on which methods of your L<HTML::Zoom::FilterBuilder> object can be called.
682 In normal usage you should generally always put the pair of method calls
683 together; the intermediary object isn't designed or expected to stick around.
687 my $z2 = $z1->select('div')->add_attribute(class => 'spoon')
689 ->replace_content('I AM A DIV!');
691 Re-runs the previous select to allow you to chain actions together on the
694 =head2 parse_selector
696 my $matcher = $zoom->parse_selector('div');
698 Used by L</select> and L</with_filter> to invoke the current
699 L<HTML::Zoom::SelectorParser> object to create a matcher object (currently
700 a coderef but this is an implementation detail) for that selector.
702 In normal usage, you probably don't need to call this yourself.