/[suikacvs]/markup/html/whatpm/Whatpm/HTML/Serializer.pod
Suika

Contents of /markup/html/whatpm/Whatpm/HTML/Serializer.pod

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (show annotations) (download)
Sun Nov 11 04:59:36 2007 UTC (17 years, 8 months ago) by wakaba
Branch: MAIN
CVS Tags: HEAD
++ ChangeLog	11 Nov 2007 04:59:27 -0000
2007-11-11  Wakaba  <wakaba@suika.fam.cx>

	* readme.en.html: Link to |Whatpm::HTML::Serializer|.

++ whatpm/Whatpm/ChangeLog	11 Nov 2007 04:59:14 -0000
2007-11-11  Wakaba  <wakaba@suika.fam.cx>

	* HTML.pod (get_inner_html): Removed.

	* Makefile (HTML-all, HTML-clean): New.

2007-11-11  Wakaba  <wakaba@suika.fam.cx>

	* HTML.pm.src (get_inner_html): Removed (moved to HTML/Serializer.pm).

++ whatpm/Whatpm/HTML/ChangeLog	11 Nov 2007 04:58:48 -0000
2007-11-11  Wakaba  <wakaba@suika.fam.cx>

	* Serializer.pod: New file.

	* Makefile: New file.

2007-11-11  Wakaba  <wakaba@suika.fam.cx>

	* Serializer.pm: New module (split from ../HTML.pm.src).

2007-11-11  Wakaba  <wakaba@suika.fam.cx>

	* ChangeLog: New file.

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 $

admin@suikawiki.org
ViewVC Help
Powered by ViewVC 1.1.24