Forem: Gabriel Lima

Widgets/Blocks with Magento Page Builder

Gabriel Lima — Mon, 24 Feb 2025 23:46:11 +0000

This guide explains how to render dynamic content in Magento Page Builder using Blocks or Widgets without
relying on the native "HTML Code" content type.

This guide is based on a custom content type generated
using commerce-docs/pbmodules.

Requirements

A pre-configured Custom Page Builder or a new installation.
Block Class and .phtml template file
(Optional) A widget.xml file if you choose to use the widget setup. If using a block-based implementation, the widget.xml file is not required.

this tutorial as created based on the custom content type that was generated by
the https://github.com/commerce-docs/pbmodules

1. Update Dependency Injection (DI) Configuration

Create or update your module's etc/di.xml, add the following code.

<type name="Magento\PageBuilder\Model\Stage\RendererPool">
    <arguments>
        <argument name="renderers" xsi:type="array">
            <item name="CONTENT_TYPE_NAME" xsi:type="object">
                Magento\PageBuilder\Model\Stage\Renderer\WidgetDirective
            </item>
        </argument>
    </arguments>
</type>

Note: Replace CONTENT_TYPE_NAME with your content type name.

2. Content Type XML Configuration

Create or update the file: view/adminhtml/pagebuilder/content_type/CONTENT_TYPE_NAME.xml

Within the section:
Add an HTML attribute (inside or any other element as needed):

<html name="html" preview_converter="Magento_PageBuilder/js/converter/attribute/preview/store-id"/>

After the </elements>:
Add the converters configuration.

<converters>
    <converter
        component="Vendor_Module/js/content-type/CONTENT_TYPE_FOLDER/mass-converter/widget-directive"
        name="widget_directive">
        <config>
            <item name="html_variable" value="html"/>
        </config>
    </converter>
</converters>

Note: Replace CONTENT_TYPE_FOLDER with your content type folder name.

3. Create the Mass Converter JavaScript

Create the file: view/adminhtml/web/js/content-type/CONTENT_TYPE_FOLDER/mass-converter/widget-directive.js
Add the following code:

Note: Replace CONTENT_TYPE_FOLDER with your content type folder name.

define([
    'Magento_PageBuilder/js/mass-converter/widget-directive-abstract',
    'Magento_PageBuilder/js/utils/object'
], function (widgetDirective, dataObject) {
    'use strict';

    class WidgetDirective extends widgetDirective {
        /**
         * Convert value to internal format
         *
         * @param {object} data
         * @param {object} config
         * @returns {object}
         */
        fromDom(data, config) {
            var attributes = super.fromDom(data, config);

            return data;
        }

        toDom(data, config) {
            const attributes = {
                type: 'Devgfnl\\WidgetBlockPageBuilder\\Block\\Info',
                template: 'Devgfnl_WidgetBlockPageBuilder::info.phtml',
                type_name: 'Widget/Block with PageBuilder',
                my_field: data.my_field
                // ... other attributes to be passed to the block/widget
            };

            dataObject.set(data, config.html_variable, this.buildDirective(attributes));
            return data;
        }
    }

    return WidgetDirective;
});

Using a Block Instead of a Widget
If you are not using the widget setup, modify the toDom function as follows:

        toDom(data, config) {
            const attributes = {
-               type: 'Devgfnl\\WidgetBlockPageBuilder\\Block\\Info',
+               class: 'Devgfnl\\WidgetBlockPageBuilder\\Block\\Info',
                template: 'Devgfnl_WidgetBlockPageBuilder::info.phtml',
                type_name: 'Widget/Block with PageBuilder',
                my_field: data.my_field
            };

-           dataObject.set(data, config.html_variable, this.buildDirective(attributes));
+           dataObject.set(data, config.html_variable, this.buildBlockDirective(attributes));
            return data;
        }

+       buildBlockDirective(attributes) {
+           return '{{block ' + this.createAttributesString(attributes) + '}}';
+       }

