Embedded Blocks

A full document, inlined at the root

An embedded Block is a full virtual .bml document inlined under a root Block's embeddedBlocks — authored the same way as the document root, and never a lightweight fragment or a Sub-Block.

An independent FQN, not nested under the root

An embedded Block's FQN is simply its own resolved type — never nested under the enclosing root's FQN — which is exactly the opposite of how a Sub-Block's identity is derived from its parent.

Root-only, and never nested further

Only the document root may declare embeddedBlocks — Sub-Blocks cannot, and an embedded Block itself cannot declare further embeddedBlocks, which keeps embedding a single flat layer.

One root, one embedded Block

A root Block can carry an embeddedBlocks aggregation holding one fully qualified virtual document, authored the same way as the root itself.

<!-- acme:Handle is fully qualified here — its own FQN, not "Basket.Handle" -->
<acme:Basket xmlns="http://blockml.org/bml"
  xmlns:acme="com.acme.example"
  xmlns:core="org.blockml.bml.core">

  <baseType>
    core:Block
  </baseType>
  <embeddedBlocks>
    <acme:Handle>
      <baseType>
        core:Block
      </baseType>
    </acme:Handle>
  </embeddedBlocks>
</acme:Basket>

acme:Handle's qualified tag already is its complete FQN, com.acme.example.Handle — nothing about Basket's identity gets prepended to it, unlike the Sub-Block on the previous page whose name became Basket.Handle.

What to carry into the next pages

After this page, readers should be able to author an embedded Block without confusing it with a lightweight fragment or a Sub-Block, before Documenting Blocks returns to the documentation model that applies to every kind of Block document, embedded ones included.

Continue with documenting Blocks