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	=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 $