NAME

Web::DOM - A Perl DOM implementation

SYNOPSIS

use Web::DOM::Document;

my $doc = new Web::DOM::Document;
my $el = $doc->create_element ('a');
$el->set_attribute (href => 'http://www.whatwg.org/');
$doc->append_child ($el);

DESCRIPTION

The Web::DOM modules is a pure-Perl DOM implementation. It implements various Web standard specifications, including DOM Living Standard and HTML Living Standard.

USAGE

The Web::DOM::Document module provides the new method returning a new document object, which corresponds to the new Document () constructor in JavaScript Web browser environment.

my $doc = new Web::DOM::Document;

Using the document object, the application can create various DOM object, using standard DOM methods:

my $el = $doc->create_element ('p'); # HTML element
my $el = $doc->create_element_ns ($nsurl, $qname);
$el->set_attribute (class => 'hoge fuga');
my $text = $doc->create_text_node ('text');
my $comment = $doc->create_comment ('data');

Please note that DOM attributes and methods are available in perllish_underscored_name rather than domSpecificationsCamelCaseName.

Alternatively, you can instantiate the document object from an HTML or XML string, using the DOMParser interface:

my $parser = new Web::DOM::Parser;
my $doc = $parser->parse_from_string ($string, 'text/html');
my $doc = $parser->parse_from_string ($string, 'application/xhtml+xml');

For more information, see documentation of relevant modules. For example, methods available on the document object is listed in the Web::DOM::Document documentation. Frequently used modules include:

Web::DOM::Document

The Document interface.

Web::DOM::Element

The Element interface.

Web::DOM::Exception

The DOMException interface.

Web::DOM::HTMLCollection

The HTMLCollection interface.

Web::DOM::Parser

The DOMParser interface.

DOM MAPPING

The modules implement the manakai's DOM Perl Binding specification <http://suika.fam.cx/~wakaba/wiki/sw/n/manakai%27s%20DOM%20Perl%20Binding>, which defines the mapping between WebIDL/DOM and Perl.

As a general rule, the object implementing the DOM interface I is an instance of the class (or the class that is a subclass of the class) Web::DOM::I. However, applications should not rely on this, as the class inheritance hierarchy could be different from the interface's one, and could be changed in future revision of the module implementation. In particular, applications should not test whether the object is an instance of the interface that is defined with the [NoInterfaceObject] extended attribute. For example, the ParentNode interface is defined with the extended attribute. The Web::DOM::Document class inherits the Web::DOM::ParentNode class, as the Document interface implements the ParentNode interface according to the DOM Standard, but applications should not test $node->isa ('Web::DOM::ParentNode').

The constructor of a DOM interface, if any, is implemented as the new class method. For example, the constructor of the Document interface can be invoked by Web::DOM::Document->new.

Attributes, methods, and constants of a DOM interface can be accessible as methods of the object implementing the interface. For example, the innerHTML attribute of the Element interface is accessible as the inner_html method of the element objects. If a method corresponding to the attribute is invoked with no argument, it acts as the getter of the attribute. If the method is invoked with an argument, it acts as the setter of the attribute.

$string_returned_by_getter = $el->inner_html;
$el->inner_html ($string_received_by_setter);

$string_returned_by_method = $el->get_attribute ($string);

$el->node_type == $el->ELEMENT_NODE;

Some objects accept array operations:

@children = @{$el->child_nodes};
$length = @{$el->child_nodes};

$first_child = $el->child_nodes->[0];
$second_child = $el->child_nodes->[1];
$second_last_child = $el->child_nodes->[-2];

CONSTRUCTORS

Following classes have the constructor (i.e. the new method):

Web::DOM::Document

Web::DOM::Implementation

Web::DOM::Parser

Web::DOM::XMLSerializer

SPECIFICATIONS

Specifications defining features supported by the modules include:

DOM and Selectors API

DOM Standard <http://dom.spec.whatwg.org/>.

DOM Standard - Selectors API <https://github.com/whatwg/dom/pull/4/files>.

DOMPARSING

DOM Parsing and Serialization Standard <http://domparsing.spec.whatwg.org/>.

DOM3CORE

Document Object Model (DOM) Level 3 Core Specification <http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/DOM3-Core.html>.

HTML

HTML Standard <http://www.whatwg.org/specs/web-apps/current-work/>.

DOMDTDEF

