commercetools parameters

After you install the commercetools integration, the following parameter types are available. You can use these to incorporate content from commercetools into your components and compositions.

Parameter typeDescription
commercetools ProductSelect a single product from commercetools.
commercetools Product ListSelect multiple products from commercetools.
commercetools Product QuerySpecify search criteria that's used to select a single or multiple products from commercetools.
commercetools CategorySelect a specific product category.

This parameter type allows a Uniform user to select a single commercetools product.

To allow a user to select a product from commercetools, you must add a parameter to a component. The parameter is used to store the identifier to the selected product when the user selects a product.

  1. In Uniform, navigate to your component.

  2. Add a new parameter using the parameter type commercetools Product.

  3. The following values can be specified:

    NameDescription
    Category constraintsSelect specific categories that are allowed to appear as results in the product query. Note: Parent categories will include all child categories.
    Display fieldUsed to update which field is used for titles when previewing the results from the query.
    Restrict search–Master/VariantsAllows you to restrict the result to only include the product master, variants, or both. This can help to reduce the resultant JSON payload and improve site performance.
    Restrict search–LocaleAllows you to remove non-configured locales from results, further reducing potential JSON payload size.
    Restrict search–CurrencyAllows you to remove non-configured currencies from results, further reducing potential JSON payload size.
    RequiredIndicates whether the value is required when the component is used.
    parameter-config
    commercetools Product parameter configuration.

When you use a component with a commercetools Product parameter, by default no product will be selected. You are prompted to select a product.

  1. Click Select.

    edit-value-default
  2. Click the product you want to select.

    edit-value-filters

    About this step

    A couple of filters are available. The dropdown allows you to filter by category. The text box allows you to filter by product name.

  3. Click Accept to save your selection.

    edit-value-selected
  4. You will see details about the product you selected, including the name, category, and price.

    edit-value-saved

    About this step

    After your selection is saved, you are presented with the following options:

    • If you want to deselect the product, click the red X.

When a product is selected, Uniform only stores the identifier for the product. Your front-end application must retrieve the details for the product. Uniform provides an enhancer to simplify this process.

tip

Using the enhancer provided by Uniform saves you from having to write logic to interact directly with commercetools.

The following is an example of what Uniform stores for the parameter.

{
   "commercetoolsProduct": {
    "type": "commercetoolsProduct",
    "value": {
      "productIds": [
        "d4d087f8-d704-4c41-9d5a-52ca56177faa"
      ]
    }
  }
}

Uniform provides an enhancer so you don't need to write the API calls to commercetools to retrieve data for products.

tip

For more information about the enhancer, see the package documentation.

  1. Add the following npm packages to your front-end application:

    @uniformdev/canvas
    @uniformdev/canvas-commercetools
    
  2. Add the following file:

        import getConfig from 'next/config';
        import { ApiRoot, createApiBuilderFromCtpClient } from '@commercetools/platform-sdk';
        import { createClient } from '@commercetools/sdk-client';
        import { createAuthMiddlewareForClientCredentialsFlow } from '@commercetools/sdk-middleware-auth';
        import { createHttpMiddleware } from '@commercetools/sdk-middleware-http';
        import { createcommercetoolsEnhancer } from '@uniformdev/canvas-commercetools';
        import fetch from 'node-fetch';
        const commercetoolsAuthUrl = [!!! YOUR CT AUTH URL !!!];
        const commercetoolsProjectKey = [!!! YOUR CT PROJECT KEY !!!];
        const commercetoolsClientId = [!!! YOUR CT CLIENT ID !!!];
        const commercetoolsClientSecret = [!!! YOUR CT CLIENT SECRET !!!];
        const commercetoolsApiUrl = [!!! YOUR CT API URL !!!];
        const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({
        host: commercetoolsAuthUrl,
        projectKey: commercetoolsProjectKey,
        credentials: {
            clientId: commercetoolsClientId,
            clientSecret: commercetoolsClientSecret,
        },
        });
        const httpMiddleware = createHttpMiddleware({
        host: commercetoolsApiUrl,
        fetch,
        });
        const ctpClient = createClient({
        middlewares: [authMiddleware, httpMiddleware],
        });
        const apiRoot: ApiRoot = createApiBuilderFromCtpClient(ctpClient);
        export const commercetoolsEnhancer = createcommercetoolsEnhancer({
        apiRoot,
        projectKey: commercetoolsProjectKey,
        });
    

    About this step

    We recommend you moving the commercetools credentials to environment variables rather than hard-coding them in the front-end app.

  3. In a text editor, open the file where you retrieve the composition definition from Uniform.

    About this step

    You are looking for the code calls the async function getComposition. The code below assumes the object returned is set in a variable composition.

  4. Add the following import statements:

    import { EnhancerBuilder, enhance } from '@uniformdev/canvas';
    import { 
        CANVAS_COMMERCETOOLS_PARAMETER_TYPES,
    } from '@uniformdev/canvas-commercetools';
    import { 
        commercetoolsEnhancer 
    } from '../lib/commercetoolsEnhancer';
    
  5. Add the following code:

    await enhance({
        composition,
        enhancers: new EnhancerBuilder().parameterType(
        CANVAS_COMMERCETOOLS_PARAMETER_TYPES, 
        commercetoolsEnhancer,
        ),
        context: {},
    });
    

    About this step

    This registers the enhancer to be used for any occurrence of the commercetools Product parameter.

Next steps

Now, the parameter value in the composition is mutated to include the field values for the selected commercetools product (instead of just being identifiers).

This parameter type allows a Uniform user to select multiple commercetools products.