Note: When using a widget, ensure that you have the proper widget.xml setup; otherwise, the Page Builder will not
render the PHTML content. The block-based approach is recommended if you want to avoid creating an extra widget.xml
file.

4. Update the Preview JavaScript

Create or update the file view/adminhtml/web/js/content-type/CONTENT_TYPE_FOLDER/preview.js file, update it with the
following code.

Note: Replace CONTENT_TYPE_FOLDER with your content type folder name.

define([
    'jquery',
    'mage/translate',
    'knockout',
    'underscore',
    'Magento_PageBuilder/js/config',
    'Magento_PageBuilder/js/content-type/preview'
], function (
    $,
    $t,
    ko,
    _,
    Config,
    PreviewBase
) {
    'use strict';

    var $super;

    /**
     * Quote content type preview class
     *
     * @param parent
     * @param config
     * @param stageId
     * @constructor
     */
    function Preview(parent, config, stageId) {
        PreviewBase.call(this, parent, config, stageId);
        this.displayPreview = ko.observable(false);
        this.previewElement = $.Deferred();
        this.loading = ko.observable(false);
        this.widgetUnsanitizedHtml = ko.observable();
        this.element = null;
        this.messages = {
            EMPTY: $t('Empty...'),
            NO_RESULTS: $t('No result were found.'),
            LOADING: $t('Loading...'),
            UNKNOWN_ERROR: $t('An unknown error occurred. Please try again.')
        };
        this.placeholderText = ko.observable(this.messages.EMPTY);
    }

    Preview.prototype = Object.create(PreviewBase.prototype);
    $super = PreviewBase.prototype;

    /**
     * Modify the options returned by the content type
     *
     * @returns {*}
     */
    Preview.prototype.retrieveOptions = function () {
        var options = $super.retrieveOptions.call(this, arguments);

        // Customize options here

        return options;
    };

    /**
     * On afterRender callback.
     *
     * @param {Element} element
     */
    Preview.prototype.onAfterRender = function (element) {
        this.element = element;
        this.previewElement.resolve(element);
    };

    /**
     * @inheritdoc
     */
    Preview.prototype.afterObservablesUpdated = function () {
        $super.afterObservablesUpdated.call(this);
        const data = this.contentType.dataStore.getState();

        if (this.hasDataChanged(this.previousData, data)) {
            this.displayPreview(false);

            if (!this.shouldDisplay(data)) {
                this.placeholderText(this.messages.EMPTY);
                return;
            }

            const url = Config.getConfig('preview_url'),
                requestConfig = {
                    // Prevent caching
                    method: 'POST',
                    data: {
                        role: this.config.name,
                        directive: this.data.main.html()
                    }
                };

            this.placeholderText(this.messages.LOADING);

            $.ajax(url, requestConfig)
                .done((response) => {
                    if (typeof response.data !== 'object' || !response.data.content) {
                        this.placeholderText(this.messages.NO_RESULTS);

                        return;
                    }

                    if (response.data.error) {
                        this.widgetUnsanitizedHtml(response.data.error);
                    } else {
                        this.widgetUnsanitizedHtml(response.data.content);
                        this.displayPreview(true);
                    }

                    this.previewElement.done(() => {
                        $(this.element).trigger('contentUpdated');
                    });
                })
                .fail(() => {
                    this.placeholderText(this.messages.UNKNOWN_ERROR);
                });
        }
        this.previousData = Object.assign({}, data);
    };

    /**
     * Determine if the preview should be displayed
     *
     * @param data
     * @returns {boolean}
     */
    Preview.prototype.shouldDisplay = function (data) {
        const myField = data.my_field;

        return !!myField;
    };

    /**
     * Determine if the data has changed, whilst ignoring certain keys which don't require a rebuild
     *
     * @param {object} previousData
     * @param {object} newData
     * @returns {boolean}
     */
    Preview.prototype.hasDataChanged = function (previousData, newData) {
        previousData = _.omit(previousData, this.ignoredKeysForBuild);
        newData = _.omit(newData, this.ignoredKeysForBuild);
        return !_.isEqual(previousData, newData);
    };

    return Preview;
});

