DEV Community: Chris Brabender

Custom Segmentation Condition in Adobe Commerce

Chris Brabender — Mon, 21 Jun 2021 17:45:30 +0000

Intro

Adobe Commerce (fka Magento Commerce, fka Magento Enterprise Edition) gives administrators the ability to create dynamic Customer Segments based on a predetermined set of available conditions. The condition builder is the same familiar interface as Catalog / Shopping Cart Price rule conditions allowing for combining multiple conditions, different input types and more flexibility.

Adobe Commerce User Guide Documentation for Customer Segments available here

This is great for data that is already available (order history, products in cart, customer attributes etc) but there is not necessarily an easy way to create a new condition based on a custom column or data source.

Example Requirement

We have a client that uses a store locator module that allows a guest or customer to select a Favourite Store for their session. Given this selection, we want to create a segment based on this and display an appropriate store banner to the user.

What is important to note in this example is that we need this to work for both Guest and Registered Customers, this eliminates customer attributes as our source of information, we'll need to reference this elsewhere.

How we solved it

It actually wasn't that difficult in the end to implement a custom condition! All it took was was a custom module with 5 files (including registration.php and module.xml) to achieve a custom segmentation condition.

Getting your condition in the list

The first thing you need to look at is where you want your condition to show up in the list, as you need to create a plugin. Looking through the conditions you will see an asterisks (*) next to several of them, this indicates the condition is applicable to both Visitor and Registered Customers so we opted to add to one of these, the Shopping Cart one.

You will need to create a plugin like below:

<type name="Magento\CustomerSegment\Model\Segment\Condition\Shoppingcart">
    <plugin name="myvendor_mymodule_segmentcondition_add_custom_customersegment_condition"
            type="MyVendor\MyModule\Plugin\CustomerSegment\Model\Segment\Condition\ShoppingcartPlugin" />
</type>

Your ShoppingcartPlugin file should receive the array of results from the Shoppingcart conditions and add a new one to the array:

class ShoppingcartPlugin
{
    public function afterGetNewChildSelectOptions(
        \Magento\CustomerSegment\Model\Segment\Condition\Shoppingcart $subject,
        array $result
    ): array
    {
        $conditions = [
            'value' => [
                [
                    'value' => \Magento\CustomerSegment\Model\Segment\Condition\StoreLocator\SelectedStore::class,
                    'label' => __('Selected Store'),
                    'available_in_guest_mode' => true
                ]
            ]
        ];

        return array_merge_recursive($result, $conditions);
    }
}

Our new condition should now show up in this list like so

The Condition

Important

First we need to talk about the naming of the class above. As you might have seen we reference a class called \Magento\CustomerSegment\Model\Segment\Condition\StoreLocator\SelectedStore, but this is not in our namespace, so how does this work?

Well, if you look at the ConditionFactory class in the CustomerSegment module, Magento has placed a restriction on the class names that can be used to generate a condition:

$classNamePrefix = 'Magento\CustomerSegment\Model\Segment\Condition\\';
if (false === strpos($className, $classNamePrefix)) {
    $className = $classNamePrefix . $className;
}
$condition = $this->_objectManager->create($className, $data);

This means anything in our namespace fails to load (an exception is thrown), so we use a virtualType to get around this. In our di.xml file we can add:

<virtualType name="Magento\CustomerSegment\Model\Segment\Condition\StoreLocator\SelectedStore"
     type="MyVendor\MyModule\Model\Condition\StoreLocator\SelectedStore" />

The class

I am going to suggest referring to one of the existing condition classes in the CustomerSegment module as inspiration here, for example: vendor\magento\module-customer-segment\Model\Segment\Condition\Shoppingcart\Itemsquantity.php

Assuming you are going to copy+paste this class, we need to change a few things to get it to work for our setup. First up, the type in the contsructor needs to be adjusted:

public function __construct(
    \Magento\Rule\Model\Condition\Context $context,
    \Magento\CustomerSegment\Model\ResourceModel\Segment $resourceSegment,
    \Magento\Quote\Model\ResourceModel\Quote $quoteResource,
    array $data = []
) {
    parent::__construct($context, $resourceSegment, $data);
    $this->setType(\Magento\CustomerSegment\Model\Segment\Condition\StoreLocator\SelectedStore::class);
    $this->setValue(null);
    $this->quoteResource = $quoteResource;
}

