RFC 002 - PLPs on FastStore

[tlgimenes]

The goal of this document is to define how we handle Product Listing Pages (PLPs) in FastStore and how ecommerce platforms and cms's can integrate with our way of handling PLPs.

Glossary

• PLP - Product Listing Page. example
• PDP - Product Display Page. example

Context

Product listing pages (PLPs) are a very present entity in an ecommerce. They list products based by a criteria and usually have a sorting button to sort the listed products according to price, sales etc. Also, these pages usually have facets for filtering the search result. A sample of plp can be seen below:

In platforms like Shopify, there is one single way of having a PLP in your site. You need to create a Collection of products and link this collection to a PLP.

In other platforms, like VTEX, there are multiple ways of clustering products into a PLP. At VTEX, you can create cluster of products following a tree hierarchy called Category tree. Also, another criteria you can use for clustering products is using something called Brand. In VTEX you also have Collections.

Differently from pdps, plps have no standard path on an ecommerce website, mainly because a PLP can be used in all of the cases mentioed above.

This document proposes a new way of declaring and creating PLPs so we can cover all of the cases above mentioned.

Proposal

1. There is an entity called StoreCollection that defines how a plp is instantiated in faststore.
2. We are able to use the Gatsby Filesystem Route API for instantiating PLPs.
3. All sync data can be found inside StoreCollection.
4. Plugins can extend StoreCollection to add more sync data if needed
5. The base StoreCollection type has the following type in TypeScript:

interface StoreColletion {
  /** @description The path on the website to create the PLP */
  slug: string
  /** @description The parent collection */
  parent?: StoreColletion
  /** @description Seo tags */
  seo: {
    title: string
    decription: string
  }
  /**
   * @description Params to retrieve the products of this PLPs. 
   * This can be the id of the collection or the search params for a search page.
   * 
   * TODO: This can be improved once we have an standard graphql layer for the faststore
   */
  searchParams: any
}

How to use it

After sourcing the above mentioned StoreCollection, we can create the PLPs with the following filesystem structure

.
└── src
    └── pages
        └── {StoreCollection.slug}
            ├── [...].tsx
            └── index.tsx

Where index.tsx is the static plp, and [...].tsx is the client-side, dynamic page used for facets.

How to use it with VTEX

At VTEX, we have many possible sources for StoreCollection instances. There is a category tree admin, a brand admin and a product cluster admin. Sadly, none of them have all the necessary fields of a StoreCollection. In category tree for example, you have the slug and seo parts of a StoreCollection, however you don't have the searchParams (used for ordering the product for instance). In the product cluster admin you don't even have the seo or slug fields.

Proposal

To solve the aforementioned problem for VTEX, I propose a unified place that will have all params needed to instantiate a PLP on the store, the CMS.
In my proposal, the CMS is the source of truth for all PLPs in the site. This means that if you created/modified a category tree of a store or if you have a new brand, this will only reflect on the store once the user creates/modifies their counterpart on the CMS. Also, the CMS contains all Seo related data, so if you change/modify those on the category tree of VTEX admin, nothing happens.

FAQ

• Does doing this locks us on VTEX CMS?
  No, since we are moving everything to the CMS, this should be easy to do on other CMSs too and the integration should follow the same code of our CMS plugin.

• The data on VTEX admin is not a source for my FastStore website?
  Yes, think that the category/brand/collection admins are there just to group similar products into a cluster that can be used by the CMS to create a page on your store

• How do you plan to rolling this out?
  I'm going to create a script that goes through the store's apis and create the pages on the CMS. After this, we can change the store's implementation and use the CMS data instead

• How about the setup of new stores?
  I'm goinig to add this script into the CMS plugin, so whenever you run the store in a newly created store it will upload and create all the necessary data on the CMS.

Final thoughts.

After these changes I think we will be able to move all search related queries to the store's implementations and get closer to our open beta since all queries will be now on the store and not on the theme