To allow a user to select multiple products from commercetools, you must add a parameter to a component. The parameter is used to store the identifiers to the selected products when the user selects products.

  1. In Uniform, navigate to your component.

  2. Add a new parameter using the parameter type commercetools Product List.

  3. The following values can be specified:

    NameDescription
    Category constraintsSelect specific categories that are allowed to appear as results in the product query. Note: Parent categories will include all child categories.
    Display fieldUsed to update which field is used for titles when previewing the results from the query.
    Restrict search–Master/VariantsAllows you to restrict the result to only include the product master, variants, or both. This can help to reduce the resultant JSON payload and improve site performance.
    Restrict search–LocaleAllows you to remove non-configured locales from results, further reducing potential JSON payload size.
    Restrict search–CurrencyAllows you to remove non-configured currencies from results, further reducing potential JSON payload size.
    RequiredIndicates whether the value is required when the component is used.
    parameter-config
    commercetools Product List parameter configuration.

This parameter type works the same way as commercetools Product, adding the ability to select multiple products from the list when the parameter value is edited.

edit-parameter-value
Example of the editing interface for an commercetools Product List parameter on a component.

This parameter type uses the same enhancer as the commercetools Product parameter type.

The following is an example of what Uniform stores for the parameter.

{
  "commercetoolsProductList": {
    "type": "commercetoolsProductList",
    "value": {
      "productIds": [
        "d4d087f8-d704-4c41-9d5a-52ca56177faa",
        "422acfa6-69d1-43e2-b519-2f82517605eb"
      ]
    }
  }
}

This parameter type allows a Uniform user to configure a query that will determine which commercetools products are retrieved.

For a user to select categories, you must add the parameter to a component. The parameter is used to store the selected categories from the category selection UI.

  1. In Uniform, navigate to your component.

  2. Add a new parameter using the parameter type commercetools Category.

  3. The following values can be specified:

    NameDescription
    Category constraintsSelect specific categories that are allowed to appear as results in the product query. Note: Parent categories will include all child categories.
    Display fieldUsed to update which field is used for titles when previewing the results from the query.
    Restrict search–Master/VariantsAllows you to restrict the result to only include the product master, variants, or both. This can help to reduce the resultant JSON payload and improve site performance.
    Restrict search–LocaleAllows you to remove non-configured locales from results, further reducing potential JSON payload size.
    Restrict search–CurrencyAllows you to remove non-configured currencies from results, further reducing potential JSON payload size.
    add-parameter-to-component
    commercetools Product Query parameter configuration.

Configuring this parameter type involves specifying the way a product search should work. You are able to control the following search settings:

FieldDescription
CategoriesFilter the query based on the category a product is within. Multiple categories can be selected, and parent categories will include all child categories.
CountThe maximum number of products that are returned.
KeywordOnly products whose names match the specified keyword(s) are included.
SortThe product property used to sort the products that are returned.
Sort OrderWhether the products should be sorted in ascending or descending order.
edit-parameter-value
Example of the editing interface for a commercetools Product Query parameter on a component.

This parameter type uses the same enhancer as the commercetools Product parameter type.

note

The parameter settings are stored in Canvas in a slightly different format. Instead of a single product ID being stored, the value stores the settings used to perform the search.

{
  "commercetoolsProductQuery": {
    "type": "commercetoolsProductQuery",
    "value": {
      "options": {
        "count": 3,
        "categories": [
          "4e90d0fd-5344-4e3f-b85b-2cd4fabd746a",
          "6efb29b3-a3c9-4d12-9eda-7d04f9d38cf3",
          "bf3c0adc-0472-4439-b0e4-16389df009bd"
        ],
        "brand": "",
        "keyword": "Blue",
        "sort": "Name",
        "sortOrder": "desc"
      },
      "searchLocale": "en"
    }
  }
}

This parameter type allows a Uniform user to select one or multiple categories to be set as the value of the parameter. This can be useful when composing pages where a global category filter needs to be set, or to access the category description stored in commercetools through the enhancer.

For a user to configure a query to determine the products from commercetools to retrieve, you must add the parameter to a component. The parameter is used to store the query settings used to perform the search.

  1. In Uniform, navigate to your component.

  2. Add a new parameter using the parameter type commercetools Product Query.

  3. The following values can be specified:

    NameDescription
    Allow multi selectDetermines if a user is able to select one or many categories within the category selector.
    RequiredIndicates whether the value is required when the component is used.
    add-parameter-to-component
    commercetools Category parameter configuration.

When you use a component with a commercetools Category parameter, by default no categories will be selected. You are prompted to select a category.

  1. Click Select.

    edit-value-default
  2. Click the category or categories you would like to select.

    edit-value-select

    About this step

    Sub-categories can be accessed by expanding the parents category with the "+" button on the left-hand side of the category.

  3. Click Save and Close to save your selection.

    edit-value-selected
  4. You will see details about the category or categories you have selected, including the name and slug.

    edit-value-saved

    About this step

    After your selection is saved, you are presented with the following options:

    • If you want to deselect the product, click the Unlink button.
    • If you want to add/edit the categories, click the Select Category button.

This parameter type uses the same enhancer as the commercetools Product parameter type.

note

The parameter settings are stored in Canvas in a slightly different format. Instead of a single product ID being stored, the value stores the settings used to perform the search.

{
  "type": "commercetoolsProductQuery",
    "commercetoolsCategory": {
      "type": "commercetoolsCategorySelector",
      "value": {
        "categoryIds": [
          "27b3ca02-0a81-4afb-871e-050d214815ca",
          "a9ca1554-55cc-4fe3-bfc3-8157c9368b17"
        ],
        "restrictLocale": "en"
      }
    }
}