We then need to define which events are relevant for us, we'll create a new one.

public function getMatchedEvents()
{
    return ['store_locator_store_changed'];
}

You'll want to update the select options and html output so the strings match what you are trying to create here, these are used once an administrator has selected the condition from the dropdown and are setting their requirements.

public function getNewChildSelectOptions(): array
{
    return [
        'value' => $this->getType(),
        'label' => __('Selected customer Store'),
        'available_in_guest_mode' => true
    ];
}

public function asHtml()
{
    return $this->getTypeElementHtml() . __(
        'Selected Customer Store %1 %2:',
        $this->getOperatorElementHtml(),
        $this->getValueElementHtml()
    ) . $this->getRemoveLinkHtml();
}

SQL Matching

CustomerSegment conditions use SQL queries to select visitors/customers that match the defined rules. To allow our Selected Store to be selected via SQL, we have added a column to the quote table where we store the currently selected store. This means we can re-use the queries from the Itemsquantity condition with only a small tweak to query from our column, instead of the qty one.

You'll notice in the below snippet that $select->where("quote.store_locator_store {$operator} ?", $this->getValue()); is basically the only change we've made. We are keeping the {$operator} value there to ensure that standard rule configuration (equals, does not equal, is in, contains etc) work as expected.

public function getConditionsSql($customerId, $website, $isFiltered = true)
{
    $table = $this->getResource()->getTable('quote');
    $operator = $this->getResource()->getSqlOperator($this->getOperator());

    $select = $this->getResource()->createSelect();
    $select->from(['quote' => $table], [new \Zend_Db_Expr(1)])->where('quote.is_active=1');
    $this->_limitByStoreWebsite($select, $website, 'quote.store_id');
    $select->limit(1);
    $select->where("quote.store_locator_store {$operator} ?", $this->getValue());
    if ($customerId) {
        // Leave ability to check this condition not only by customer_id but also by quote_id
        $select->where('quote.customer_id = :customer_id OR quote.entity_id = :quote_id');
    } else {
        $select->where($this->_createCustomerFilter($customerId, 'quote.customer_id'));
    }

    return $select;
}

private function executeSql($customer, $websiteId, $params, $isFiltered = true)
{
    $table = $this->getResource()->getTable('quote');
    $operator = $this->getResource()->getSqlOperator($this->getOperator());

    $select = $this->getResource()->createSelect();

    if ($isFiltered) {
        $select->from(['quote' => $table], [new \Zend_Db_Expr(1)])->where('quote.is_active=1');
        $select->limit(1);
    } else {
        $select->from(['quote' => $table], ['customer_id'])->where('quote.is_active=1');
    }
    $select->where(
        'quote.store_id IN(?)',
        $this->getStoreByWebsite($websiteId)
    );

    $select->where("quote.store_locator_store {$operator} ?", $this->getValue());
    if ($isFiltered) {
        // Leave ability to check this condition not only by customer_id but also by quote_id
        $contextFilter = ['quote.entity_id = :quote_id'];
        if (!empty($params['customer_id'])) {
            $contextFilter[] = 'quote.customer_id = :customer_id';
        }
        $select->where(implode(' OR ', $contextFilter));
    } else {
        $select->where('customer_id IS NOT NULL');
    }
    $matchedParams = $this->matchParameters($select, $params);
    $result = $this->quoteResource->getConnection()->fetchCol($select, $matchedParams);
    return $result;
}

Now, we can save our new segment in the admin panel and trigger a segment data refresh (assuming we have populated a store in the quotes table).

NOTE: Segment Data Refresh is queue based so you'll need to run the following queue:consumer command after you have clicked "Refresh Segment Data"

php bin/magento queue:consumers:start matchCustomerSegmentProcessor

Once that has processed, you should see your matched customer in the grid! NOTE: The grid will only show Registered customers, this does not mean it's not working for Visitors (they just won't even show here).

Keeping our matched users up to date