[emersonlaurentino]

I agree. But I don't like the name StoreCollection because we have some ways of clustering products on PLP, and Collection is one. So, I'm suggesting changing the name to StoreProductList. Sound to me less confusing.

[emersonlaurentino]

But is exactly the name collection that confuses everything. I agree with you about product collection is a term for grouping products, but is the definition of collection and no for ways of clustering products. We need a name to group all ways, and collection is only one.

[tlgimenes]

I don't think so. I think we use the name collection in VTEX in the wrong way. The new catalog is not even using the collection concept anymore. Their idea is to create cluster of products. We could call this cluster of products Collection in our framework. I guess this is good because it is closer to Shopify's collection and easier to understand when coming from the source shopify plugin to our framework, don't you think so?

[emersonlaurentino]

so, alright then!

[davicostalf]

The new catalog is not even using the collection concept anymore. Their idea is to create cluster of products.

@tlgimenes, do you know if they intend to use the term "cluster" in the user-facing UI? It seems to me like it's a very technical term, and that "collection" is more approachable.

[tlgimenes]

In the figmas I've seen they don't have a screen for creating these clusters. You kind of just group the products in the same context of the page you are creating

[davicostalf]

PDP - Product Display Page. example

PDP means Product Details Page

however you don't have the searchParams (used for ordering the product for instance)

Can you please detail what's included or should be included in the searchParams?

[davicostalf]

These are the ones?

