Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 28 ยท Jobs, Content and Operations

Content Assets and Page Designer

Learn how Salesforce B2C Commerce manages storefront content: content assets, content slots, Page Designer components, regions, localization and caching.

A storefront is not only products. The footer text, the home page banner, the shipping policy, the "back to school" landing page: all of this is content, and merchandisers want to change it without waiting for a code deployment. Salesforce B2C Commerce gives you three tools for that, from simple to powerful: content assets, content slots and Page Designer. As a developer you build the places where content can appear and the building blocks merchants can use; the merchants then fill them in Business Manager.

This lesson explains what each tool is for, how a Page Designer component is built (a JSON definition, a render script and an ISML template), how localization and caching affect content, and how the headless storefronts read the same data. The real platform code is read-only on this site because it needs a B2C Commerce instance. The TryIt blocks are stand-ins: small JavaScript models that follow the same ideas (fallback chains, slot ranking, a tree of components) so you can experiment. They are not the platform's code.

Three tools for three jobs

Tool What it is Typical use
Content asset A named piece of markup or text with an ID, folder and online flag Footer links, policy text, a help block
Content slot A placeholder on a page that picks which content to show A banner that depends on the category or the customer group
Page Designer A visual editor that assembles whole pages from components in regions Landing pages, campaign pages, a configurable home page

A rule of thumb: if the merchant edits one text block, use a content asset. If the choice of content changes by context or schedule, use a slot. If the merchant needs to compose a page from reusable pieces, use Page Designer.

Content assets

A content asset lives in Business Manager under the Merchant Tools content area. It has an ID (for example footer-info), a name, an online flag, optional folder assignments for navigation and search, and a body. The body is a custom attribute that holds markup text, so the editor can use a rich text view.

You can use an asset from a template with a remote include, which is how SFRA's content pages work:

HTML
<isinclude url="${URLUtils.url('Page-Include', 'cid', 'footer-info')}"/>

The Page-Include route in the base cartridge loads the asset by its ID and renders it. Because it is a remote include, the fragment has its own cache lifetime (see Caching and Performance). In script code you can read assets with ContentMgr:

JavaScript
'use strict';

var ContentMgr = require('dw/content/ContentMgr');

var asset = ContentMgr.getContent('footer-info');
if (asset && asset.online) {
    var html = asset.custom.body ? asset.custom.body.markup : '';
}

Two practical points. First, content that comes from a rich text editor is trusted markup: it is printed without encoding on purpose, so only trusted staff should get edit rights (Security, Sessions and Compliance). Second, assets are localizable: a merchant can enter a version per locale, and when a version is missing the platform falls back along the locale chain to the default. The first stand-in models that fallback.

JS Stand-in: content assets with a locale fallback chain

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that fr_BE has no entry of its own and lands on fr, and ja_JP ends on default. Offline and unknown assets both give null, so templates and scripts must handle a missing asset.

Content slots

A content slot is a named placeholder in an ISML template. The developer decides where it is and what kind of content it holds; the merchandiser decides what it shows.

HTML
<isslot id="home-main-m" description="Main banner on the home page" context="global"/>

The context says where the slot is evaluated: global (the same everywhere), category (it can vary by category, so it needs a context-object) or folder. In Business Manager, merchandisers create slot configurations for a slot: what to show (a product list, a category, a content asset, or HTML), when it is active (a schedule) and for whom (customer groups). If several configurations qualify, the one with the best rank wins.

Slots are older than Page Designer and are still handy for "show X to this group between these dates". The next stand-in picks a configuration the way the idea works.

JS Stand-in: choosing a slot configuration by schedule, group and rank

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The VIP shopper sees the VIP configuration only during its week. Because the slot's result depends on the date and the customer group, a cached page can show the wrong banner unless the slot is rendered in a way that respects it: this is why slots and caching are always discussed together.

Page Designer

Page Designer lets merchants build a page visually: they pick a page type, drop components into its regions, set attributes (a headline, a link) and publish with a schedule. As a developer you provide the vocabulary: page types, component types and layout components.

flowchart TD
    P["Page (type: storePage)"] --> R["Region: main"]
    R --> L["Layout component: 2-column row"]
    L --> R1["Region: left"]
    L --> R2["Region: right"]
    R1 --> C1["heroBanner"]
    R2 --> C2["productCarousel"]

A page has regions; components fill regions; a layout component has regions of its own, so pages are trees.

A component is three files