DOM Document Type Definitions <http://suika.fam.cx/www/markup/xml/domdtdef/domdtdef>.

DOMPERL

manakai's DOM Perl Binding <http://suika.fam.cx/~wakaba/wiki/sw/n/manakai%27s%20DOM%20Perl%20Binding>.

MANAKAI

manakai DOM Extensions <http://suika.fam.cx/~wakaba/wiki/sw/n/manakai%20DOM%20Extensions>.

For the complete list of relevant specifications, see documentations of the modules.

DEPENDENCY

The modules require Perl 5.8 or later.

The only dependency is the perl-charclass package <https://github.com/wakaba/perl-charclass>, which is the submodule of the Git repository.

Following features require the perl-web-markup package <https://github.com/manakai/perl-web-markup> (Web::HTML::Parser and its family): inner_html, outer_html, insert_adjacent_html, and DOMParser.

Following features require the Web::CSS::Selectors::API module in the perl-web-css package <https://github.com/manakai/perl-web-css>: query_selector and query_selector_all.

DEVELOPMENT

Latest version of the modules is available from the GitHub repository: <https://github.com/manakai/perl-web-dom>.

Test results can be reviewed at: <https://travis-ci.org/manakai/perl-web-dom>.

HISTORY

The manakai project has been developed several generations of DOM implementation. The current DOM3 implementation <https://github.com/wakaba/manakai/tree/master/lib/Message/DOM> had been worked since 2007.

The Web::DOM modules has been developed as replacement for those modules, supporting the current DOM Standard. It does not reuse most of the code of the older implementation, and many useless DOM3 features are not implemented. However, it does implement some DOM3 features that is really necessary for backward compatibility, as well as non-standard manakai extensions. It should be possible for applications using the old implementation to migrate to the new implementation by just replacing class name and as such.

Obsolete features

Following features fully or partially implemented in previous versions of manakai DOM implementations are considered obsolete and will not be implemented by these modules unless they are reintroduced by some DOM specification or found to be necessary for backward compatibility:

DOMImplementationRegistry, DOMImplementationSource, DOMImplementationList, DOM features, DOMStringList, StringExtended, read-only nodes, EntityReference, CDATASection, replaceWholeText, isElementContentWhitespace, specified setter, hasReplacementTree setter, DOM3 configuration parameters, configuration parameters for DOM3 spec compatible DTD-based node operations, DOM3 DOMError, DOMErrorHandler, UserDataHandler, DOMLocator, isId and family, internalSubset, TypeInfo and schemaTypeInfo, DOM3 LS, namespaces for DOM3 events, DocumentType->implementation, URIReference, InternetMediaType, SerialWalker, overloaded operators ==, !=, and .=, write operations through overloaded @{} and %{} operators for NodeList, NamedNodeMap, and HTMLCollection. Attr, Entity, and AttributeDefinition nodes can no longer contain Text nodes.

By default the DocumentType node can no longer contain ProcessingInstruction nodes as children. The old behavior can be restored by setting a true value to the manakai-allow-doctype-children configuration parameter (See Web::DOM::Configuration).

The strict_error_checking attribute no longer disables random exceptions as defined in DOM3 specification; its scope is formally defined in the manakai DOM Extensions specification [MANAKAI].

TODO

The initial milestone of the project is reimplementing the subset of DOM supported by the original manakai's DOM implementation <https://github.com/wakaba/manakai/tree/master/lib/Message/DOM>, except for obsolete features. Features that should be implemented in the initial phase of the development include:

baseURI and related methods [DOM] [HTML] [MANAKAI]

Mutation observers [DOM]

Selectors API Level 2 features

DOMSettableTokenList interface [DOM]

New mutation methods [DOM]

prepend, append, before, after, replace, remove

DOM Events [DOM]

DOM Ranges

DOM Ranges interfaces and methods [DOM]; Ranges support in DOM Core methods and attributes [DOM]; Range.prototype.createContextualFragment [DOMPARSING].

DOM Traversal [DOM]

Window [HTML]

CSSOM

manakai CSSOM/Window extensions

Element.prototype.manakaiComputedStyle, Window.prototype.manakaiGetComputedStyle, Window.prototype.setDocument

HTML DOM [HTML]

Atom DOM [ATOMDOM]

WebVTT DOM [HTML]

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

Copyright 2012-2013 Wakaba <wakaba@suikawiki.org>.

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