properties: {
from: {
type: 'number',
title: 'de',
},
to: {
type: 'number',
title: 'ate',
},
collection: {
type: 'string',
title: 'Colecao',
},
hideUnavailableItems: {
default: true,
type: 'boolean',
title: 'Esconder items indisponiveis',
},
orderBy: {
type: 'string',
enum: [
'OrderByScoreDESC',
'OrderByPriceDESC',
'OrderByPriceASC',
'OrderByTopSaleDESC',
'OrderByReviewRateDESC',
'OrderByNameDESC',
'OrderByNameASC',
'OrderByReleaseDateDESC',
'OrderByBestDiscountDESC',
],
enumNames: [
'Relevance',
'Price: High to Low',
'Price: Low to High',
'Sales',
'Reviews',
'Name, ascending',
'Name, descending',
'Release date',
'Discount',
],

[tlgimenes]

Not really, searchParams is an any type. This could also work on shopify. This schema only work on vtex

[tlgimenes]

For our specific case on our CMS, I'd have something like:

{
  "title": "StoreCollection",
  "description": "Definition of a Collection for the CMS",
  "type": "object",
  "required": [
    "seo",
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "title": "Page path on your website",
      "default": "/path/to/the/page"
    },
    "seo": {
      "type": "object",
      "title": "Seo",
      "required": [
        "title",
        "description"
      ],
      "properties": {
        "title": {
          "type": "string",
          "title": "Title Tag",
          "default": "Page's Title Tag"
        },
        "description": {
          "type": "string",
          "title": "Meta tag description",
          "default": "Page's meta tag description"
        }
      }
    },
    "ui": {
      "type": "object",
      "title": "UI Related parameters",
      "properties": {
        "orderBy": {
          "type": "string",
          "enum": [
            "price:desc",
            "price:asc",
            "orders:desc",
            "name:desc",
            "name:asc",
            "release:desc",
            "discount:desc",
            ""
          ],
          "enumNames": [
            "Price: High to Low",
            "Price: Low to High",
            "Sales",
            "Name, descending",
            "Name, ascending",
            "Release date",
            "Discount",
            "Default"
          ]
        }
      }
    },
    "remoteId": {
      "title": "Choose the product cluster to create from",
      "type": "object",
      "anyOf": [
        {
          "title": "Category",
          "properties": {
            "categoryId": {
              "type": "string"
            }
          }
        },
        {
          "title": "Brand",
          "properties": {
            "brandId": {
              "type": "string"
            }
          }
        },
        {
          "title": "Collection",
          "properties": {
            "clusterId": {
              "type": "string"
            }
          }
        }
      ]
    }
  }
}

[davicostalf]

This "Choose the product cluster to create from" is what you're proposing for now considering our current Catalog, but you imagine that in the future it would be through here that the user would list the products and create the groups?

[iaronaraujo]

"Since we are moving everything to the CMS, this should be easy to do on other CMSs too and the integration should follow the same code of our CMS plugin."
Was this tested or is this an assumption?

[emersonlaurentino]

at first, assuming. but we can do a POC, what do you think?

[iaronaraujo]

I think that's a good idea, but it might be good to change the text until we really figure this out!

[iaronaraujo]

It seems that this idea appeared through benchmarks, right? Do we also have any user research that backs this feature up? cc @davicosta99

[davicostalf]

No, we still don't have a benchmark on how other commerce platforms and CMSs handle product listing pages.

[igorbrasileiro]

@tlgimenes can you explain the advantages of these changes?

[tlgimenes]

Sure! Today people don't really have control over their site urls. If you create a category on your category tree, this will automatically generate urls on your site with the url's being the slugified name of this category. This is the same case for brands.

For some merchants, this is ok and it's how they operate. However, for other, more complex merchants, they create categories/brands for clustering products to achieve a certain business capability and do not want to have urls on their site based on their catalog setup. This is the case for grocery/marketplaces that have lots of brands but they don't want to have pages for every brand on their site.

This RFC allows us to split the responsibilities of creating and managing the catalog from actually creating pages on the website, allowing these more complex stores to decide which pages exist on their store. A nice side effect this rfc causes is having all store-related page setup in one single place, the CMS, instead of being scattered across VTEX modules.

[davicostalf]

This RFC allows us to split the responsibilities of creating and managing the catalog from actually creating pages on the website, allowing these more complex stores to decide which pages exist on their store.

Something we need to investigate is whether this would worsen the experience for stores that don't have this complexity.

A nice side effect this rfc causes is having all store-related page setup in one single place, the CMS, instead of being scattered across VTEX modules.

Products would still have page information defined through the Catalog, right?

[tlgimenes]

Products would still have page information defined through the Catalog, right?

Yes, however, talking to the catalog team, they want to remove the SEO info from catalog and move it somewhere else. This somewhere else may be the CMS too

[vibegui]

This, for me, is the largest benefit. Separation of concerns. We should strive to always make systems simpler.

[tlgimenes]

Ok guys, after talking to some more people and showing this RFC to our customers I think I found a good balance between the solutions.

I think the main debate in here arises from how customers use the VTEX platform. As I said before, VTEX has 3 ways of creating a PLP. It can be via Categories, Brands and Collections (also known as product clusters). Categories and Brands have a dedicated admin for changing SEO properties (title and meta tag description) and have a well defined path on the store. For instance, if you create a brand named Awesome Brand, this brand will be available at /awesome-brand. Product clusters, on the other hand, have no admin for setting their title or meta tag description and have no standard path on the store. This is because collection are only a way of clustering products together. These clusters can be used for creating shelves, landing pages and other things.
One thing Categories/Brands/Collections have in common is that none of them have an admin for:

1. Adding banner images to the PLP
2. Setting search ordering of the products.

However, when building a PLP, our customers demand for ways of sorting the products and adding banners. In short, for building a PLP, we need the following info:

1. SEO (title, description and canonical)
2. Path of the page
3. Search Params, like product ordering and other params
4. Banners of the page.

This is the StoreCollection entity I proposed on the first iteration. If we have this entity, we are able to solve all basic needs for PLPs on an ecommerce. The problem now is how can we fill this infos for Categories,Brands,Clusters.
On my first iteration, I proposed all of these info to be filled on the CMS. If it wasn't on the CMS, it would not generate a StoreCollection, which, in turn, it would not generate a page on the store. After showing this to some of our customers and the catalog team, they didn't really like the solution because it means the user would not register Categories/Brands info on the Categories admin but would rather register on the CMS.
My first proposition on this iteration is that:

1. For Categories and Brands
   1.1. All categories and brands present on the catalog have a corresponding page on the website
   1.2. SEO data is NOT editable on the CMS and is only editable on the categories admin
   1.3. Path is predetermined by the catalog logic
   1.4. Search params are editable via CMS. If the user does not create a content for that specific page the search params will be the default ones
   1.5. Banners are ediable via CMS. If the user does not create a specific content for that Brand/Category, no banners will be set for the corresponding StoreCollection entity
2. For product Clusters:
   2.1 SEO/Path/SearchParams/Banners are all editable via CMS and if no content is created on the CMS, no StoreCollection will be created and thus, no page for this collection will be rendered.

The aforementioned proposition works fine on well behaviored catalogs. However, we have some customers where their brand list or category tree should not have a one-to-one relationship with the pages being created. This is the case for some grocery stores, where they don't want to have one brand page for each brand on their brand list, and this is the case for stores that share their catalog among many VTEX's tenants, where each category should create a page on each tenant.
The way we currently solve this problem is that we ask for these store maintainers a .json containing a list of brands/categories they want to generate on each store, save this json in a file inside the store's repo and use it for generating the PLPs.
The problem with this approach is that whenever the user wants to change the generated pages or simply rename a category, it needs to ask for their dev team (agency) to update the store.
To make our business users free from a dev team, I propose a second mode of using FastStore at VTEX. This mode works exactly like the first proposition, however with 1.1. removed. This means that only PLPs registered on the CMS will have a StoreCollection sourced in the GraphQL layer of FastStore, dropping the need of the json that exists on these store's repos.

Note that all described above is for sourcing the StoreCollection entity. If the user wants, it can drop using StoreCollection for creating pages and create their own way of creating pages.

TL-DR

I propose that:
0. Creation of an entity in the FastStore data layer called StoreCollection. This entity has all that's needed for rendering a PLP, a.k.a, SEO/path/searchParams/banners

1. SEO for Brands/Categories is still managed by their respective admins. Side note is that the catalog team still want to keep supporting it.
2. SEO/path for Collections is managed on the CMS.
3. Search Params/Banners are set via CMS for Categories/Brands/Clusters
4. There are two sourcing modes for StoreCollection.
   4.1. catalog-first: where all brands/categories have a corresponding StoreCollection. This works fine for well behaved catalogs
   4.2. cms-first: where StoreCollection are only sourced for brands/categories that are registered on the CMS

[vibegui]

Excellent iteration. One clarification question: where/how do I choose the sourcing mode for my site? Is it per-site or per-account?

[tlgimenes]

This is a parameter of the plugin. So this is a per gatsby project setting

[victorhmp]

This looks really good!
The questions that I had while reading through the first iterations were pretty much all addressed here 😅 . You did an awesome job in showing the benefits this approach would bring to us and the clients. And if I understand correctly, there are no practical downsides for the clients, since their main pain point (that I can think of) would be solved by the catalog-first sourcing mode. Are there any more potential downsides for store admins that we should be aware of?

[davicostalf]

Really comprehensive explanation, Gimenes! I would only add two things:

• I don't think it would be appropriate for this entity to be called "StoreCollection" as it may be used for brands and categories as well. I believe there should only be one concept that uses the word "Collection" within VTEX, to avoid any confusion. My suggestion is "product listing", given that all these concepts (brands, categories, collections) will generate product listings pages.
• Related to Victor's question, I think there's one downside for store admins, but one that doesn't need to be addressed in this first iteration. Currently, through the VTEX Search admins, users can specify search rules that apply to multiple pages. I think we could design a recommended CMS schema that could allow them this same flexibility, without requiring 1 CMS document per page necessarily.