These helpers pertain to HTML and data attributes of a node. More...

Static Public Member Functions
static	getBag (Document $doc)
	Return the dynamic "bag" property of a Document.

static	getCodec (Document $doc)
	Return the JsonCodec used for rich attributes in a Document.

static	isPrepared (Document $doc)

static	prepareDoc (Document $doc)

static	prepareChildDoc (Document $topLevelDoc, Document $childDoc)

static	stashObjectInDoc (Document $doc, NodeData $obj)
	Stash $obj in $doc and return an id for later retrieval.

static	noAttrs (Element $node)
	Does this node have any attributes?

static	getNodeData (Element $node)
	Get data object from a node.

static	setNodeData (Element $node, NodeData $data)
	Set node data.

static	getDataParsoid (Element $node)
	Get data parsoid info from a node.

static	setDataParsoid (Element $node, DataParsoid $dp)
	Set data parsoid info on a node.

static	getDataNodeI18n (Element $node)
	Retrieves internationalization (i18n) information of a node (typically for localization)

static	setDataNodeI18n (Element $node, I18nInfo $info)
	Sets internationalization (i18n) information of a node, used for later localization.

static	getDataAttrI18n (Element $node, string $name)
	Retrieves internationalization (i18n) information of an attribute value (typically for localization)

static	setDataAttrI18n (Element $node, string $name, I18nInfo $info)
	Sets internationalization (i18n) information of a attribute value, used for later localization.

static	getDataAttrI18nNames (Element $node)

static	getDataParsoidDiff (Element $node)
	Get data diff info from a node.

static	getDataParsoidDiffDefault (Element $node)
	Get data diff info from a node, setting a default value if not present.

static	setDataParsoidDiff (Element $node, ?DataParsoidDiff $diffObj)
	Set data diff info on a node.

static	getDataMw (Element $node)
	Get data meta wiki info from a node.

static	setDataMw (Element $node, ?DataMw $dmw)
	Set data meta wiki info from a node.

static	validDataMw (Element $node)
	Check if there is meta wiki info in a node.

static	getJSONAttribute (Element $node, string $name, $defaultVal)
	Get an object from a JSON-encoded XML attribute on a node.

static	setJSONAttribute (Element $node, string $name, $obj)
	Set a attribute on a node with a JSON-encoded object.

static	setShadowInfo (Element $node, string $name, $val)
	Set shadow info on a node; similar to the method on tokens.

static	setShadowInfoIfModified (Element $node, string $name, $val, $origVal, bool $skipOrig=false)
	Set shadow info on a node; similar to the method on tokens.

static	addNormalizedAttribute (Element $node, string $name, $val, $origVal, bool $skipOrig=false)
	Set an attribute and shadow info to a node.

static	storeInPageBundle (DomPageBundle $pb, Element $node, stdClass $data, array $idIndex)
	Removes the `data-*` attribute from a node, and migrates the data to the given DomPageBundle.

static	getCodecHints ()
	Helper function to create static Hint objects for JsonCodec.

static	injectPageBundle (Document $doc, PageBundle $pb)

static	extractPageBundle (Document $doc)

static	visitAndLoadDataAttribs (Node $node, array $options=[])
	Walk DOM from node downward calling loadDataAttribs.

static	loadDataAttribs (Node $node, array $options)
	These are intended be used on a document after post-processing, so that the underlying .dataobject is transparently applied (in the store case) and reloaded (in the load case), rather than worrying about keeping the attributes up-to-date throughout that phase.

static	usedIdIndex (Node $node)
	Builds an index of id attributes seen in the DOM.

static	visitAndStoreDataAttribs (Node $node, array $options=[])
	Walk DOM from node downward calling storeDataAttribs.

static	storeDataAttribs (Node $node, ?array $options=null)
	Copy data attributes from the bag to either JSON-encoded attributes on each node, or the page bundle, erasing the data-object-id attributes.

static	cloneNode (Element $elt, bool $deep)
	Clones a node and its data bag.

static	cloneDocumentFragment (DocumentFragment $df)
	Clones a DocumentFragment and its associated data bags.

static	getAttributeObject (Element $node, string $name, $classHint)
	Return the value of a rich attribute as a live (by-reference) object.

static	getAttributeObjectDefault (Element $node, string $name, $classHint)
	Return the value of a rich attribute as a live (by-reference) object.

static	setAttributeObject (Element $node, string $name, object $value, $classHint=null)
	Set the value of a rich attribute, overwriting any previous value.

static	removeAttributeObject (Element $node, string $name)
	Remove a rich attribute.

