author | William Roberts <williamr@symbian.org> |
Wed, 03 Jun 2009 18:33:51 +0100 | |
changeset 3 | 8b87ea768cb8 |
parent 0 | 02cd6b52f378 |
permissions | -rw-r--r-- |
0
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
1 |
=head1 NAME |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
2 |
|
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
3 |
XML::DOM::DocumentFragment - Facilitates cut & paste in XML::DOM documents |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
4 |
|
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
5 |
=head1 DESCRIPTION |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
6 |
|
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
7 |
XML::DOM::DocumentFragment extends L<XML::DOM::Node> |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
8 |
|
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
9 |
DocumentFragment is a "lightweight" or "minimal" Document object. It is |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
10 |
very common to want to be able to extract a portion of a document's |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
11 |
tree or to create a new fragment of a document. Imagine implementing a |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
12 |
user command like cut or rearranging a document by moving fragments |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
13 |
around. It is desirable to have an object which can hold such fragments |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
14 |
and it is quite natural to use a Node for this purpose. While it is |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
15 |
true that a Document object could fulfil this role, a Document object |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
16 |
can potentially be a heavyweight object, depending on the underlying |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
17 |
implementation. What is really needed for this is a very lightweight |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
18 |
object. DocumentFragment is such an object. |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
19 |
|
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
20 |
Furthermore, various operations -- such as inserting nodes as children |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
21 |
of another Node -- may take DocumentFragment objects as arguments; this |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
22 |
results in all the child nodes of the DocumentFragment being moved to |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
23 |
the child list of this node. |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
24 |
|
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
25 |
The children of a DocumentFragment node are zero or more nodes |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
26 |
representing the tops of any sub-trees defining the structure of the |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
27 |
document. DocumentFragment nodes do not need to be well-formed XML |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
28 |
documents (although they do need to follow the rules imposed upon |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
29 |
well-formed XML parsed entities, which can have multiple top nodes). |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
30 |
For example, a DocumentFragment might have only one child and that |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
31 |
child node could be a Text node. Such a structure model represents |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
32 |
neither an HTML document nor a well-formed XML document. |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
33 |
|
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
34 |
When a DocumentFragment is inserted into a Document (or indeed any |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
35 |
other Node that may take children) the children of the DocumentFragment |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
36 |
and not the DocumentFragment itself are inserted into the Node. This |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
37 |
makes the DocumentFragment very useful when the user wishes to create |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
38 |
nodes that are siblings; the DocumentFragment acts as the parent of |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
39 |
these nodes so that the user can use the standard methods from the Node |
02cd6b52f378
adding synch hg to p4 & create dummy foundation structure scripts
tahirm@symbian.org
parents:
diff
changeset
|
40 |
interface, such as insertBefore() and appendChild(). |