Source

p5-html-html5-dom / lib / HTML / HTML5 / DOM.pod

=head1 NAME

HTML::HTML5::DOM - implementation of the HTML5 DOM on top of XML::LibXML

=head1 SYNOPSIS

 use HTML::HTML5::DOM;
 
 # Here $doc is an XML::LibXML::Document...
 my $doc = HTML::HTML5::Parser->load_html(location => 'my.html');
 
 # This upgrades it to an HTML::HTML5::DOM::HTMLDocument...
 XML::LibXML::Augment->rebless($doc);
 
 # What's the page title?
 warn $doc->getElementsByTagName('title')->get_index(1)->text;
 
 # Let's submit the first form on the page...
 my $forms = $doc->getElementsByTagName('form');
 $forms->get_index(1)->submit;

=head1 DESCRIPTION

HTML::HTML5::DOM is a layer on top of XML::LibXML which provides a number
of additional classes and methods for elements. Because it wraps almost
every XML::LibXML method, it is not as fast as using XML::LibXML directly
(which is an XS module), but it is more convenient.

=head2 DOM Support

HTML::HTML5::DOM implements those parts of the HTML5 DOM which are
convenient to do so, and also supports a lot of the pre-HTML5 DOM which
was obsoleted by the HTML5 spec. Additionally a number of DOM extensions
(methods prefixed with C<p5_>) are provided.

DOM events and event handlers (e.g. C<onclick>) are not supported, and
are unlikely to be supported in the foreseeable future.

The CSS bits of DOM are not supported, but may be in the future.

=head2 Perl specifics

DOM attributes are typically implemented as get/set/clear methods. For
example:

  warn $my_div->id;      # get
  $my_div->id($new_id);  # set
  $my_div->id(undef);    # clear

Methods which return a list usually return a normal Perl list when called
in list context, and an XML::LibXML::NodeList (or a subclass of that) when
called in list context.

Methods that return a URI generally return one blessed into the L<URI>
class.

Methods that return a datetime, generally return one blessed into the
L<DateTime> class.

Methods that result in hypertext navigation (e.g. clicking a link or
submitting a form) generally return a L<Web::Magic> object (which is
basically an HTTP request waiting to happen).

The standard Perl C<isa> method is overridden to support two additional
calling styles:

  $elem->isa( 'h1' );                 # element tag name
  $elem->isa( -HTMLHeadingElement );  # DOM interface name

=head2 HTML::HTML5::DOM class methods

While most of the interesting stuff is in L<HTML::HTML5::DOM::HTMLElement>
and other classes like that, the HTML::HTML5::DOM package itself provides a
handful of methods of its own.

=over

=item * C<< XHTML_NS >>

Constant. The XHTML namespace URI as a string.

=item * C<< getDOMImplementation >>

Gets a singleton object blessed into the HTML::HTML5::DOM class.

=item * C<< hasFeature >>

Given a feature and version, returns true if the feature is supported.

  my $impl = HTML::HTML5::DOM->getDOMImplementation;
  if ($impl->hasFeature('Core', '2.0')) {
    # ... do stuff
  }

=item * C<< getFeature >>

Given a feature and version, returns an HTML::HTML5::DOMutil::Feature object.

=item * C<< registerFeature >>

Experimental method to extend HTML::HTML5::DOM.

  my $monkey = HTML::HTML5::DOMutil::Feature->new(Monkey => '1.0');
  $monkey->add_sub(
    HTMLElement => 'talk',
    sub { print "screech!\n" },
  );
  $impl->registerFeature($monkey);
  
  $element->talk if $impl->hasFeature(Monkey => '1.0');

=item * C<< parse >>

Given a file handle, file name or URL (as a string or L<URI> object),
parses the file, returning an L<HTML::HTML5::DOM::HTMLDocument> object.

This function uses HTML::HTML5::Parser but you can alternatively use
XML::LibXML's XML parser:

 my $dom = HTML::HTML5::DOM->parse($fh, using => 'libxml');

=item * C<< parseString >>

As per C<parse>, but parses a string.

=item * C<< createDocument >>

Returns an HTML::HTML5::DOM::HTMLDocument representing a blank page.

=item * C<< createDocumentType >>

Given a qualified name, public identifier (which might be undef) and system
identifier (also perhaps undef), returns a doctype tag.

This is currently returned as a string, but in an ideal world would be an
L<XML::LibXML::Dtd> object.

=back

=head1 BUGS

L<http://rt.cpan.org/Dist/Display.html?Queue=HTML-HTML5-DOM>.

=head1 SEE ALSO

L<HTML::HTML5::DOM::ReleaseNotes>.

=head2 General DOM information

B<HTML5 DOM Specifications:>
L<http://www.w3.org/TR/domcore/>,
L<http://www.w3.org/TR/html5/index.html#interfaces>.

B<Pre-HTML5 DOM Specifications:>
L<http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html>
L<http://www.w3.org/TR/DOM-Level-2-HTML/html.html>.

=head2 Other packages in this distribution

=over

=item * L<HTML::HTML5::DOM::HTMLAnchorElement>

=item * L<HTML::HTML5::DOM::HTMLAreaElement>

=item * L<HTML::HTML5::DOM::HTMLAudioElement>