5. Create the Preview Template

Create or update the file preview template file:
view/adminhtml/web/template/content-type/CONTENT_TYPE_FOLDER/default/preview.html, add
the following code:

Note: Replace CONTENT_TYPE_FOLDER with your content type folder name.

<div class="pagebuilder-content-type" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css"
     event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
    <div class="my-class"
         data-bind="liveEdit: { field: 'my_field', placeholder: $t('Your custom content type!') }"></div>
    <div if="displayPreview" class="rendered-content" html="widgetUnsanitizedHtml" afterRender="onAfterRender"></div>
    <div ifnot="displayPreview" class="pagebuilder-products-placeholder">
        <span class="placeholder-text" text="placeholderText"></span>
    </div>
    <render args="getOptions().template"></render>
</div>

6. Create the Master Template

Create or update the file master template file:
view/adminhtml/web/template/content-type/CONTENT_TYPE_FOLDER/default/master.html, add the
following code:

Note: Replace CONTENT_TYPE_FOLDER with your content type folder name.

<div html="data.main.html" attr="data.main.attributes" css="data.main.css" ko-style="data.main.style"></div>

Results

Observations

KnockoutJS Rendering: In tests, a PHTML file incorporating KnockoutJS rendered correctly on the frontend. However, KnockoutJS may not render as expected in the admin area.
Widget vs. Block: If you use the widget setup, ensure that the corresponding widget.xml is configured properly; otherwise, the PHTML content may not be rendered. The block-based approach is recommended for simplicity, as it does not require an extra XML configuration file.
BlockInterface: If you use the block and widget approach, ensure that the Block class implements the BlockInterface to avoid any issues with the Page Builder rendering the content.

Known Issues & Solutions

Issue: The PHTML content is not rendered in the admin area.
- Solution:
  - If you are using the widget setup, ensure that the widget.xml file is configured properly.
  - Ensure that the Block class implements the BlockInterface.

Code Reference

Source Code
- Branch Widget with Page builder
- Branch Block with Page builder

How to Create a Custom Countdown Content Type in PWA Studio

Gabriel Lima — Tue, 10 Sep 2024 01:38:56 +0000

Summary
- Introduction
- Prerequisites
- Before You Begin
- About the Structure
- Hands-on Code (Step-by-Step)
- Repository
- References

Introduction

In this tutorial, you will learn how to create and integrate a custom content type countdown into PWA Studio. By the end of this guide, you will have a fully functional countdown that is editable from Magento's admin panel and rendered in your PWA storefront.

Prerequisites

Before you begin, ensure you have the following:

A working installation of Magento and PWA Studio.
Basic knowledge of React, JavaScript, and Magento PageBuilder.
Node.js and npm installed in your environment.
PageBuilder Countdown Module

Before You Begin

Before you start coding this content type, ensure the Content Type is installed in your Magento and PWA Studio setup using the Scaffolding Tool. This tool will help set up the basic storefront environment.

The content type that we will integrate with PWA Studio is a countdown timer, which you can get from the repository of this tutorial.

About the Structure

Here is the final structure of the content type:



pwa-studio
├── src
│   ├── components
│   │   └── Countdown
│   │       ├── ContentType
│   │       │   └── Countdown
│   │       │       ├── configAggregator.js
│   │       │       ├── countdown.js
│   │       │       ├── countdown.module.css
│   │       │       └── index.js
│   │       ├── countdown.js
│   │       ├── detect.js
│   │       └── index.js
│   └── talons
│       └── Countdown
│           └── useCountdown.js
├── local-intercept.js
│

Hands-on Code (Step-by-Step)

Now let's start creating the custom content type.

Step 1: Modify `local-intercept.js`

Open the local-intercept.js file in your PWA Studio root and update its content as follows:



function localIntercept(targets) {
    targets.of('@magento/pagebuilder').customContentTypes.tap(
        contentTypes => contentTypes.add({
            contentType: 'Countdown',
            importPath: require.resolve("./src/components/Countdown/index.js")
        })
    );
}

