Version: 3.x

Add a new attribute

Front-Commerce allows you to leverage Magento attributes in your application. This guide explains the different steps involved by going through a concrete example.

Let's say we want to add a new element to display on a product's page (for instance, a product's rate). You will have to:

Add an attribute to your Magento 2.
Expose the attribute in your GraphQL schema.
Display it on screen.

Add a value to your database

The process to do so may vary with the backend software you are using. For Magento 2 (used in this example), you can refer to How to Create Product Attributes in Magento 2.

Expose the attribute in your GraphQL schema

warning

This section follows the Extend the GraphQL schema guide. We won't go into too much detail here, so please refer to the guide if you need more information.

We want to display the rate of a product on the product page. To keep it simple, it will only consist in displaying a number, which can be manually edited by the merchant. This feature will be stored in a new extension called ratings.

Let's create a new extension along with its folder structure. At the root of your repository, type the following command.

mkdir -p extensions/ratings

Create the extension

Let's create our extension :

import { defineExtension } from "@front-commerce/core";

export default function ratings() {
  return defineExtension({
    name: "ratings",
    theme: "extensions/ratings/theme",
    meta: import.meta,
  });
}

And add the extension we just made to Front-Commerce. Edit the front-commerce.config.ts file (root folder) as shown below to do so.

import { defineConfig } from "@front-commerce/core/config";
import themeChocolatine from "@front-commerce/theme-chocolatine";
import storesConfig from "./app/config/stores";
import magento2 from "@front-commerce/magento2";
import ratings from "extensions/ratings";

export default defineConfig({
  extensions: [themeChocolatine(), magento2({ storesConfig }), ratings()],
  // ...
});

Extend the Product definition

First, we need to tell the server how to customise the GraphQL schema. To do so, we will create graphQL module and extend Product to add our rate.

extensions/ratings/graphql/index.ts
import { createGraphQLModule } from "@front-commerce/core/graphql";

export default createGraphQLModule({
  namespace: "Ratings",
  typeDefs: /* GraphQL */ `
    extend type Product {
      rate: Float
    }
  `,
});

Implement the resolver

We must now define what Front-Commerce should fetch when rate is requested in a GraphQL query; in other words we must write the code that will resolve the queries for the rates.

Create a file named runtime.ts and type the following code. It implements the runtime with its resolvers.

extensions/ratings/graphql/runtime.ts
import { createGraphQLRuntime } from "@front-commerce/core/graphql";

export default createGraphQLRuntime({
  resolvers: {
    Product: {
      rate: ({ rate }) => parseFloat(rate),
    },
  },
});

And load the runtime in the graphQL module :

extensions/ratings/graphql/index.ts
import { createGraphQLModule } from "@front-commerce/core/graphql";

export default createGraphQLModule({
  namespace: "Ratings",
  typeDefs: /* GraphQL */ `
    extend type Product {
      rate: Float
    }
  `,
  loadRuntime: () => import("./runtime"),
});

Declare the module

If we want our code to be taken into account when the module is loaded, we must reference it.

import { defineExtension } from "@front-commerce/core";

export default function ratings() {
  return defineExtension({
    name: "ratings",
    theme: "extensions/ratings/theme",
    meta: import.meta,
    graphql: {
      modules: [ratingsModule],
    },
  });
}

Discover the playground

By typing yourhostname/graphql (in our case localhost:4000/graphql) in your browser address bar, you can access a GraphQL playground with a nice GUI to test your queries.

You will need to restart the application to access the updated schema in the playground.

http://localhost:4000/graphql
{
  product(sku: "yourSKUhere") {
    name
    rate
  }
}

From this GraphQL query, you should get a JSON content that looks like this:

{
  "data": {
    "product": {
      "name": "Your product name",
      "rate": // the value stored in your backoffice (Magento 2 in this case)
    }
  }
}

Displaying the result on screen

warning

This section follows the Override a component guide. We won't go into too much detail here, so please refer to the guide if you need more information.

Now that you have access to your attribute, you can display it however you want in your React application. In this example, we will add it on the product's page, in the right section.

How to find which files to edit

With React Dev Tools

With the React Dev Tools, you can easily find the component name :

Open the Dev Tools
Browse to the "Component" tab
Click on "Select an element in the page to inspect it"
Click on the section you want to find the name

React Dev Tools screenshot demonstrating that when you inspect a product page description, you find the product-sythesis component in component tab

Then you can search for that keyword in your node_modules/@front-commerce folder and you will find the right files.

With the inspector

On your web page, right click on the element you wish to edit, then click on Inspect Element. In the inspector, you can look for the class that holds the elements you want to edit. Here, the class is product-synthesis.

Inspector screenshot demonstrating that when you inspect a product page description, you find the product-sythesis class in the DOM

Then you can search for that keyword in your node_modules/@front-commerce folder and you will find the right files.

Overriding the files

In this example, the files to be overridden are ProductSynthesisFragment.gql and Synthesis.jsx both located at theme/modules/ProductView/Synthesis. Copy and paste them into extensions/ratings/theme/modules/ProductView/Synthesis.
See Override a component for more details.

Once you have created the new files, restart your application to ensure that these are used instead of the core ones.

Updating the query

In extensions/ratings/theme/modules/ProductView/Synthesis/ProductSynthesisFragment.gql, add the following query line. It means that the application will request the rate field as well when sending the query. (Depending on the version of Front-Commerce you are using, the content might differ slightly.)

extensions/ratings/theme/modules/ProductView/Synthesis/ProductSynthesisFragment.gql
#import "theme/components/organisms/Configurator/ProductConfiguratorFragment.gql"
#import "theme/modules/AddToCart/ProductStockFragment.gql"
#import "theme/modules/ProductView/ProductName/ProductNameFragment.gql"
#import "theme/modules/AddToCart/AddToCartFragment.gql"
#import "theme/modules/ProductView/GroupedItems/GroupedItemsFragment.gql"

fragment ProductSynthesisFragment on Product {
  sku
  rate
  ...ProductNameFragment
  ...ProductConfiguratorFragment
  ...ProductStockFragment
  ...AddToCartFragment
  ...GroupedItemsFragment
  groupedItems {
    product {
      sku
    }
  }
}

info

GraphQL queries can be split in Fragments and each fragment is supposed to live next to a component in order to easily request all the data needed for your component. Thus, since we need to display some new data on the ProductSynthesis component, we update the ProductSynthesisFragment.

We're almost there! In the file Synthesis.jsx, you can add some code to display the rate. Knowing React.js or at least HTML syntax is necessary to perform this step without impacting other items on the page.

// Many more things here
const ProductSynthesis = (props) => {
  const {
    product,
    // Many more things here
  } = props;
  return (
    <div className="product__synthesis">
      {/* Many more things here */}
      <div>Rate: {product.rate} / 5</div>
      {/* Many more things here */}
    </div>
  );
};

export default ProductSynthesis;