matlab.io.xml.dom.DocumentFragment Class

Namespace: matlab.io.xml.dom

Group of document nodes

Since R2021a

Description

Use an object of the matlab.io.xml.dom.DocumentFragment class as a container for a group of document nodes. Appending a document fragment to another node appends the children of the fragment but not the fragment itself. Similarly, inserting a fragment inserts the children but not the fragment. A fragment does not have to be well-formed XML. For example, a fragment can contain multiple top-level nodes or a single text node.

The matlab.io.xml.dom.DocumentFragment class is a handle class.

Class Attributes

`ConstructOnLoad`	`true`
`HandleCompatible`	`true`

For information on class attributes, see Class Attributes.

Creation

You can create a matlab.io.xml.dom.DocumentFragment object by using the createDocumentFragment method of a matlab.io.xml.dom.Document object.

Properties

expand all

`TextContent` — Text content of document fragment
`''` (default) | character vector | string scalar

Text content of this document fragment, specified as a character vector or string scalar. This property contains the concatenated textual content of the children of this fragment.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

Methods

expand all

Public Methods

`appendChild`	`childNode = appendChild(thisFragment,childNode)` appends a node to this fragment and returns the appended node object.
`child`	`node = child(thisFragment,index)` returns the child of this fragment at the specified one-based index. An index value of 1 specifies the first child, a value of 2 specifies the second child, and so on.
`cloneNode`	`docClone = cloneNode(thisFragment,deep)` creates and returns a copy of this `matlab.io.xml.dom.DocumentFragment` object. If `deep` is `true`, the copy is a deep copy. If `deep` is `false`, the copy is a shallow copy.
`compareDocumentPosition`	`posEnum = compareDocumentPosition(thisFragment,otherNode)` returns 35, which indicates that this fragment has no relationship to the position of the other node in the document. A document fragment has no relationship to other document nodes because a fragment is never a child of a document.
`getAttributes`	`attrs = getAttributes(thisFragment)` returns an empty `matlab.io.xml.dom.NamedNodeMap` object because document fragments do not have attributes.
`getChildNodes`	`nodeList = getChildNodes(thisFragment)` returns the children of this fragment as a `matlab.io.xml.dom.NodeList` object.
`getChildren`	`nodes = getChildren(thisFragment)` returns a 1-by-N array of objects, such as `matlab.io.xml.dom.Element` or `matlab.io.xml.dom.Text` objects, that represent the children of this fragment.
`getFirstChild`	`child = getFirstChild(thisFragment)` returns the first child of this fragment.
`getLastChild`	`child = getLastChild(thisFragment)` returns the last child of this fragment.
`getLength`	`length = getLength(thisFragment)` returns the number of children of this fragment as a double.
`getLocalName`	`name = getLocalName(thisFragment)` returns an empty character array because document fragments do not have names.
`getNamespaceURI`	`uri = getNamespaceURI(thisFragment)` returns an empty character array because document fragments do not have names.
`getNextSibling`	`getNextSibling(thisFragment)` returns an empty node object because fragments cannot have siblings.
`getNodeName`	`name = getNodeName(thisFragment)` returns`'#document-fragment'`, which is the name of a document fragment node specified by the W3C XML DOM standard.
`getNodeType`	`type = getNodeType(thisFragment)` returns the double `11`, which indicates that this node is a document fragment. This method provides compatibility with existing MATLAB^® code that is based on the W3C XML DOM standard. For new MATLAB code, use `isa` to determine the type of a node. For example: import matlab.io.xml.dom.* d = Document('book'); frag= createDocumentFragment(d); if isa(frag,'matlab.io.xml.dom.DocumentFragment') fprintf('This is an document fragment.\n'); end
`getNodeValue`	`name = getNodeValue(thisFragment)` returns an empty character vector because a fragment does not have a node value.
`getOwnerDocument`	`doc = getOwnerDocument(thisFragment)` returns the document that owns this element as a `matlab.io.xml.dom.Document` object. The owner document is the document that created this fragment.
`getParentNode`	`parent = getParentNode(thisFragment)` returns an empty node object because document fragments do not have parents.
`getPrefix`	`prefix = getPrefix(thisFragment)` returns an empty character vector because fragments do not have names.
`getPreviousSibling`	`getPreviousSibling(thisFragment)` returns an empty node object because document fragments do not have siblings.
`getTextContent`	`getTextContent(thisFragment)` returns the text content of this fragment. If this fragment has children, the method returns the concatenated text content of the children.
`hasAttributes`	`tf = hasAttributes(thisFragment)` returns `false` because a fragment does not have attributes.
`hasChildNodes`	`tf = hasChildNodes(thisFragment)` returns `true` if this fragment has children.
`insertBefore`	`node = insertBefore(thisFragment,newChild,refChild)` inserts `newChild` before `refChild` in this document fragment. If `refChild` is empty, the method inserts `newChild` at the end of the list of the children of this fragment. If `newChild` is a document fragment node, the method inserts the children of the fragment before the reference node in the same order as they appear in the fragment. If `newChild` already exists in the fragment, the method removes and reinserts it. If `refChild` is a node that has never been appended or inserted into the fragment, it is treated as an empty object and `newChild` is inserted at the end of the list of children of this fragment.
`isDefaultNamespace`	`tf = isDefaultNamespace(thisFragment,namespaceURI)` returns `false` because document fragments do not have names.
`isEqualNode`	`tf = isEqualNode(thisFragment,otherNode)` returns `true` if the node specified by `otherNode` is a fragment and the children of this fragment and the other fragment node are equal. This method tests for equality of nodes, not whether the nodes are handles to the same object. To test for sameness, use the `isSameNode` method. Nodes that are the same are also equal, but nodes that are equal are not necessarily the same.
`isSameNode`	`tf = isSameNode(thisFragment,otherNode)` returns `true` if `otherNode` is the same node as `thisFragment`.
`item`	`node = item(thisFragment,index)` returns the child of this fragment specified by a zero-based index. An index value of 0 specifies the first child, a value of 1 specifies the second child, and so on.
`lookupNamespaceURI`	`uri = lookupNamespaceURI(thisFragment,prefix)` returns an empty character array because document fragments do not have namespaces.
`lookupPrefix`	`prefix = lookupPrefix(thisFragment,namespaceURI)` returns an empty character vector because fragments do not have names.
`normalize`	`normalize(thisFragment)` removes empty text nodes from this fragment and combines adjacent text nodes into a single text node.
`removeChild`	`child = removeChild(thisFragment,child)` removes the child node specified by `child` from this fragment and returns the removed child.
`replaceChild`	`child = replaceChild(thisFragment,newChild,oldChild)` replaces `oldChild` with `newChild` and returns `newChild`. If `newChild` is a `matlab.io.dom.xml.DocumentFragment` object, the method replaces `oldChild` with all of the children of the `DocumentFragment` object and inserts the children in the same order. If the new child is already in the fragment, the method removes the child from the document before it replaces the old child.
`setNodeValue`	`setNodeValue(thisFragment,value)` does not change the node value of this fragment. The node value of a fragment is `''`by definition.
`setPrefix`	`setPrefix(thisFragment,prefix)` returns an error because document fragments do not have names.
`setTextContent`	`setTextContent(thisFragment,textContent)` replaces existing nodes in this fragment with a `matlab.io.xml.dom.Text` node that contains the specified text. Specify `textContent` as a character vector or string scalar.

