Magento2 Module Layout – Relationship Between Module Layout Handle XML Files and Theme Update XML Files

These matters due to a different XSD configurations. The

<layout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/layout_generic.xsd">

declaration says that we want to use layout with XSD definition provided in the

lib/internal/Magento/Framework/View/Layout/etc/layout_generic.xsd

In the layout_generic.xsd file it provides definition for layout node with genericLayout element type.

<xs:complexType name="genericLayout">
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
        <xs:element ref="referenceContainer" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="container" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="block" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="referenceBlock" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="update" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="move" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="uiComponent" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
</xs:complexType>

Having that, the layout file has been validated by the XSD when xml is loaded. In addition to this it highlights all possible nodes and node attributes in the layout.xml file.

Same with page_configuration.xsd definition for <page /> node. This XSD describes nodes which can be used to describe page.

Hope it helps.

I'm trying to solve a similar issue, so I'm reading through the code pretty extensively to get to the root of this. I'll start at the end and work backward:

The call to addUpdate() you reference actually does end up calling addUpdate() on the \Magento\Framework\View\Model\Layout\Merge class. Hold onto your seat: it's a bumpy road. The $page variable is an instance of \Magento\Framework\View\Result, and it inherits the definition of addUpdate() from its parent class Layout (in the same namespace). That class in turn calls addUpdate() on a ProcessorInterface, whose default implementation is none other than: Magento\Framework\View\Model\Layout\Merge.

So then to your question about it seeming to pass the entire XML string: you are correct, and the behavior is correct. The Merge class should theoretically be taking care of parsing the <update> inside _fetchRecursiveUpdates() and then loading the layout XML from the referenced handle.

The catch is that _fetchRecursiveUpdates() is never called on XML chunks that are added via addUpdate(). They are assumed to be ready-to-go (non-recursive) layout instructions. Layout XML from external addUpdate() calls are included directly via a call to $this->asString() at the very end of Merge::load(). They never pass through the inner _merge() function which is what indirectly calls _fetchRecursiveUpdates().

A simplistic solution would be to create a new class that extends the built-in Merge class and set it as the preferred implementation of ProcessorInterface. You would then change the addUpdate() method to perform the same logic as _fetchRecursiveUpdates() before saving its argument to the internal array, something like the following:

public function addUpdate($update)
{
    $updateXml = $this->_loadXmlString($update);
    if (strtolower($updateXml->getName()) == 'update' && isset($updateXml['handle'])) {
        $this->_merge((string)$updateXml['handle']);
    } else {
        $this->updates[] = $update;
    }
    return $this;
}