Gesso Drupal Commerce

Installation

pnpm add @acromedia/gesso-drupal-commerce @acromedia/gesso-commerce

Configuration

1. Set the environment variable for NEXT_PUBLIC_DRUPAL_URL in the .env file.
2. The @acromedia/gesso-drupal-commerce package depends on the drupal search api to be enabled on your drupal back end and to have search indicies configured for products and for product attribtues. By default this package assumes that the products index will have a machine name "products" and the attribtues index will have a machine name "attributes". Machine names can be included in the commerce provider config object under the "searchApi" key. See below.
3. The customer plugins require custom fields to be added to the drupal user and customer profiles to satisfy the gesso Customer interface. The user entity should have fields added for first name and last name. The customer profile entity/bundle should have a field added for a phone number. The machine names of the custom fields can vary particularly for pre-existing sites. Machine names can be included in the commerce provider config object under the "customerFields" key. See below.
4. The Gesso Drupal Commerce useProduct plugin can either use JSON:API or GraphQl by specifying either 'jsonapi' or 'graphql' in the configuration object. Note some additional configuration options are intended specifically for one method or the other.
5. Gesso Drupal Commerce by default expects the product image(s) field to be field_representative_image. If your site uses a different field name, you can set the productImageField key in the commerce provider config object. See below.
6. Gesso Drupal Commerce by default expects the product image media to be stored with a field name field_media_image. If your site uses a different field name you can set the productImageMediaField key in the commerce provider config object. See below.
7. The Gesso Drupal Commerce useProduct config can accept additionalProperties which is an array of graphql field name strings (camelCase) on the product or the product variations. This will append these fields to the grapql query and map them into the gesso response. This is not necessary for the jsonapi version of useProduct which includes all unmapped fields in the product data and variation data objects.
8. The Gesso Drupal Commerce config can accept field name overrides for product properties of "brand", "facets" and "stockLevel". Brand is a taxonomy entity reference field attached to the product. The facets fields are the facet names configured in jsonapi_search_api_facets setup. The stockLevel field is a field attached to the product. Note stock level is currently only used by the graphql version of useProduct.
9. The cart plugins require the drupal product variations to have an image field with a default name of field_image. If your site uses a different name, you can set the productVariationImageField key in the commerce provider config object. See below.
10. The Gesso Drupal Commerce config can accept an array of strings for checkout.projectFields which allow you to customise the checkout process to include additional information on the customer's order (e.g., notes). This configuration only supports direct entity attributes. It does not support entity reference fields. These custom fields can be mutated by including data for them in the Billing profile and Shipment profile data objects when calling updateBillingProfile and updateShipment.
11. The useAutocomplete plugin provides search suggestions by querying the Search API products index with a fulltext filter. It returns an array of suggestions, each containing a label, product ID, image URL, price, and link. It reuses the searchApi.productsIndex, productImageField, and productImageMediaField config values. Results are sorted by relevance and limited by the limit parameter (default 5). A minimum keyword length of 3 characters is enforced at the provider level.

{
   searchApi: {
      productsIndex: <your custom products index machine name (default: products)>,
      attributesIndex: <your custom attributes index machine name (default: attributes)>
   }
   customerFields: {
      phone: <your custom phone number machine name on the profile--customer (default: field_phone1)>,
      firstName: <your custom first name machine name on the user entity (default: field_first_name)>
      lastName: <your custom last name machine name on the user entity (default: field_last_name)>
   }
   additionalProperties: <An array of camelCase graphql field names>
   productImageField: <your custom product image field machine name (default: field_representative_image)>
   productImageMediaField: <your custom product variation image field machine name (default: field_media_image)>
   productVariationImageField: <you custom variation imagbe field machine name (default: field_image)>
   apiType: 'jsonapi' or 'graphql'. (default: 'graphql').
   productFields: {
      brand: <your custom brand name here> (default: field_brand)
      facets: {
        category: <your custom category facet name here> (default: category);
        brand: <your custom brand facet name> (default: brand)
      };
      stockLevel: <your custom stock level name here> (default: field_stock_level)
   }
   checkout: {
      projectFields: <an arry of field names that can be added to your order during checkout>
   }
}

Note: This is by no means the only configuration required for this module to work. For a comprehensive list of dependencies and permissions, consult the gesso drupal cms repository and the gesso documentation.

Testing

By default, cart and customer tests will run against mocks. If you want to run against the live API, add 'LIVE_TESTS=true' to your env