moduleexports = localIntercept;

This code instructs the @magento/pagebuilder to add the custom Countdown content type.

Step 2: Create `configAggregator.js`

Create the file src/components/Countdown/ContentType/Countdown/configAggregator.js with the following content:



import { getAdvanced } from "@magento/pagebuilder/lib/utils";

export default (node, props) => {
    return {
        targetDate: node.childNodes[0].childNodes[0].attributes[1].value,
        ...getAdvanced(node),
    };
};

1. `targetDate` Extraction:

We access the date through: node.childNodes[0].childNodes[0].attributes[1].value. This navigates through the node to reach the attribute that holds the targetDate.

2. `getAdvanced(node)` Utility Function:

getAdvanced(node) is a utility function that retrieves additional styling properties from the node like padding, margins, border, text alignment, and CSS classes.
These settings allow the countdown timer to inherit any advanced layout configurations made by the user in the Magento Page Builder's editor.

Step 3: Create Countdown Component

Now we will create the countdown component.

`countdown.js`

Create the file src/components/Countdown/ContentType/Countdown/countdown.js and add the following code:



import React from 'react';
import { mergeClasses } from '@magento/venia-ui/lib/classify';
import { arrayOf, bool, shape, string } from 'prop-types';

import defaultClasses from './countdown.module.css';
import { FormattedMessage } from 'react-intl';
import { useCountdown } from '../../../../talons/Countdown/useCountdown';

const Countdown = props => {
    const {
        targetDate,
        textAlign,
        border,
        borderColor,
        borderWidth,
        borderRadius,
        isHidden,
        marginTop,
        marginRight,
        marginBottom,
        marginLeft,
        paddingTop,
        paddingRight,
        paddingBottom,
        paddingLeft,
        cssClasses
    } = props;

    const classes = mergeClasses(defaultClasses, props.classes);

    const {
        days,
        hours,
        minutes,
        seconds
    } = useCountdown({ targetDate });

    const formStyles = {
        textAlign,
        border,
        borderColor,
        borderWidth,
        borderRadius,
        isHidden,
        marginTop,
        marginRight,
        marginBottom,
        marginLeft,
        paddingTop,
        paddingRight,
        paddingBottom,
        paddingLeft,
    };

    return (
        <div style={formStyles}>
            <div className={classes.wrapper}>
                <div className={classes.field}>
                    <div className="days">{days}</div>
                    <div className="separator">:</div>
                    <div className="hours">{hours}</div>
                    <div className="separator">:</div>
                    <div className="min">{minutes}</div>
                    <div className="separator">:</div>
                    <div className="sec">{seconds}</div>
                    <div className={classes.label}>
                        <FormattedMessage
                            id="countdown.days"
                            defaultMessage="days"
                        />
                    </div>
                    <div></div>
                    <div className={classes.label}>
                        <FormattedMessage
                            id="countdown.hours"
                            defaultMessage="hours"
                        />
                    </div>
                    <div></div>
                    <div className={classes.label}>
                        <FormattedMessage
                            id="countdown.minutes"
                            defaultMessage="min"
                        />
                    </div>
                    <div></div>
                    <div className={classes.label}>
                        <FormattedMessage
                            id="countdown.seconds"
                            defaultMessage="sec" />
                    </div>
                </div>
            </div>
        </div>
    );
};

Countdown.propTypes = {
    textAlign: string,
    border: string,
    borderColor: string,
    borderWidth: string,
    borderRadius: string,
    isHidden: bool,
    marginTop: string,
    marginRight: string,
    marginBottom: string,
    marginLeft: string,
    paddingTop: string,
    paddingRight: string,
    paddingBottom: string,
    paddingLeft: string,
    cssClasses: arrayOf(string),
    classes: shape({ wrapper: string, field: string, label: string })
};

Countdown.defaultProps = {};

export default Countdown;

Let's break down some key parts of the Countdown component code:

