Whatpm/HTML/Serializer.pod

=head1 NAME

Whatpm::HTML::Serializer - HTML DOM Serializer

=head1 SYNOPSIS

  require Whatpm::HTML::Serializer;
  
  ## Serialize an HTML document
  my $html = Whatpm::HTML::Serializer->get_inner_html ($doc);
  ## NOTE: $html = $doc->inner_html is preferred.
  
  ## Serialize an HTML element
  my $html = Whatpm::HTML::Serializer->get_inner_html ($el);
  ## NOTE: $html = $el->inner_html is preferred.
  
  ## Serialize an HTML document fragment
  my $html = Whatpm::HTML::Serializer->get_inner_html ($df);

=head1 DESCRIPTION

The C<Whatpm::HTML::Serializer> module provides a function that
implements the fragment serialization algorithm of HTML5.  It can
be used to serialize a HTML C<Document> or C<Element> node into
an HTML document or fragment.

Note that the algorithm cannot be used to serialize an arbitrary 
DOM tree; an attempt to serialize a DOM that cannot be represented
in a static HTML document (fragment) will result in an invalid 
document or in a document representing different DOM tree.

For example, the DOM tree:

  +- Element |p|
       +- Element |ul|

... cannot be represented in HTML serialization.  The serialization
algorithm will generate an invalid HTML fragment:

  <p><ul></ul></p>

... which represents another DOM tree:

  +- Element |p|
  +- Element |ul|
  (with "invalid </p>" error)

... without raising any error or warning.  This is a limitation of
the HTML serialization format and the fragment serialization algorithm.

B<NOTE>: Usually you don't have to call this module directly,
since L<Message::DOM::Document> and L<Message::DOM::Element>
modules implement the C<inner_html> attribute for
DOM C<Document> and C<Element> nodes.

=head1 METHODS

=over 4

=item I<$html> = Whatpm::HTML::Serializer->get_inner_html (I<$node>, [I<$onerror>])

Serialize a node by the HTML fragment serialization algorithm.

=over 4

=item I<$node>

The node to serialize.  The node must be a DOM C<Document>,
C<DocumentFragment>, or C<Element> node.

=item I<$onerror>

A reference to C<CODE>, which will be invoked when an error occurs.
If the algorithm is required to raise an C<INVALID_STATE_ERR> error,
i.e. if the algorithm is faced to a C<Node> whose type is different
from any of ones supported by the algorithm, the C<CODE> is
invoked with that C<Node> as an argument.  It is expected for the
C<CODE> to raise an exception.  If no exception is raised,
the C<Node> is ignored for the purpose of the algorithm.

If I<$onerror> is omitted, an empty C<CODE> (which does nothing)
is assumed.

=item I<$html>

A C<SCALAR> reference to the result of the HTML fragment serialization 
algorithm.

=back

=back

=head1 SEE ALSO

Whatpm <http://suika.fam.cx/www/markup/html/whatpm/readme>.

HTML5 <http://whatwg.org/html5>.

manakai's L<Message::DOM::Document> and L<Message::DOM::Element>
modules are implementing the C<inner_html> attribute.

=head1 AUTHOR

Wakaba <w@suika.fam.cx>.

=head1 LICENSE

Copyright 2007 Wakaba <w@suika.fam.cx>

This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

=cut

## $Date: 2007/11/04 04:34:30 $
1	wakaba	1.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 $