#include <Ultralight/dom/DocumentFragment.h>

Overview

A container for assembling DOM nodes off the page.

A DocumentFragment is a DOM node that holds child nodes outside the document tree. It serves as temporary storage for building content in native code before inserting it into the page.

You can build list items from C++ data off the page and insert them in one call:

dom::DocumentFragment items = document.createDocumentFragment();
for (const Score& score : scores) {
  dom::Element entry = document.createElement("li");
  entry.append(score.player, ": ", std::to_string(score.points));
  items.appendChild(entry);
}
document.getElementById("scores").replaceChildren(items);

Inserting a Fragment

Because DocumentFragment inherits from dom::Node, you can pass it to any DOM insertion call.

Inserting a fragment moves all its children into the page in order, leaving the fragment empty. The handle remains valid after insertion, so you can fill it with new nodes and insert it again.

See also: dom::Document::createDocumentFragment(), dom::Element::replaceChildren(), dom::Node, dom::Range::extractContents()

Inheritance diagram for DocumentFragment:

Static Public Member Functions
static DocumentFragment	Adopt (ULDOMFragment handle)
	Wrap a C handle you own, taking ownership of it.
static DocumentFragment	FromBorrowed (ULDOMFragment handle)
	Wrap a C handle the library owns, adding a reference.
Static Public Member Functions inherited from Node
static Node	Adopt (ULDOMNode handle)
	Wrap a C handle you own, taking ownership of it.
static Node	FromBorrowed (ULDOMNode handle)
	Wrap a C handle the library owns (eg, a callback argument), adding a reference.

Public Member Functions
	DocumentFragment ()=default
	Create an empty DocumentFragment.
	DocumentFragment (const DocumentFragment &other)
	Copy constructor (both handles refer to the same fragment).
	DocumentFragment (DocumentFragment &&other) noexcept
	Move constructor (other becomes empty).
DocumentFragment &	operator= (DocumentFragment other) noexcept
	Assignment (copies or moves).
Element	appendChild (const Element &child) const
	Append an element to the fragment (appendChild).
Result< Element >	appendChild (const Element &child, Checked_t) const
	Same as appendChild(), but returns a Result with the reason for a failure.
Node	appendChild (const Node &child) const
	Append a node of any kind to the fragment (appendChild).
Result< Node >	appendChild (const Node &child, Checked_t) const
	Same as appendChild() with a Node, but returns a Result with the reason for a failure.
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	append (T &&... nodes) const
	Add nodes and strings to the end of the fragment (append).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	append (Checked_t, T &&... nodes) const
	Same as append(), but returns a Result with the reason for a failure.
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	prepend (T &&... nodes) const
	Add nodes and strings to the start of the fragment, before its first child (prepend).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	prepend (Checked_t, T &&... nodes) const
	Same as prepend(), but returns a Result with the reason for a failure.
ULDOMFragment	raw () const
	Get the C handle, for passing to the C API (eg, ulDOMElementAppendFragment()).
ULDOMFragment	LeakRef ()
	Give up ownership of the C handle and return it.
Public Member Functions inherited from Node
	Node ()
	Create an empty Node.
	Node (const Node &other)
	Copy constructor (both handles refer to the same node).
	Node (Node &&other) noexcept
	Move constructor (other becomes empty).
