Explore Page and Component Type ISML, HTML, and CSS
Learning Objectives
After completing this unit, you’ll be able to:
- Explain 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 the region it’s in.
Introduction
Vijay Lahiri, the Cloud Kicks developer, is ready to explore the visual-oriented code in the ISML, HTML, and CSS files. He wants to learn how they work within the overall Page Designer code structure.
Simply put, an ISML template renders the HTML code that shows on the browser, while CSS defines the styling. Script files kick off and facilitate this chain of events.
ISML and HTML
A page type’s render function creates the page’s HTML markup. Typically, that means that it calls an ISML template that uses PageRenderHelper.getRegionModelRegistry() to render each region of the page.
The storePage.isml template, for example, renders regions: main, and legalnotice.
<iscontent type="text/html" charset="UTF-8" compact="true" />
<isdecorate template="common/layout/pdStorePage">
<isscript>
var assets = require('*/cartridge/scripts/assets.js');
assets.addCss('/css/experience/storePage.css');
</isscript>
<div class="storepage" id="${pdict.page.ID}">
<div class="container">
<div class="row">
<isprint value="${pdict.regions.main.setClassName("col-12").render()}" encoding="off" />
</div>
<div class="row">
<isprint value="${pdict.regions.legalnotice.setClassName("col-12").render()}" encoding="off" />
</div>
</div>
</div>
</isdecorate>
Each PageRenderHelper.getRegionModelRegistry() finds the assigned and visible components in each region and calls each component’s render function, which in turn calls its own ISML template, as in this example of mainBanner.isml.
<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 by specifying which HTML element to use as the wrapper and which attributes to assign to the wrapper.
CSS
Web pages and CSS go together like… JSON and script files. So what does that mean in Page Designer?
To start, it means that Vijay can count on these standards.
- By default, the HTML wrapper for Page Designer CSS 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. When used in the CSS class name, the dot is replaced with a hyphen, for example, experience-component experience-assets-productile.
For example, for a region with ID top_region and three components, two of type component_type_1 and one of type component_type_2, the default HTML wrapper looks like this.
<div class="experience-region experience-top_region">
<div
class="experience-component experience-component_type_1">
content of first component (type component_type_1) goes here
</div>
<div class="experience-component experience-component_type_1">
content of second component (type component_type_1) goes here
</div>
<div class="experience-component experience-component_type_2">
content of third component (type component_type_2) goes here
</div>
</div>
Vary the Look
Vijay wants his components to use different styles depending on the region they’re in. To do this, he defines a component type for a product tile that uses default render settings. Then he defines another component type for a carousel, a one-region component that scrolls through a number of other components. When the product tile component appears in the carousel (as opposed to a banner component, for example), he wants it to use styling specific to the carousel.
Here’s the code to set the custom render settings for the carousel. He includes this code in the render function of the component type’s script file.
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);
Build Time
Vijay uploads his awesome new code to the server. Then he tests it by opening Page Designer and creating a new page and adding the components to it that he just changed. He can view the results in Page Designer’s center pane or preview it in the storefront.
Next Steps
In this unit, you took a look at the more visual Page Designer ISML, HTML, and CSS code. In previous units, you explored the Page Designer page and component type development environment, from concepts to installs and uploads to the detailed code. In the next unit, you go beyond using the standard component attributes to create your own.