Props Destructuring: In the component's props, we are receiving several variables, most notably the targetDate from the configAggregator.js file. This scaffolding represents the end time for the countdown. Along with targetDate, we also receive various styling-related variables such as textAlign, border, and padding, which are dynamically passed from Page Builder. Lastly, the cssClasses variable comes directly from Page Builder and contains any additional CSS classes that need to be applied to the component.
Calling the Talon: After destructuring the props, we initialize the useCountdown talon. This custom hook (useCountdown) is passed the targetDate as a prop and, in return, provides the values needed to display the countdown—days, hours, minutes, and seconds. These values are automatically updated as time progresses, which ensures that the countdown remains accurate in real-time.
Combining Style Properties: The formStyles variable is an object that combines all the individual style-related variables (such as border, textAlign, margin, and padding) from the props. This aggregation makes it easier to apply these styles in one go, directly onto the container <div>, by using the style attribute:


 <div style={formStyles}>

By passing the formStyles object here, we ensure that the countdown component reflects any custom styling options configured via the Page Builder, such as margins, padding, and borders.

`countdown.module.css`

Next, create the CSS file src/components/Countdown/ContentType/Countdown/countdown.module.css:



.wrapper {
    composes: flex from global;
}  

.field {
    composes: grid from global;
    composes: items-center from global;
    composes: justify-items-center from global;
    composes: gap-1.5 from global;
    composes: font-light from global;
    grid-template-columns: 1fr auto 1fr auto 1fr auto 1fr;
}

field div {
    font-size: 1.5rem;
    letter-spacing: normal;
}

.label {
    composes: text-base from global;
    margin-top: -5px;
    letter-spacing: normal;
}

`index.js`

Finally, create the src/components/Countdown/ContentType/Countdown/index.js file:



import React from 'react';
import configAggregator from './configAggregator';

export default {
    configAggregator,
    component: React.lazy(() => import('./countdown'))
}

configAggregator Import: The configAggregator is imported from the configAggregator.js file. This function is responsible for collecting the necessary data (such as targetDate, margins, borders, etc.) from the Page Builder content type and passing it as props to the component. It ensures that all configurations from the admin panel are correctly applied to the component.
Dynamic Component loading: The React.lazy() function is used to lazily load the countdown component.
Exporting the Configuration Object: The file exports a default object containing two key properties:
- configAggregator: This defines how the content type's configuration data is retrieved and passed into the component.
- component: This points to the countdown component, which is lazy loaded via React.lazy().

This file essentially sets up the necessary configurations and ensures that the countdown component is properly integrated with the Page Builder in a performance-efficient manner.

1. `src/components/Countdown/countdown.js`



import React from 'react';
import { setContentTypeConfig } from '@magento/pagebuilder/lib/config';
import ContentTypeConfig from './ContentType/Countdown';

setContentTypeConfig('example_countdown', ContentTypeConfig);

const Countdown = (props) => {
    return null;
};

export default Countdown;

setContentTypeConfig: This function registers the custom content type (example_countdown) with Page Builder. It accepts two arguments:
- The first argument is the content type name (example_countdown), which must match the name defined in the XML file located at app/code/Example/PageBuilderCountdown/view/adminhtml/pagebuilder/content_type/example_countdown.xml.
- The second argument, ContentTypeConfig, is imported from the Countdown folder and includes the component configuration required by Page Builder.
The component itself (Countdown) does not render any UI, as it only serves to register the content type. Therefore, it returns null.

2. `src/components/Countdown/detect.js`

This file defines a regular expression (RegEx) function to detect if the custom content type is present in the content.



export default function detectMyCustomType(content) {
    return /data-content-type=\"example_countdown/.test(content);
}

detectMyCustomType: This function checks if the Page Builder content contains the custom content type (example_countdown) by searching for the data-content-type="example_countdown" attribute in the rendered HTML. If found, it returns true, indicating that the custom content type is present.
The same content type name (example_countdown) is used here, matching the one defined in the XML file and the setContentTypeConfig function.

3. `src/components/Countdown/index.js`

In this file, we export the components and functionality created above.



export { default } from './countdown';
export { default as Component } from './countdown';
export { default as canRender } from './detect';

