Start tracking your progress
Trailhead Home
Trailhead Home

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 templates render HTML on the browser, while CSS does the styling.

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 PageMgr.renderRegion() to render each region of the page.

The homepage.isml template, for example, 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() function 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 banner.isml.

...
<img width="<!-- calculate it in your component controller using
${pdict.content.size} -->" src="${pdict.content.image.getAbsURL()}"
alt="${pdict.content.alt}"/>
<!--
 // if the 'assets.banner' component type had a region 'banner1' we could render it here
 <isprint value="${PageMgr.renderRegion( pdict.component.getRegion('foobar') )}" encoding="off"/>
-->
… 

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.