=item * L<HTML::HTML5::DOM::HTMLBRElement>

=item * L<HTML::HTML5::DOM::HTMLBaseElement>

=item * L<HTML::HTML5::DOM::HTMLBodyElement>

=item * L<HTML::HTML5::DOM::HTMLButtonElement>

=item * L<HTML::HTML5::DOM::HTMLCanvasElement>

=item * L<HTML::HTML5::DOM::HTMLCollection>

=item * L<HTML::HTML5::DOM::HTMLCommandElement>

=item * L<HTML::HTML5::DOM::HTMLDListElement>

=item * L<HTML::HTML5::DOM::HTMLDataListElement>

=item * L<HTML::HTML5::DOM::HTMLDetailsElement>

=item * L<HTML::HTML5::DOM::HTMLDivElement>

=item * L<HTML::HTML5::DOM::HTMLDocument>

=item * L<HTML::HTML5::DOM::HTMLElement>

=item * L<HTML::HTML5::DOM::HTMLEmbedElement>

=item * L<HTML::HTML5::DOM::HTMLFieldSetElement>

=item * L<HTML::HTML5::DOM::HTMLFormControlsCollection>

=item * L<HTML::HTML5::DOM::HTMLFormElement>

=item * L<HTML::HTML5::DOM::HTMLHRElement>

=item * L<HTML::HTML5::DOM::HTMLHeadElement>

=item * L<HTML::HTML5::DOM::HTMLHeadingElement>

=item * L<HTML::HTML5::DOM::HTMLHtmlElement>

=item * L<HTML::HTML5::DOM::HTMLIFrameElement>

=item * L<HTML::HTML5::DOM::HTMLImageElement>

=item * L<HTML::HTML5::DOM::HTMLInputElement>

=item * L<HTML::HTML5::DOM::HTMLKeygenElement>

=item * L<HTML::HTML5::DOM::HTMLLIElement>

=item * L<HTML::HTML5::DOM::HTMLLabelElement>

=item * L<HTML::HTML5::DOM::HTMLLegendElement>

=item * L<HTML::HTML5::DOM::HTMLLinkElement>

=item * L<HTML::HTML5::DOM::HTMLMapElement>

=item * L<HTML::HTML5::DOM::HTMLMediaElement>

=item * L<HTML::HTML5::DOM::HTMLMenuElement>

=item * L<HTML::HTML5::DOM::HTMLMetaElement>

=item * L<HTML::HTML5::DOM::HTMLMeterElement>

=item * L<HTML::HTML5::DOM::HTMLModElement>

=item * L<HTML::HTML5::DOM::HTMLOListElement>

=item * L<HTML::HTML5::DOM::HTMLObjectElement>

=item * L<HTML::HTML5::DOM::HTMLOptGroupElement>

=item * L<HTML::HTML5::DOM::HTMLOptionElement>

=item * L<HTML::HTML5::DOM::HTMLOutputElement>

=item * L<HTML::HTML5::DOM::HTMLParagraphElement>

=item * L<HTML::HTML5::DOM::HTMLParamElement>

=item * L<HTML::HTML5::DOM::HTMLPreElement>

=item * L<HTML::HTML5::DOM::HTMLProgressElement>

=item * L<HTML::HTML5::DOM::HTMLQuoteElement>

=item * L<HTML::HTML5::DOM::HTMLScriptElement>

=item * L<HTML::HTML5::DOM::HTMLSelectElement>

=item * L<HTML::HTML5::DOM::HTMLSourceElement>

=item * L<HTML::HTML5::DOM::HTMLSpanElement>

=item * L<HTML::HTML5::DOM::HTMLStyleElement>

=item * L<HTML::HTML5::DOM::HTMLTableCaptionElement>

=item * L<HTML::HTML5::DOM::HTMLTableCellElement>

=item * L<HTML::HTML5::DOM::HTMLTableColElement>

=item * L<HTML::HTML5::DOM::HTMLTableDataCellElement>

=item * L<HTML::HTML5::DOM::HTMLTableElement>

=item * L<HTML::HTML5::DOM::HTMLTableHeaderCellElement>

=item * L<HTML::HTML5::DOM::HTMLTableRowElement>

=item * L<HTML::HTML5::DOM::HTMLTableSectionElement>

=item * L<HTML::HTML5::DOM::HTMLTextAreaElement>

=item * L<HTML::HTML5::DOM::HTMLTimeElement>

=item * L<HTML::HTML5::DOM::HTMLTitleElement>

=item * L<HTML::HTML5::DOM::HTMLTrackElement>

=item * L<HTML::HTML5::DOM::HTMLUListElement>

=item * L<HTML::HTML5::DOM::HTMLVideoElement>

=item * L<HTML::HTML5::DOM::RadioNodeList>

=back

=head2 Packages external to this distribution

B<"Friends":>
L<XML::LibXML>,
L<XML::LibXML::Augment>,
L<HTML::HTML5::Parser>,
L<HTML::HTML5::Writer>,
L<HTML::HTML5::ToText>,
L<HTML::HTML5::Builder>.

B<"Rivals":>
L<HTML::DOM>,
L<HTML::Tree>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENCE

This software is copyright (c) 2012 by Toby Inkster.

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

=head1 DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.