Default Export (Countdown): This file exports the countdown component as the default export.
Named Export (Component): The countdown component is also exported as a component, making it easier to refer to the component when necessary.
Named Export (canRender): The detect function is exported as canRender, which will be used by Page Builder to determine whether the custom content type should be rendered based on the presence of the data-content-type="example_countdown" attribute.

These files collectively ensure that the custom content type (example_countdown) is properly registered, detected, and rendered within the Page Builder environment.

Step 4: Set up the Talon

In this section, we will create a talon to handle the logic behind the countdown timer. If you're unfamiliar with talons, they are hooks used in the Magento PWA Studio to separate logic from components, making code more modular and reusable. For more details, check out Talons (adobe.com).

Now create the talon file src/talons/Countdown/useCountdown.js:



import { useEffect, useState, useCallback } from 'react';

export const useCountdown = ({ targetDate }) => {
    const validateDate = (date) => {
        const target = new Date(date);
        return isNaN(target.getTime()) ? null : target;
    };

    const target = validateDate(targetDate);

if (!target) {
        console.error('Invalid targetDate provided');
        return { days: '00', hours: '00', minutes: '00', seconds: '00' };
    }

    const calculateTimeLeft = useCallback(() => {
        const difference = target - new Date();
        if (difference <= 0) return { days: '00', hours: '00', minutes: '00', seconds: '00' };  

        const time = (unit, mod) => String(Math.floor((difference / unit) % mod)).padStart(2, '0');

        return {
            days: time(1000 * 60 * 60 * 24, Infinity),
            hours: time(1000 * 60 * 60, 24),
            minutes: time(1000 * 60, 60),
            seconds: time(1000, 60),
        };
    }, [target]);

    const [timeLeft, setTimeLeft] = useState(calculateTimeLeft);

    useEffect(() => {
        if (Object.values(timeLeft).every((v) => v === '00')) return;

        const timer = setInterval(() => setTimeLeft(calculateTimeLeft), 1000);
        return () => clearInterval(timer);
    }, [timeLeft, calculateTimeLeft]);

    return timeLeft;
};

validateDate: This function ensures the provided targetDate is valid. If the date is invalid, it returns null, and the countdown will display "00" for all time units.
calculateTimeLeft: This function calculates the difference between the current time and the targetDate. It returns the remaining time formatted as days, hours, minutes, and seconds.
useState: We use React's useState to store the current countdown time, updating it every second.
useEffect: This hook sets up a timer that updates the countdown every second. If the countdown reaches "00", it stops.

Repository

You can find the complete repository, which includes both the final PWA Studio code and the Magento module used in this tutorial, at the following link:

https://github.com/GabrielFNLima/magento2-pwa-countdown

Forem: Gabriel Lima

Widgets/Blocks with Magento Page Builder

Requirements

1. Update Dependency Injection (DI) Configuration

2. Content Type XML Configuration

3. Create the Mass Converter JavaScript

4. Update the Preview JavaScript

5. Create the Preview Template

6. Create the Master Template

Results

Observations

Known Issues & Solutions

Code Reference

How to Create a Custom Countdown Content Type in PWA Studio

Introduction

Prerequisites

Before You Begin

About the Structure

Hands-on Code (Step-by-Step)

Step 1: Modify local-intercept.js

Step 2: Create configAggregator.js

1. targetDate Extraction:

2. getAdvanced(node) Utility Function:

Step 3: Create Countdown Component

countdown.js

countdown.module.css

index.js

1. src/components/Countdown/countdown.js

2. src/components/Countdown/detect.js

3. src/components/Countdown/index.js

Step 4: Set up the Talon

Repository

References

Step 1: Modify `local-intercept.js`

Step 2: Create `configAggregator.js`

1. `targetDate` Extraction:

2. `getAdvanced(node)` Utility Function:

`countdown.js`

`countdown.module.css`

`index.js`

1. `src/components/Countdown/countdown.js`

2. `src/components/Countdown/detect.js`

3. `src/components/Countdown/index.js`