Components are cartridge files under experience/components/<group>/. The cartridge needs a normal layout (see Cartridges and the Cartridge Path).

TEXT
cartridge/
  experience/components/storefront/heroBanner.json
  experience/components/storefront/heroBanner.js
  templates/default/experience/components/storefront/heroBanner.isml

The JSON definition declares the name, the group the editor shows it under, the editable attributes and any regions:

JSON
{
  "name": "Hero Banner",
  "description": "A headline with a button",
  "group": "storefront",
  "region_definitions": [],
  "attribute_definition_groups": [
    {
      "id": "content",
      "name": "Content",
      "description": "Texts and link",
      "attribute_definitions": [
        { "id": "headline", "name": "Headline", "type": "string", "required": true },
        { "id": "ctaLabel", "name": "Button label", "type": "string", "required": false },
        { "id": "ctaLink", "name": "Button link", "type": "string", "required": false }
      ]
    }
  ]
}

The render script receives a context with the merchant's values and returns HTML by rendering the template:

JavaScript
'use strict';

var Template = require('dw/util/Template');
var HashMap = require('dw/util/HashMap');

/**
 * @param {dw.experience.ComponentScriptContext} context
 * @returns {string} the rendered HTML
 */
exports.render = function render(context) {
    var content = context.content;
    var model = new HashMap();

    model.put('headline', content.headline);
    model.put('ctaLabel', content.ctaLabel);
    model.put('ctaLink', content.ctaLink);

    return new Template('experience/components/storefront/heroBanner').render(model).text;
};

The template is ordinary ISML, using pdict values and the encoding rules from ISML Templates. A layout component additionally declares region_definitions and renders them with the region's render() helper in its template.

A page is shown by a route that loads it with PageMgr and renders it. In SFRA the base cartridge's Page-Show route does this with PageMgr.getPage() and checks page.isVisible(), which respects the schedule and customer-group visibility the merchant set.

The component tree

The renderer is recursion: render a page's regions, render each region's components, and let layout components render their own regions. The stand-in below does exactly that with a registry of component types, so a component type that does not exist is skipped instead of crashing the whole page.

JS Stand-in: render a Page Designer style component tree

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The merchant typed <b> into the headline, and the output shows it escaped. The unknown carousel type became a comment and the page still rendered. In the real platform the editor will not even let a merchant place a component type that is not installed, but versions change and cartridges are removed, so defensive rendering is still wise.

Localization and the Experience API

Page Designer lets merchants localize a page's content per locale in the editor, and the same locale fallback idea from the first stand-in applies. For headless storefronts the same pages are available as data: the Shopper Experience API (part of SCAPI, see OCAPI and SCAPI) returns a page as JSON with its regions and components, and the PWA Kit storefront maps each component type to a React component. That makes the component type ID a contract: renaming storefront.heroBanner breaks pages that already use it.

Content and caching

Content is the most cache-friendly data on a site, and the most tempting to cache wrongly. Content assets pulled in with a remote include get their own cache time. Page Designer pages are cached like any other page, so after publishing a change the merchant may need to wait for the TTL or invalidate the cache. Keep personal data out of component templates: a cached component is served to everyone.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A merchant wants a banner that changes with the category and shows a VIP offer only to one customer group for one week. Which tool fits best?

    Slots exist to choose which content appears depending on context, schedule and customer group. A single content asset has no such targeting.
  2. 2. What are the three parts of a Page Designer component?

    The JSON describes attributes and regions, the script builds the model and renders the template, and the template produces the HTML.
  3. 3. Why is the component type ID treated like a contract?

    Pages store the component type they use, and PWA Kit style storefronts map the type to a front-end component. Changing the ID orphans existing content.
  4. 4. A French-Belgian shopper (fr_BE) opens a page. The asset has only fr and default versions. What is served?

    Localized values resolve along a chain, locale then language then default. The first stand-in shows the same idea.

Summary

  • Use content assets for named blocks, slots for context-dependent choices and Page Designer for composed pages.
  • A Page Designer component is a JSON definition, a render script and an ISML template; layout components contain regions of their own.
  • Pages are trees, so rendering is recursion and should tolerate unknown component types.
  • Localized values fall back from locale to language to default.
  • Rich text content is trusted markup, so restrict who can edit it.
  • Cache lifetimes decide how quickly published changes appear; never put personal data in cached components.
  • The TryIt blocks are stand-ins: the real definitions, ContentMgr and PageMgr need a B2C Commerce instance.

Next: Caching and Performance