Public Attributes
const	DATA_OBJECT_ATTR_NAME = 'data-object-id'

Detailed Description

These helpers pertain to HTML and data attributes of a node.

Member Function Documentation

◆ addNormalizedAttribute()

static Wikimedia\Parsoid\Utils\DOMDataUtils::addNormalizedAttribute	(	Element	$node,
		string	$name,
			$val,
			$origVal,
		bool	$skipOrig = false )

static

Set an attribute and shadow info to a node.

Similar to the method on tokens

Parameters

Element	$node	node
string	$name	Name of the attribute.
mixed	$val	value
mixed	$origVal	original value
bool	$skipOrig

◆ cloneNode()

static Wikimedia\Parsoid\Utils\DOMDataUtils::cloneNode	(	Element	$elt,
		bool	$deep )

static

Clones a node and its data bag.

Parameters

Element	$elt
bool	$deep

Returns: Element

◆ extractPageBundle()

static Wikimedia\Parsoid\Utils\DOMDataUtils::extractPageBundle ( Document $doc )

static

Parameters

Document $doc doc

Returns: ?PageBundle

◆ getAttributeObject()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getAttributeObject	(	Element	$node,
		string	$name,
			$classHint )

static

Return the value of a rich attribute as a live (by-reference) object.

This also serves as an assertion that there are not conflicting types.

@phan-template T

Parameters

Element	$node	The node on which the attribute is to be found.
string	$name	The name of the attribute.
	class-string<T>\|Hint<T>	$classHint

Returns: ?T The attribute value, or null if not present.

◆ getAttributeObjectDefault()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getAttributeObjectDefault	(	Element	$node,
		string	$name,
			$classHint )

static

Return the value of a rich attribute as a live (by-reference) object.

This also serves as an assertion that there are not conflicting types. If the value is not present and the class hint is a RichCodecable, a default value will be created using $className::defaultValue() and stored as the value of the attribute.

Note: The $className should have be JsonCodecable (either directly or via a custom JsonClassCodec).

@phan-template T

Parameters

Element	$node	The node on which the attribute is to be found.
string	$name	The name of the attribute.
	class-string<T>\|Hint<T>	$classHint

Returns: ?T The attribute value, or null if not present.

◆ getBag()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getBag ( Document $doc )

static

Return the dynamic "bag" property of a Document.

Parameters

Document $doc

Returns: DataBag

◆ getCodec()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getCodec ( Document $doc )

static

Return the JsonCodec used for rich attributes in a Document.

Parameters

Document $doc

Returns: JsonCodec

◆ getCodecHints()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getCodecHints ( )

static

Helper function to create static Hint objects for JsonCodec.

Returns: array<Hint>

◆ getDataAttrI18n()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getDataAttrI18n	(	Element	$node,
		string	$name )

static

Retrieves internationalization (i18n) information of an attribute value (typically for localization)

Parameters

Element	$node
string	$name

Returns: ?I18nInfo

◆ getDataAttrI18nNames()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getDataAttrI18nNames ( Element $node )

static

Parameters

Element $node

Returns: array

◆ getDataMw()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getDataMw ( Element $node )

static

Get data meta wiki info from a node.

Parameters

Element $node node

Returns: DataMw

◆ getDataNodeI18n()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getDataNodeI18n ( Element $node )

static

Retrieves internationalization (i18n) information of a node (typically for localization)

Parameters

Element $node

Returns: ?I18nInfo

◆ getDataParsoid()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getDataParsoid ( Element $node )

static

Get data parsoid info from a node.

Parameters

Element $node node

Returns: DataParsoid

◆ getDataParsoidDiff()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getDataParsoidDiff ( Element $node )

static

Get data diff info from a node.

Parameters

Element $node node

Returns: ?DataParsoidDiff

◆ getDataParsoidDiffDefault()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getDataParsoidDiffDefault ( Element $node )

static

Get data diff info from a node, setting a default value if not present.

Parameters

Element $node node

Returns: DataParsoidDiff

◆ getJSONAttribute()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getJSONAttribute	(	Element	$node,
		string	$name,
			$defaultVal )

static

Get an object from a JSON-encoded XML attribute on a node.

Parameters

Element	$node	node
string	$name	name
mixed	$defaultVal

Returns: mixed

◆ getNodeData()

static Wikimedia\Parsoid\Utils\DOMDataUtils::getNodeData ( Element $node )

static

Get data object from a node.

Parameters

Element $node node

Returns: NodeData

◆ injectPageBundle()

static Wikimedia\Parsoid\Utils\DOMDataUtils::injectPageBundle	(	Document	$doc,
		PageBundle	$pb )

