How to create a Custom Component for SFCC Page Designer

6 min readFeb 24, 2021

Photo by Christina @ wocintechchat.com on Unsplash

Introduction

No matter if you’re an experienced developer from DemandWare time or a new developer since SalesForce incorporated this service to its cloud, you might found this platform lacks for a friendly way to allow author to edit content. This changed on August 2019, when a new feature called Page Designer was put in General Availability. Please, allow me to explain what Page Designer is, and step you into develop your own components so your users to easily edit pages.

What is Page Designer?

SFCC has a few ways to add and configure dynamic content on the Business Manager for merchandisers. Either if user wants to use Content Slot or Content Asset, user is limited to edit content as plain HTML or Rich Text. Ever more, if developer added a barely complex markup, merchandiser must be very careful to don’t break markup.

Page Designer is a really easy to use visual editor to customize site’s pages without risk of breaking markup or either HTML/CSS knowledge from user.

You can test it by your own accessing Merchant Tools → Content → Page Designer and edit one of the existing page (home-example.html or campaign-example.html). If you open one of them, you might see something similar to the image below:

As a quick walk through, you can see four buttons floating on the left:

First one (plus icon) allows you to drag and drop one of the built in (or one of yours) component.
Second one is aim to arrange components across the page and organize the entire page. It could be very useful when you have plenty components to take care.
Third one allows you to change Page Properties as its name, locale, when and for which customer groups display, and SEO between other stuff.
Last one is to manage Media content as images and videos.

Why use Page Designer?

Page Designer allows developers to encapsulate logic and dynamic markup generation to end user while asking to enter simple data like strings, image or product’s category for each page’s component.

You can reuse common components across storefronts or projects, saving a lot of time.

Additionally, you can create your own page’s layout and put some logic there or configure which components are permitted to add on each section.

Hands On

Before we start

We assume you already have a SFCC sandbox instance and know how to deploy your code there.

Create basic project

Our project is going to be called demo-page-designer and our cartridge basic-page-designer.

mkdir demo-page-designer && cd demo-page-designer
mkdir basic-page-designer && cd basic-page-designer
mkdir cartridges && cd cartridges
mkdir basic-page-designer && cd basic-page-designer
mkdir experience && cd experience
mkdir components && cd components
mkdir demo_assets && cd demo_assets

Then, copy SFRA content from official repo to a sub-folder named sfra.

Folder structure

Page designers components lives under experience folder. There, we need to place two files: a JSON file for component definition and a JS controller to render output.

Let’s create those files at $/basic-page-designer/cartridges/basic-page-designer/experience/components/demo-assets .

Suppose our component name is heroWithCTA. Let’s create needed files with the desired content.

Definition file

Create a file named heroWithCTA.json. Here, we have some self-explained properties and other important properties:

group: This is the editor group where component will be shown for author.
attribute_definition_groups: This array contains fields group definitions. Each group must have at least one field. Each field need to specify its ID, name and type.

You can find here more information about Page Designer’s component JSON schema.

Below is the complete file content which defines two groups (“Hero Title” and “Hero Call To Action”), on last one we add two fields to configure CTA’s link and caption.

{
  "name": "Hero with CTA",
  "description": "Hero with title, image, copy and CTA button",
  "group": "commerce_assets",
  "attribute_definition_groups": [
  {
    "id": "heroSubTitleSection",
    "name": "Hero title",
    "description": "The message to be displayed on the Sub Title.",
    "attribute_definitions": [
    {
      "id": "heroTitle",
      "name": "Title",
      "description": "The message to be displayed on the title.",
      "type": "string",
      "required": true
    }]
  },
  {
    "id": "heroCTASection",
    "name": "Hero Call To Action",
    "description": "The CTA to be displayed on the hero.",
    "attribute_definitions": [
    {
      "id": "heroCTALink",
      "name": "Button Link",
      "description": "CTA's link.",
      "type": "url"
    },
    {
      "id": "heroCTAText",
      "name": "Button Link Caption",
      "description": "CTA's Caption.",
      "type": "string"
    }]
  }],
  "region_definitions": []
}

Controller file

Here lives code to handle data retrieval to render component with user’s data.

Create a file named heroWithCTA.js and then pass user entered data to an ISML view.

You can find below the entire code sample to continue with our sample.

‘use strict’;var Template = require(‘dw/util/Template’);
var HashMap = require(‘dw/util/HashMap’);/**
* Render logic for CTA With Hero Component
* @param {dw.experience.ComponentScriptContext} context The component script context object.
* @returns {string} The template to be displayed
*/module.exports.render = function (context) {
  var content = context.content;
  var model = new HashMap();  model.heroTitle = content.heroTitle;
  model.heroCTALink = content.heroCTALink;
  model.heroCTAText = content.heroCTAText;  return new Template(‘experience/components/demo_assets/heroWithCTA’).render(model).text;
};

Create Component Template

Last piece of code we need to introduce is to display User’s data. As usual when using ISML templates, we receive data from heroWithCTA.js in pdict variable.

Below is the missing piece of code. Save it in /experience/components/demo_assets as heroWithCTA.isml

<div class="container hero-cta-wrapper">
  <div class="row">
    <div class="campaign-banner-container col-10 col-sm-6">
      <div class="campaign-banner-message">
        <h2 class="title">${pdict.heroTitle}</h2>        <isif condition="${pdict.heroCTALink && pdict.heroCTAText}">
          <a class="cta-button btn btn-primary" href="${pdict.heroCTALink}">${pdict.heroCTAText}</a>
        </isif>
      </div>
    </div>
  </div>
</div>

Please notice that heroCTALink and heroCTAText are not mandatory. For that, we need to check if we want to display Call To Action link.

Testing our component

To fully test your brand new component, you can upload your cartridge to your sandbox and edit any existing Page Designer Page.

You might see our new component under the component group Commerce Assets as follows:

You can drag and drop it to any empty space on the page and component editor might display to enter the fields we configured.

After filling up required fields, you can see component rendering on the page with a very basic style.

Component’s properties editor with values.

Troubleshooting tip: remember to add your cartridge to your storefront cartridge path, and verify you uploaded latest code to active code version. As a last resource, try to re-initialize your code version.

Conclusion

Page designer doesn’t require a lot of development effort to give a simple to use way to our clients to change content in Business Manager without fear of breaking out our priceless markup.