1 |
=head1 NAME |
2 |
|
3 |
Whatpm::HTML::Serializer - HTML DOM Serializer |
4 |
|
5 |
=head1 SYNOPSIS |
6 |
|
7 |
require Whatpm::HTML::Serializer; |
8 |
|
9 |
## Serialize an HTML document |
10 |
my $html = Whatpm::HTML::Serializer->get_inner_html ($doc); |
11 |
## NOTE: $html = $doc->inner_html is preferred. |
12 |
|
13 |
## Serialize an HTML element |
14 |
my $html = Whatpm::HTML::Serializer->get_inner_html ($el); |
15 |
## NOTE: $html = $el->inner_html is preferred. |
16 |
|
17 |
## Serialize an HTML document fragment |
18 |
my $html = Whatpm::HTML::Serializer->get_inner_html ($df); |
19 |
|
20 |
=head1 DESCRIPTION |
21 |
|
22 |
The C<Whatpm::HTML::Serializer> module provides a function that |
23 |
implements the fragment serialization algorithm of HTML5. It can |
24 |
be used to serialize a HTML C<Document> or C<Element> node into |
25 |
an HTML document or fragment. |
26 |
|
27 |
Note that the algorithm cannot be used to serialize an arbitrary |
28 |
DOM tree; an attempt to serialize a DOM that cannot be represented |
29 |
in a static HTML document (fragment) will result in an invalid |
30 |
document or in a document representing different DOM tree. |
31 |
|
32 |
For example, the DOM tree: |
33 |
|
34 |
+- Element |p| |
35 |
+- Element |ul| |
36 |
|
37 |
... cannot be represented in HTML serialization. The serialization |
38 |
algorithm will generate an invalid HTML fragment: |
39 |
|
40 |
<p><ul></ul></p> |
41 |
|
42 |
... which represents another DOM tree: |
43 |
|
44 |
+- Element |p| |
45 |
+- Element |ul| |
46 |
(with "invalid </p>" error) |
47 |
|
48 |
... without raising any error or warning. This is a limitation of |
49 |
the HTML serialization format and the fragment serialization algorithm. |
50 |
|
51 |
B<NOTE>: Usually you don't have to call this module directly, |
52 |
since L<Message::DOM::Document> and L<Message::DOM::Element> |
53 |
modules implement the C<inner_html> attribute for |
54 |
DOM C<Document> and C<Element> nodes. |
55 |
|
56 |
=head1 METHODS |
57 |
|
58 |
=over 4 |
59 |
|
60 |
=item I<$html> = Whatpm::HTML::Serializer->get_inner_html (I<$node>, [I<$onerror>]) |
61 |
|
62 |
Serialize a node by the HTML fragment serialization algorithm. |
63 |
|
64 |
=over 4 |
65 |
|
66 |
=item I<$node> |
67 |
|
68 |
The node to serialize. The node must be a DOM C<Document>, |
69 |
C<DocumentFragment>, or C<Element> node. |
70 |
|
71 |
=item I<$onerror> |
72 |
|
73 |
A reference to C<CODE>, which will be invoked when an error occurs. |
74 |
If the algorithm is required to raise an C<INVALID_STATE_ERR> error, |
75 |
i.e. if the algorithm is faced to a C<Node> whose type is different |
76 |
from any of ones supported by the algorithm, the C<CODE> is |
77 |
invoked with that C<Node> as an argument. It is expected for the |
78 |
C<CODE> to raise an exception. If no exception is raised, |
79 |
the C<Node> is ignored for the purpose of the algorithm. |
80 |
|
81 |
If I<$onerror> is omitted, an empty C<CODE> (which does nothing) |
82 |
is assumed. |
83 |
|
84 |
=item I<$html> |
85 |
|
86 |
A C<SCALAR> reference to the result of the HTML fragment serialization |
87 |
algorithm. |
88 |
|
89 |
=back |
90 |
|
91 |
=back |
92 |
|
93 |
=head1 SEE ALSO |
94 |
|
95 |
Whatpm <http://suika.fam.cx/www/markup/html/whatpm/readme>. |
96 |
|
97 |
HTML5 <http://whatwg.org/html5>. |
98 |
|
99 |
manakai's L<Message::DOM::Document> and L<Message::DOM::Element> |
100 |
modules are implementing the C<inner_html> attribute. |
101 |
|
102 |
=head1 AUTHOR |
103 |
|
104 |
Wakaba <w@suika.fam.cx>. |
105 |
|
106 |
=head1 LICENSE |
107 |
|
108 |
Copyright 2007 Wakaba <w@suika.fam.cx> |
109 |
|
110 |
This library is free software; you can redistribute it |
111 |
and/or modify it under the same terms as Perl itself. |
112 |
|
113 |
=cut |
114 |
|
115 |
## $Date: 2007/11/04 04:34:30 $ |