Now that we have our condition all built, we need to make sure that when a user (Visitor or Registered Customer) changes their store, they are added to the correct segment. This is handled via events, you can see the standard events Magento listens to here vendor\magento\module-customer-segment\etc\frontend\events.xml

We have a couple of ways we can implement our own, the simplest could be to dispatch our store_locator_store_changed (we defined earlier) when the customer changes their selected store and then listen to that event, sending it to the ProcessEventObserver class such as:

<event name="store_locator_store_changed">
    <observer name="mymodule_customersegment_store_changed" instance="Magento\CustomerSegment\Observer\ProcessEventObserver"/>
</event>

Bonus tips

Re-save your segment when changing SQL

Segment SQL queries are saved in to the magento_customersegment_segment table when you create the segment, this means if you are in development of your new condition and have changed the SQL in the Class, you'll need to re-save the segment in the admin to pull down and save your latest SQL changes. You may not see your matched customers reflected correctly until you do the save.

Experiment

Segment conditions have A LOT of options. For example, we are just using a basic numeric input type here but you can use a select here instead and populate it with a list of your Stores from a data model

protected $_inputType = 'numeric';

You can also create a Combine condition, which is more complicated in its setup but also in its capabilities.

Simplifying Targetables in PWA Studio

Chris Brabender — Wed, 31 Mar 2021 19:11:39 +0000

After the positive feedback on my first Simplifying Styling in PWA Studio article (thanks to everyone who gave me feedback there), I have put together the next iteration of the concept which focuses on Simplifying Targetables in PWA Studio.

I'm not going to go into the details on how to use Targetables, that has been covered in a few places which you can refer to:

https://marcin-kwiatkowski.com/how-to-extend-pwa-studio-with-new-features (thanks for the shout out Marcin!)
https://magento.github.io/pwa-studio/pwa-buildpack/reference/targetables/TargetableModule/

What I am going to cover here is the problem with the local-intercept.js file.

What problem?

In our scaffolded PWA Studio project we have a single local-intercept.js file which is our starting point for working with Targets and Targetables.

Having a single file to do all of our work here will quickly make this file unruly and frankly, just enormous. This makes it difficult to identify customisations (for debugging, finding what has been done etc) and ensure we aren't trying to intercept the same component twice.

What is the fix?

Following a similar concept to the Simpliying Styling process, I am proposing a file naming convention and structure to automatically detect and load relevant intercept files for specific modules.

So what does the structure look like? Let's assume we want to intercept the Header component

@magento/venia-ui/lib/components/Header/header.js
We could create a new file in our local project like this - src/components/Header/header.targetables.js

Again if we wanted to intercept the ProductFullDetail component * @magento/venia-ui/lib/components/ProductFullDetail/productFullDetail.js)

We could create a src/components/ProductFullDeatil/productFullDetail.targetables.js file

This way we can more easily identify, categorise and isolate our intercepts. Making it much easier to customise the project.

So assuming we have these files in place, how do we load them? And how do we use them?

Updating local-intercept.js

We need to do a few things in our local-intercept.js file to identify and load these files. So we are going to use globby again to find our targetables files.

We are also going to use babel-plugin-require-context-hook/register to load the files inline and execute a function within those files (this means we can pass the component to our targetables files and run a standardised function to simplify things even more).

  // Access our Targetables object
const { Targetables } = require('@magento/pwa-buildpack');
const targetables = Targetables.using(targets);

// Define the path to @magento packages
const magentoPath = 'node_modules/@magento';

const globby = require('globby');
const path = require('path');

// Context loader allows us to execute functions in the targeted file
const requireContextLoader = require('babel-plugin-require-context-hook/register')();

// Find our .targetables.js files
(async () => {
    const paths = await globby('src/components', {
        expandDirectories: {
        files: ['*.targetables.js']
        }
    });

    paths.forEach((myPath) => {
        const relativePath = myPath.replace('.targetables', '').replace(`src/components`, `${magentoPath}/venia-ui/lib/components`);
        const absolutePath = path.resolve(relativePath);

        fs.stat(absolutePath, (err, stat) => {
        if (!err && stat && stat.isFile()) {
            // Retrieve the react component from our cache (so we can use it more than once if necessary)
            const component = getReactComponent(relativePath.replace('node_modules/', ''));

            /** 
             * Load the targetables file for the component and execute the interceptComponent function
             * We also pass in the component itself so we don't need to load it in the file
            */
            const componentInterceptor = require('./' + myPath);
            componentInterceptor.interceptComponent(component);
        }
        });
    });
})();


