Render Pages and Components with ISML, HTML, and CSS
Learning Objectives
After completing this unit, you’ll be able to:
- Describe what a page type’s render function does.
- List four Page Designer CSS development standards.
- Explain how you can vary a component’s style based on its region.
Explore the Visual Layer
You’ve worked through controllers, JSON, and script files. Now, it’s time to explore the visual layer: ISML, HTML, and CSS.
An ISML template renders the HTML that appears in the browser. CSS defines the styling. Script files call the template, which outputs the markup.
Render Pages with ISML and HTML
A page type’s render function creates the page’s HTML markup. Typically, it calls an ISML template that uses PageMgr.renderRegion() to render each region of the page.
In this example, a page calls an ISML template that renders three regions: header, main, and footer.
<html>
...
<isprint value="${PageMgr.renderRegion( pdict.page.getRegion('header') )}" encoding="off" />
...
<isprint value="${PageMgr.renderRegion( pdict.page.getRegion('main') )}" encoding="off" />
...
<isprint value="${PageMgr.renderRegion( pdict.page.getRegion('footer') )}" encoding="off" />
...
</html>Each PageMgr.renderRegion() call finds the assigned and visible components in that region and calls each component’s render function, which in turn calls the component’s own ISML template. Here’s what a component ISML template looks like for the SFRA mainBanner component.
<isscript>
var assets = require('*/cartridge/scripts/assets.js');
assets.addCss('/css/experience/components/commerceAssets/imageAndTextCommon.css');
</isscript>
<div class="mainbanner-container">
<a href="${pdict.categoryLink}">
<div class="row">
<div class="col-12">
<figure class="mainbanner-figure image-component">
<picture>
<source srcset="${pdict.image.src.tablet}" media="(min-width: 768px)"/>
<source srcset="${pdict.image.src.desktop}" media="(min-width: 1024px)"/>
<img
class="mainbanner-image image-fluid common-image-component common-image-filter"
src="${pdict.image.src.mobile}"
style="--focal-point-x:${pdict.image.focalPointX}; --focal-point-y:${pdict.image.focalPointY}"
<isif condition="${pdict.image.alt}">alt="${pdict.image.alt}" title="${pdict.image.alt}"</isif>
/>
</picture>
<figcaption class="image-heading-container">
<div class="row image-heading-text">
<div class="col-12 text-sm-left text-center">
<span>
<isprint value="${pdict.heading}" encoding="off"/>
</span>
</div>
</div>
<div class="row mainbanner-sub-text">
<div class="col-12 text-sm-left text-center">
<p class="link-large">${Resource.msg('pd.main.banner.shop.now','pageDesigner',null)}</p>
</div>
</div>
</figcaption>
</figure>
</div>
</div>
</a>
</div>As Page Designer renders each region and component, it uses the dw.experience.RegionRenderSettings and dw.experience.ComponentRenderSettings APIs to create an HTML element to wrap the content, specifying which HTML element to use as the wrapper and which attributes to assign to it.
Apply CSS Standards
These four standards apply.
- By default, the HTML wrapper for Page Designer regions and components is
div. - The default CSS class for regions is
experience-region experience-<region_definition_id>. - The default CSS class for components is
experience-component experience-<componenttype_id>. - Component type ID values include dots, for example,
assets.productile. In CSS class names, the dot becomes a hyphen:experience-component experience-assets-productile.
For example, for a region with ID my_region and three components, two of type my_component_type_1 and one of type my_component_type_2, the default HTML wrapper looks like this.
<div class="experience-region experience-my_region">
<div class="experience-component experience-my_component_type_1">
content of first component (type my_component_type_1) goes here
</div>
<div class="experience-component experience-my_component_type_1">
content of second component (type my_component_type_1) goes here
</div>
<div class="experience-component experience-my_component_type_2">
content of third component (type my_component_type_2) goes here
</div>
</div>Vary the Look
Components take on different styles depending on the region that they’re in. Consider this scenario: a product tile component uses default render settings on its own, but when it appears inside a carousel component, you want it to use carousel-specific styling.
For the carousel’s carousel region, you want the first and second components to get the CSS class item, and the third to get item active so it renders as the active slide. The HTML output looks like this.
<div class="carousel-inner"> <div class="item">content of first component goes here</div> <div class="item">content of second component goes here</div> <div class="item active">content of third component goes here</div> </div>
Place this code in the render function of the carousel component’s script file to set those custom render settings.
var carousel = component.getRegion("carousel");
// set styling for carousel region
var carouselRenderSettings = new dw.experience.RegionRenderSettings();
carouselRenderSettings.setTagName("div");
carouselRenderSettings.setAttributes({ class: "carousel-inner" });
// set carousel item styling (default)
var defaultCarouselComponentRenderSettings = new dw.experience.ComponentRenderSettings();
defaultCarouselComponentRenderSettings.setTagName("div");
defaultCarouselComponentRenderSettings.setAttributes({ class: "item" });
carouselRenderSettings.setDefaultComponentRenderSettings(defaultCarouselComponentRenderSettings);
// set carousel item styling (active one)
var activeCarouselComponent = carousel.visibleComponents[0]; // init the first one as being active
var activeCarouselComponentRenderSettings = new dw.experience.ComponentRenderSettings();
activeCarouselComponentRenderSettings.setTagName("div");
activeCarouselComponentRenderSettings.setAttributes({ class: "item active" });
carouselRenderSettings.setComponentRenderSettings(
activeCarouselComponent,
activeCarouselComponentRenderSettings,
);
// render the carousel region
return dw.experience.PageMgr.renderRegion(carousel, carouselRenderSettings);The SFRA reference implementation includes helper functionality in the Page Designer reference examples to streamline this code.
Upload and Preview Your Changes
Upload your new code to the server, then open Page Designer and create a page. Add the components you updated and view the results in Page Designer’s center pane or preview them in the storefront.
Up Next
In this unit, you explored the visual layer of Page Designer—ISML, HTML, and CSS—and saw how PageMgr.renderRegion() drives region rendering. You learned how SFRA uses ISML templates to render component markup and how to customize component styling based on the region context.
In the next unit, you go beyond standard component attributes and create your own custom attribute editor.