Node &	operator= (Node other) noexcept
	Assignment (copies or moves).
	~Node ()
	Destroy this handle (the node itself isn't affected).
	operator bool () const
	Whether or not this Node is valid (see IsAlive()).
bool	IsEmpty () const
	Whether or not this Node is empty (it holds no handle).
bool	IsAlive () const
	Whether or not this Node is valid (it isn't empty and its page is still alive).
bool	IsSame (const Node &other) const
	Whether or not two handles refer to the same node (isSameNode).
NodeType	nodeType () const
	Get the kind of node (nodeType).
std::string	nodeName () const
	Get the node's name (nodeName).
Node	parentNode () const
	Get the node's parent (parentNode).
Element	parentElement () const
	Get the node's parent element (parentElement).
Node	firstChild () const
	Get the node's first child of any kind (firstChild).
Node	lastChild () const
	Get the node's last child of any kind (lastChild).
Node	previousSibling () const
	Get the node's previous sibling of any kind (previousSibling).
Node	nextSibling () const
	Get the node's next sibling of any kind (nextSibling).
NodeList	childNodes () const
	Get the node's children of every kind in order (childNodes).
bool	hasChildNodes () const
	Whether or not the node has any children (hasChildNodes).
bool	isConnected () const
	Whether or not the node is in its document (isConnected).
Document	ownerDocument () const
	Get the document this node belongs to (ownerDocument).
Element	AsElement () const
	Get this node as an Element.
DocumentFragment	AsFragment () const
	Get this node as a DocumentFragment.
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	before (T &&... nodes) const
	Insert nodes and strings just before this node, in its parent (before).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	before (Checked_t, T &&... nodes) const
	Same as before(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	after (T &&... nodes) const
	Insert nodes and strings just after this node, in its parent (after).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	after (Checked_t, T &&... nodes) const
	Same as after(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
void	replaceWith (T &&... nodes) const
	Replace this node with nodes and strings, in its parent (replaceWith).
template<typename... T> requires ((detail::NodeOrString<T> && ...))
Result< void >	replaceWith (Checked_t, T &&... nodes) const
	Same as replaceWith(), but returns a Result with the reason for a failure (eg, a HierarchyRequestError for a cycle).
void	remove () const
	Remove this node from its parent (remove).
Result< void >	remove (Checked_t) const
	Same as remove(), but returns a Result with the reason for a failure.
ULDOMNode	raw () const
	Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMNode.h> functions.
ULDOMNode	LeakRef ()
	Give up ownership of the C handle and return it.

Protected Member Functions
	DocumentFragment (ULDOMFragment handle)
Protected Member Functions inherited from Node
	Node (ULDOMNode handle)

Additional Inherited Members
Public Attributes inherited from Node
detail::NodeStringProp< detail::NodeValueTag >	nodeValue
	The text of a text or comment node (nodeValue).
detail::NodeStringProp< detail::NodeTextContentTag >	textContent
	The text of this node and all its descendants (textContent).
detail::NodeStorage	detail_
	Internal storage (not part of the API).

Constructor & Destructor Documentation

◆ DocumentFragment() [1/4]

DocumentFragment ( )

default

Create an empty DocumentFragment.

See also: Document::createDocumentFragment()

◆ DocumentFragment() [2/4]

DocumentFragment ( const DocumentFragment & other )

inline

Copy constructor (both handles refer to the same fragment).

Parameters

◆ DocumentFragment() [3/4]

DocumentFragment ( DocumentFragment && other )

inlinenoexcept

Move constructor (other becomes empty).

Parameters

other The DocumentFragment to move from.

◆ DocumentFragment() [4/4]

DocumentFragment ( ULDOMFragment handle )

inlineexplicitprotected

Member Function Documentation

◆ Adopt()

DocumentFragment Adopt ( ULDOMFragment handle )

inlinestatic

Wrap a C handle you own, taking ownership of it.

Parameters

handle A handle from the C API that you would otherwise destroy with ulDestroyDOMFragment() (NULL gives an empty DocumentFragment).

Returns: Returns a DocumentFragment that destroys handle when it's done.

◆ append() [1/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

Result< void > append	(	Checked_t	,
		T &&...	nodes ) const

inlinenodiscard

Same as append(), but returns a Result with the reason for a failure.

dom::Checked comes first here, before the nodes (batch.append(dom::Checked, row, "x")).

Returns: Returns success. Fails with a HierarchyRequestError if one of the nodes can't go in a fragment (eg, a doctype).

◆ append() [2/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

void append ( T &&... nodes ) const

inline

Add nodes and strings to the end of the fragment (append).

Pass any mix of nodes (including elements) and strings. Each string is added as a new text node (it's never parsed as markup).

Parameters

nodes The nodes and strings to add, in order. A node that's already in the page (or in another fragment) moves here.

◆ appendChild() [1/4]

Element appendChild ( const Element & child ) const

inline

Append an element to the fragment (appendChild).

If the element is already in the page (or in another fragment), it moves here.

Parameters

child The element to append.

Returns: Returns the appended element (empty if this fragment or child is empty or its page is gone).

◆ appendChild() [2/4]

Result< Element > appendChild	(	const Element &	child,
		Checked_t	) const

inlinenodiscard

Same as appendChild(), but returns a Result with the reason for a failure.

Returns: Returns the appended element (it fails only when this fragment or child is empty or its page is gone).

◆ appendChild() [3/4]

Node appendChild ( const Node & child ) const

inline

Append a node of any kind to the fragment (appendChild).

Use this for text and comment nodes (eg, from Document::createTextNode()). An Element argument goes to the overload that returns an Element.

Parameters

child The node to append. If it's already in the page (or in another fragment), it moves here.

Returns: Returns child (empty if nothing was appended, eg, because child is a doctype, or a handle is empty or its page is gone).

◆ appendChild() [4/4]

Result< Node > appendChild	(	const Node &	child,
		Checked_t	) const

inlinenodiscard

Same as appendChild() with a Node, but returns a Result with the reason for a failure.

Returns: Returns child. Fails with a HierarchyRequestError if child can't go in a fragment (eg, a doctype).

◆ FromBorrowed()

DocumentFragment FromBorrowed ( ULDOMFragment handle )

inlinestatic

Wrap a C handle the library owns, adding a reference.

Parameters

handle The borrowed handle (NULL gives an empty DocumentFragment).

Returns: Returns a DocumentFragment with its own reference to handle.

◆ LeakRef()

ULDOMFragment LeakRef ( )

inline

Give up ownership of the C handle and return it.

This DocumentFragment becomes empty.

Returns: Returns the handle. You must call ulDestroyDOMFragment() when finished.

◆ operator=()

DocumentFragment & operator= ( DocumentFragment other )

inlinenoexcept

Assignment (copies or moves).

Parameters

other The DocumentFragment to assign from.

Returns: Returns this DocumentFragment.

◆ prepend() [1/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

Result< void > prepend	(	Checked_t	,
		T &&...	nodes ) const

inlinenodiscard

Same as prepend(), but returns a Result with the reason for a failure.

dom::Checked comes first here, before the nodes (batch.prepend(dom::Checked, row, "x")).

Returns: Returns success. Fails with a HierarchyRequestError if one of the nodes can't go in a fragment (eg, a doctype).

◆ prepend() [2/2]

template<typename... T>
requires ((detail::NodeOrString<T> && ...))

void prepend ( T &&... nodes ) const

inline

Add nodes and strings to the start of the fragment, before its first child (prepend).

Works like append().

Parameters

nodes The nodes and strings to add, in order. A node that's already in the page (or in another fragment) moves here.

◆ raw()

ULDOMFragment raw ( ) const

inline

Get the C handle, for passing to the C API (eg, ulDOMElementAppendFragment()).

Returns: Returns the handle (NULL for an empty DocumentFragment). This DocumentFragment still owns it, so don't destroy it.

The documentation for this class was generated from the following file:

Ultralight/dom/DocumentFragment.h

Overview

Inserting a Fragment

Static Public Member Functions

Public Member Functions

Protected Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ DocumentFragment() [1/4]

◆ DocumentFragment() [2/4]

◆ DocumentFragment() [3/4]

◆ DocumentFragment() [4/4]

Member Function Documentation

◆ Adopt()

◆ append() [1/2]

◆ append() [2/2]

◆ appendChild() [1/4]

◆ appendChild() [2/4]

◆ appendChild() [3/4]

◆ appendChild() [4/4]

◆ FromBorrowed()

◆ LeakRef()

◆ operator=()

◆ prepend() [1/2]

◆ prepend() [2/2]

◆ raw()