// Create a cache of components so our styling and intercepts can use the same object
let componentsCache = [];
function getReactComponent(modulePath) {
    if (componentsCache[modulePath] !== undefined) {
        return componentsCache[modulePath];
    }

    return componentsCache[modulePath] = targetables.reactComponent(modulePath);
}

And that is all we need in our local-intercept.js file in order to load and execute all our *.targetables.js files! We don't need to touch local-intercept.js ever again to execute targetables functionality.

Our *.targetables.js files

Within our *targetables.js files all we need to do is define our interceptComponent function and export it.

EG: src/components/Header/header.targetables.js

Here we are passing in the header.js component from Venia UI with the targetables functions ready to go. So we can simply do component.insertAfterJSX etc in our files.

const interceptComponent = (component) => {
    component.addImport('import MegaMenu from "../../../../../../src/components/MegaMenu"');
    component.insertAfterJSX('Link', '<MegaMenu />');
    component.setJSXProps('Link', {
        'className':'{classes.logoContainer}'
    });
}

exports.interceptComponent = interceptComponent;

And this can be repeated to intercept any other Venia UI component we like:

EG 2: src/components/Navigation/navigation.targetables.js

Here we are just removing the h2 element from the navigation.

const interceptComponent = (component) => {
    // Execute our JSX manipulation
    component.removeJSX('h2');
}

exports.interceptComponent = interceptComponent;

It's a pretty straight forward setup and I hope it will come in handy to help you manage your customisations for your new PWA Studio projects!

Please share and let me know if you have any feedback and/or if you implement this strategy!

Simplifying styling in PWA Studio

Chris Brabender — Wed, 03 Mar 2021 15:27:39 +0000

TLDR: It doesn't have to be difficult.

A short history

PWA Studio from Magento has been out and about in the wild for a couple of years now and over time they are slowly adding to the core product.

Originally Venia (the code name for the project) was seen as a reference storefront only but over time has grown in to the base starting point for new projects. This comes with a set of challenges not originally considered by the Magento team.

One of those key challenges is simply modifying or replacing the styling of a component. Until now that has been done in one of 3 ways:

Tree replacement
Taking and replacing the entire tree to get to the component you want to style, and then overriding the entire CSS file. This causes issues because you are taking on ownership of the entire code for all components in the tree, making it more difficult to maintain and upgrade.

Normal replacement module / webpack aliases
This focuses on using webpack to modify the file references in particular components and replacing them with a file in your own project. This approach is relatively solid but can become unwieldly with a long list of aliases to manage when you start
overriding hundreds of CSS files.

The alias approach can also be risky if file names are duplicated elsewhere.

config.resolve.alias = {
    ...config.resolve.alias,
    './productFullDetail.css': path.resolve('./src/components/ProductFullDetail/productFullDetail.css')
}

Fooman VeniaUiOverrideResolver
A great module from Fooman allowing you to overwrite any file in peregrine/venia-ui easily and following a simple pattern. I personally didn't like the folder structure this introduced to projects and was override only, not extend.

Reference - https://github.com/fooman/venia-ui-override-resolver

So what's different now?

Version 9.0 of PWA Studio introduced some new features and enhancements to the extensibility framework. Targetables gives us the opportunity to modify a React component without the need to override the entire component in our app.

The concept

How do I turn the standard Venia storefront into something custom for my clients?

Here's our starting point:

I wanted to explore how we could use the Targetables, the naming convention for styling attached to components and mergeClasses to simplify the entire process of updating styling.

The naming convention
PWA Studio follows a strict naming convention with regards to CSS files for components. Lets take Button as an example.

The Button component is made up of two files:

button.js
button.css

button.js imports button.css and uses that as the defaultClasses with the mergeClasses function from classify.

So what if we were to mimic that file structure in our local project? Following along with the Button example, if I was to create a file src/components/Button/button.css could I have that picked up automatically?

