Template decoration with isdecorate, isreplace and SFRA decorators
Key Takeaway
Wrap content in <isdecorate template="..."> to place it at the <isreplace/> tag of a decorator template. In SFRA, page.isml includes site navigation and checkout.isml leaves it out.
Template decoration lets an ISML template place its content inside a shared layout, such as a page with a header, navigation and footer. SFRA uses decoration to give every storefront page one of two standard layouts. The layout you choose decides whether the page shows site navigation.
How decoration works
The content template wraps all the content you want to decorate in an <isdecorate> tag. The tag's required template attribute names the decorator template, for example <isdecorate template="common/layout/page"> ... </isdecorate>.
Inside the decorator template, <isreplace/> marks the spot where the wrapped content is inserted, like the open space inside a picture frame. In the output, the decorator template's contents surround the wrapped content.
<!-- Decorator template: layout/frame.isml -->
<header>Store header</header>
<isreplace/>
<footer>Store footer</footer>
<!-- Content template -->
<isdecorate template="layout/frame">
<h1>Gift cards</h1>
</isdecorate>
<!-- Output -->
<header>Store header</header>
<h1>Gift cards</h1>
<footer>Store footer</footer>The "Gift cards" heading takes the place of <isreplace/>, so the header and footer from the decorator surround it. Surrounding a page's body content with a shared header and footer is a typical use of decoration.
A decorator template usually has one <isreplace/> tag, but zero or several are allowed. With zero, the decorated content is left out of the output. With several, the decorated content is output once for each <isreplace/> tag.