Examples

collapse all

Use Document Fragment to Create Content Based on Run-Time Data

Open Live Script

Suppose that your application creates chapters and that the number of chapters is determined at run time. You can write a function, such as the createChapters function, defined at the end of this example, to create a specified number of chapter elements and return them as a document fragment.

Create a document that has a root element named book.

import matlab.io.xml.dom.*

doc = Document("book");
docElemRoot = getDocumentElement(doc);

Call the function createChapters to return three chapters as a matlab.io.xml.dom.DocumentFragment object. Append the fragment to the document.

docFrag = createChapters(doc,3);
appendChild(docElemRoot,docFrag);

Write the document to the file book.xml.

xmlFileName = "book.xml";
writer = matlab.io.xml.dom.DOMWriter;
writeToFile(writer,doc,xmlFileName);

Display the resulting XML.

type(xmlFileName);

<?xml version="1.0" encoding="UTF-8" standalone="no" ?><book><chapter>Chapter 1</chapter><chapter>Chapter 2</chapter><chapter>Chapter 3</chapter></book>

The createChapters Function

The function createChapters returns a DocumentFragment object that contains the specified number of chapter elements.

function docFrag = createChapters(doc,n)
docFrag = createDocumentFragment(doc);
for i=1:n
    chapter = createElement(doc,"chapter");
    appendChild(chapter,createTextNode(doc,sprintf("Chapter %d",i)));
    appendChild(docFrag,chapter);
end
end

Version History

Introduced in R2021a