mergeClasses
mergeClasses, by default, takes the default styling from defaultClasses and merges them with anything passed in via props to the component.
Here we could add an addition set of classes that could be out local styling updates and make it look something like:

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

This would give us the flexibility of local styling on top of the default styling, but also the ability to pass in props styling for specific use cases across the application, which would update our local styling.

Putting it to work

We need two things to make this all work:

A way to identify any local files that extend default styling
A way to add them to our library components without overriding

Identifying local styling
globby is a great tool for recursively scanning directories to find files or folders matching specific criteria, so we need to add that to our project.

yarn add globby

Next, we are going to use our local-intercept.js file as the place we do most of the work here.

This script scans all directories in src/components and finds any CSS files. It then extracts the component from the folder names and tries to match that to a component in venia-ui, if it matches, we know we are trying to extend styling.

function localIntercept(targets) {
    const { Targetables } = require('@magento/pwa-buildpack');
    const targetables = Targetables.using(targets);

    const magentoPath = 'node_modules/@magento';

    const globby = require('globby');
    const fs = require('fs');
    const path = require('path');

    (async () => {
        /** Load all CSS files from src/components */
        const paths = await globby('src/components', {
          expandDirectories: {
            extensions: ['css']
          }
        });

        paths.forEach((myPath) => {
          const relativePath = myPath.replace('src/components', `${magentoPath}/venia-ui/lib/components`);
          const absolutePath = path.resolve(relativePath);

          /** Identify if local component maps to venia-ui component */
          fs.stat(absolutePath, (err, stat) => {
            if (!err && stat && stat.isFile()) {
              /** 
               * This means we have matched a local file to something in venia-ui!
               * Find the JS  component from our CSS file name 
               * */
              const jsComponent = relativePath.replace('node_modules/', '').replace('.css', '.js');
            }
          });
        });
    })();
}

Adding our styling
So now we know what CSS files we are extending, how do we tell our library components to use our styling?

Thats where Targetables come in to play. Taking our script above, we know what the JS Component is so we can just add this after the jsComponent line:

/** Load the relevant venia-ui component */
const eSModule = targetables.reactComponent(jsComponent);
const module = targetables.module(jsComponent);

/** Add import for our custom CSS classes */
eSModule.addImport(`import localClasses from "${myPath}"`);

/** Update the mergeClasses() method to inject our additional custom css */
module.insertAfterSource(
    'const classes = mergeClasses(defaultClasses, ',
    'localClasses, '
);

The script here loads an esModule and injects our localClasses into the top of the file as an import and then modifies the default mergeClasses from:

const mergeClasses(defaultClasses, props.classes);

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

Setting up some custom styles

The screenshot above shows the product detail page, so lets change up some of the styling on that page.

To do that we are going to create a new file in our project:

src/components/ProductFullDetail/productFullDetail.css

Now you can do a yarn watch and see the changes we are going to do live. As this customisation is applied at build time if you create a NEW file you will need to stop and start your project but if you modify a file you have already created the hot reload functions will work just fine.

Let's add the following to our css file, which will add a border around our Image Carousel:

.imageCarousel  {
    border: solid 1px black;
}

That's it. That's the blog, thanks for reading. Not really but this should have reloaded and should look a little broken, but this is a good thing.

What we've done here is modified just the imageCarousel class in our custom file and kept all the rest of the styling for the ProductFullDetail page which is great! Exactly what we wanted, but we've lost all our original styling for the imageCarousel.

This is good in some instances where we want to just replace all the styling for a particular class so having this full replacement as an option is great, but if we want to just modify one thing and inherit the rest, we able to use composes from CSS Modules to achieve this. All we need to do is composes imageCarousel from Venia like this:

.imageCarousel  {
    composes: imageCarousel from '~@magento/venia-ui/lib/components/ProductFullDetail/productFullDetail.css';
    border: solid 1px black;
}

Now our page is looking like it should, with our border.

That really is it now though. Thanks for reading! If you have any questions let me know on Twitter @brabs13 or via the #pwa slack channel in Magento Community Engineering.

If you put this into practice please share me a link so I can check out the work.