static

Parameters

Document	$doc	doc
PageBundle	$pb	object

◆ loadDataAttribs()

static Wikimedia\Parsoid\Utils\DOMDataUtils::loadDataAttribs	(	Node	$node,
		array	$options )

static

These are intended be used on a document after post-processing, so that the underlying .dataobject is transparently applied (in the store case) and reloaded (in the load case), rather than worrying about keeping the attributes up-to-date throughout that phase.

For the most part, using this.ppTo* should be sufficient and using these directly should be avoided.

Parameters

Node	$node	node
array	$options	options

◆ noAttrs()

static Wikimedia\Parsoid\Utils\DOMDataUtils::noAttrs ( Element $node )

static

Does this node have any attributes?

Parameters

Element $node

Returns: bool

◆ prepareChildDoc()

static Wikimedia\Parsoid\Utils\DOMDataUtils::prepareChildDoc	(	Document	$topLevelDoc,
		Document	$childDoc )

static

Parameters

Document	$topLevelDoc
Document	$childDoc

◆ removeAttributeObject()

static Wikimedia\Parsoid\Utils\DOMDataUtils::removeAttributeObject	(	Element	$node,
		string	$name )

static

Remove a rich attribute.

Parameters

Element	$node	The node on which the attribute is to be found.
string	$name	The name of the attribute.

◆ setAttributeObject()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setAttributeObject	(	Element	$node,
		string	$name,
		object	$value,
			$classHint = null )

static

Set the value of a rich attribute, overwriting any previous value.

Generally mutating the result returned by the ::getAttribute*Default() methods should be done instead of using this method, since the objects returned are live.

Note: For attribute names where ::isHtmlAttributeWithSpecialSemantics() returns true you can customize the "flattened" representation used for HTML semantics by having the value implement RichCodecable::flatten().

@phan-template T

Parameters

Element	$node	The node on which the attribute is to be found.
string	$name	The name of the attribute. @phan-suppress-next-line PhanTypeMismatchDeclaredParam
T	$value	The new (object) value for the attribute
	class-string<T>\|Hint<T>\|null	$classHint Optional serialization hint @phpcs:ignore MediaWiki.Commenting.FunctionAnnotations.UnrecognizedAnnotation @phan-suppress-next-next-line PhanTemplateTypeNotUsedInFunctionReturn

◆ setDataAttrI18n()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setDataAttrI18n	(	Element	$node,
		string	$name,
		I18nInfo	$info )

static

Sets internationalization (i18n) information of a attribute value, used for later localization.

Parameters

Element	$node
string	$name
I18nInfo	$info

Returns: void

◆ setDataMw()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setDataMw	(	Element	$node,
		?DataMw	$dmw )

static

Set data meta wiki info from a node.

Parameters

Element	$node	node
?DataMw	$dmw	data-mw

◆ setDataNodeI18n()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setDataNodeI18n	(	Element	$node,
		I18nInfo	$info )

static

Sets internationalization (i18n) information of a node, used for later localization.

Parameters

Element	$node
I18nInfo	$info

Returns: void

◆ setDataParsoid()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setDataParsoid	(	Element	$node,
		DataParsoid	$dp )

static

Set data parsoid info on a node.

Parameters

Element	$node	node
DataParsoid	$dp	data-parsoid

◆ setDataParsoidDiff()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setDataParsoidDiff	(	Element	$node,
		?DataParsoidDiff	$diffObj )

static

Set data diff info on a node.

Parameters

Element	$node	node
?DataParsoidDiff	$diffObj	data-parsoid-diff object

◆ setJSONAttribute()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setJSONAttribute	(	Element	$node,
		string	$name,
			$obj )

static

Set a attribute on a node with a JSON-encoded object.

Parameters

Element	$node	node
string	$name	Name of the attribute.
mixed	$obj	value of the attribute to

◆ setNodeData()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setNodeData	(	Element	$node,
		NodeData	$data )

static

Set node data.

Parameters

Element	$node	node
NodeData	$data	data

◆ setShadowInfo()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setShadowInfo	(	Element	$node,
		string	$name,
			$val )

static

Set shadow info on a node; similar to the method on tokens.

Records a key = value pair in data-parsoid['a'] property.

This is effectively a call of 'setShadowInfoIfModified' except there is no original value, so by definition, $val is modified.

Parameters

Element	$node	node
string	$name	Name of the attribute.
mixed	$val	val

◆ setShadowInfoIfModified()

static Wikimedia\Parsoid\Utils\DOMDataUtils::setShadowInfoIfModified	(	Element	$node,
		string	$name,
			$val,
			$origVal,
		bool	$skipOrig = false )

static

Set shadow info on a node; similar to the method on tokens.

If the new value ($val) for the key ($name) is different from the original value ($origVal):

the new value is recorded in data-parsoid->a and
the original value is recorded in data-parsoid->sa

Parameters

Element	$node	node
string	$name	Name of the attribute.
mixed	$val	val
mixed	$origVal	original value (null is a valid value)
bool	$skipOrig

◆ stashObjectInDoc()

static Wikimedia\Parsoid\Utils\DOMDataUtils::stashObjectInDoc	(	Document	$doc,
		NodeData	$obj )

static

Stash $obj in $doc and return an id for later retrieval.

Parameters

Document	$doc
NodeData	$obj

Returns: int

◆ storeDataAttribs()

static Wikimedia\Parsoid\Utils\DOMDataUtils::storeDataAttribs	(	Node	$node,
		?array	$options = null )

static

Copy data attributes from the bag to either JSON-encoded attributes on each node, or the page bundle, erasing the data-object-id attributes.

Parameters

Node	$node	node
?array	$options	options discardDataParsoid: Discard DataParsoid objects instead of storing them keepTmp: Preserve DataParsoid::$tmp storeInPageBundle: If set to a DomPageBundle, data will be stored in the given page bundle instead of data-parsoid and data-mw. outputContentVersion: Version of output we're storing. The page bundle didn't have data-mw before 999.x idIndex: Array of used ID attributes

◆ storeInPageBundle()

static Wikimedia\Parsoid\Utils\DOMDataUtils::storeInPageBundle	(	DomPageBundle	$pb,
		Element	$node,
		stdClass	$data,
		array	$idIndex )

static

Removes the data-* attribute from a node, and migrates the data to the given DomPageBundle.

Generates a unique id with the following format:

mw<base64-encoded counter>

but attempts to keep user defined ids.

TODO: Note that $data is effective a partial PageBundle containing only the 'parsoid' and 'mw' properties.

Parameters

DomPageBundle	$pb
Element	$node	node
stdClass	$data	data
array	$idIndex	Index of used id attributes in the DOM

◆ usedIdIndex()

static Wikimedia\Parsoid\Utils\DOMDataUtils::usedIdIndex ( Node $node )

static

Builds an index of id attributes seen in the DOM.

Parameters

Node $node

Returns: array

◆ validDataMw()

static Wikimedia\Parsoid\Utils\DOMDataUtils::validDataMw ( Element $node )

static

Check if there is meta wiki info in a node.

Parameters

Element $node node

Returns: bool

◆ visitAndLoadDataAttribs()

static Wikimedia\Parsoid\Utils\DOMDataUtils::visitAndLoadDataAttribs	(	Node	$node,
		array	$options = [] )

static

Walk DOM from node downward calling loadDataAttribs.

Parameters

Node	$node	node
array	$options	options

◆ visitAndStoreDataAttribs()

static Wikimedia\Parsoid\Utils\DOMDataUtils::visitAndStoreDataAttribs	(	Node	$node,
		array	$options = [] )

static

Walk DOM from node downward calling storeDataAttribs.

Parameters

Node	$node	node
array	$options	options

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

src/Utils/DOMDataUtils.php

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ addNormalizedAttribute()

◆ cloneNode()

◆ extractPageBundle()

◆ getAttributeObject()

◆ getAttributeObjectDefault()

◆ getBag()

◆ getCodec()

◆ getCodecHints()

◆ getDataAttrI18n()

◆ getDataAttrI18nNames()

◆ getDataMw()

◆ getDataNodeI18n()

◆ getDataParsoid()

◆ getDataParsoidDiff()

◆ getDataParsoidDiffDefault()

◆ getJSONAttribute()

◆ getNodeData()

◆ injectPageBundle()

◆ loadDataAttribs()

◆ noAttrs()

◆ prepareChildDoc()

◆ removeAttributeObject()

◆ setAttributeObject()

◆ setDataAttrI18n()

◆ setDataMw()

◆ setDataNodeI18n()

◆ setDataParsoid()

◆ setDataParsoidDiff()

◆ setJSONAttribute()

◆ setNodeData()

◆ setShadowInfo()

◆ setShadowInfoIfModified()

◆ stashObjectInDoc()

◆ storeDataAttribs()

◆ storeInPageBundle()

◆ usedIdIndex()

◆ validDataMw()

◆ visitAndLoadDataAttribs()

◆ visitAndStoreDataAttribs()