All ContributorsAll Contributors

The Order Configuration app, designed for B2B scenarios, displays a form responsible for collecting order data in a modal.

order-configuration-giforder-configuration-gif

Once the form is submitted, the order data collected will be available at Master Data and saved in the current VTEX session.

This app can be used to enable customization of all kinds of behaviors, such as custom prices, custom products, etc. Keep in mind the Order Configuration app does not offer these functionalities, it only enables other apps to do so.

Follow the steps below to install and set up the Order Configuration app in your store.

Step 1: Install the app

First, you must add the order-configuration app to your theme's dependencies in the manifest.json file:

dependencies: {
  "vtex.order-configuration": "2.x"
}

This will enable you to use the blocks exported by the order-configuration app. Check out the full list below:

Block nameDescription
order-configParent block only responsible for rendering its children blocks, that in turn build the Order Configuration component.
order-config.titleRenders the component title, that is, the message text displayed for users to present the component. On the image above, the component title is Order Configuration.
order-config.modalRenders the modal responsible for displaying the component content.
order-config.formRenders the component content, that is, a form to be filled out by users.

Step 2: Declare the required blocks

Add the order-config block in the Header component, as shown in the example below.

{
  "header-layout.desktop": {
    "children": [
      "flex-layout.row#1-desktop",
      "flex-layout.row#2-desktop",
      "flex-layout.row#3-desktop",
      "sticky-layout#4-desktop"
    ]
  },
  "flex-layout.row#3-desktop": {
    "props": {
      "blockClass": "menu-link",
      "horizontalAlign": "center",
      "preventHorizontalStretch": true,
      "preventVerticalStretch": true,
      "fullWidth": true
    },
    "children": [
      "[email protected]:menu#websites",
      "flex-layout.col#spacer",
+     "order-config#header",
      "[email protected]:menu#institutional"
    ]
  },

Then, declare the order-config#header block and its children blocks: order-config.title and order-config.modal. Example:

{
  "order-config#header": {
    "children": [
      "order-config.title#header",
      "order-config.modal#header"
    ],
    "props": {
      "blockClass": "header",
      "formFields": [
        {
          "name": "orderType",
          "type": "string",
          "fieldType": "radio",
          "label": "Order Type",
          "defaultValue": "resale",
          "options": [
            {
              "label": "Resale",
              "value": "resale"
            },
            {
              "label": "Consumption",
              "value": "consumption"
            }
          ]
        },
        {
          "name": "state",
          "type": "string",
          "fieldType": "select",
          "label": "State",
          "showInTitle": true,
          "options": [
            {
              "label": "ES",
              "value": "ES"
            },
            {
              "label": "SP",
              "value": "SP"
            }
          ]
        }
      ]
    }
  },
  "order-config.modal#header": {
    "children": [
      "order-config.form"
    ]
  },
  "order-config.title#header": {
    "props": {
      "formTitle": "Order Configuration for Header"
    }
  },
}

If the order-config.form block does not have any children configured, a default form will be rendered automatically based on the React Hook Form JSON Schema library. To declare children blocks according to your business needs, check out the Advanced configuration section below.

Step 3: Create main schema in Master Data

You must create a schema named main in Master Data, using the order_configuration data entity.

You can place a request using the Save schema by name endpoint of the Master Data API - v2 to do so.

The schema should contain all the data that you added in the form above, otherwise the data will not be persisted.

Request body example

{
    "v-cache": false,
    "properties": {
        "clientId": {
            "type": "string"
        },
        "orderType": {
            "type": "string"
        },
        "state": {
            "type": "string"
        }
    },
    "v-default-fields": [
        "clientId",
        "orderType",
        "state"
    ],
    "v-indexed": [
        "clientId",
        "orderType",
        "state"
    ]
}

Refer to Master Data API - v2 documentation for more details.

Step 4: Update orderForm configuration

It is also necessary to configure a new app in the orderForm.

First, place a GET Get orderForm configuration request to retrieve the current orderForm settings before updating them. By doing so you ensure that you will only change the properties you want in the next step.

Then, place a POST Update orderForm configuration request, setting the following object inside the apps object in the request body:

        {
            "fields": [
                "values"
            ],
            "id": "orderconfig",
            "major": 1
        }

Request body example

{
    "paymentConfiguration": {
        "requiresAuthenticationForPreAuthorizedPaymentOption": false,
        "allowInstallmentsMerge": null,
        "blockPaymentSession": null,
        "paymentSystemToCheckFirstInstallment": null,
        "defaultPaymentSystemToApplyOnUserOrderForm": null
    },
    "taxConfiguration": null,
    "minimumQuantityAccumulatedForItems": 1,
    "decimalDigitsPrecision": 2,
    "minimumValueAccumulated": null,
    "apps": [
        {
            "fields": [
                "quoteId"
            ],
            "id": "b2b-quotes-graphql",
            "major": 1
        },
        {
            "fields": [
                "values"
            ],
            "id": "orderconfig",
            "major": 1
        }
    ],
    "allowMultipleDeliveries": true,
    "allowManualPrice": true,
    "maxNumberOfWhiteLabelSellers": null,
    "maskFirstPurchaseData": null,
    "recaptchaValidation": "vtexcriteria",
    "maskStateOnAddress": true
}

You can refer to Checkout API documentation for more information.

Advanced configuration

If desired, you can declare the order-config.form block by adding and configuring the formFields prop and an array of form children blocks (whose descriptions you can find below).

{
  "order-config#static-page": {
    "props": {
      "formFields": [
        {
          "name": "orderType",
          "type": "string",
          "fieldType": "select",
          "label": "Order Type",
          "defaultValue": "res",
          "showInTitle": true,
          "options": [
            {
              "label": "Resale",
              "value": "res"
            },
            {
              "label": "Consumption",
              "value": "cons"
            }
          ]
        },
        {
          "name": "state",
          "type": "string",
          "fieldType": "select",
          "label": "State",
          "showInTitle": true,
          "required": true,
          "options": [
            {
              "label": "ES",
              "value": "ES"
            },
            {
              "label": "SP",
              "value": "SP"
            }
          ]
        },
        {
          "name": "someTextInput",
          "label": "Some Text Input",
          "fieldType": "input",
          "type": "string",
          "required": true,
          "showInTitle": true
        }
      ]
    },
    "children": [
      "order-config.title#static-page",
      "order-config.form#static-page"
    ]
  },
  "order-config.form#static-page": {
    "children": [
      "flex-layout.row#state-and-payment-method",
      "order-config.text#some-text-input",
      "order-config.submit"
    ]
  },
  "flex-layout.row#state-and-payment-method": {
    "children": [
      "order-config.dropdown#state",
      "order-config.radiogroup#payment-method"
    ],
    "props": {
      "blockClass": "stateAndPaymentMethod"
    }
  },
  "order-config.dropdown#state": {
    "props": {
      "pointer": "#/properties/state"
    }
  },
  "order-config.radiogroup#payment-method": {
    "props": {
      "pointer": "#/properties/paymentMethod"
    }
  },
  "order-config.text#some-text-input": {
    "props": {
      "pointer": "#/properties/someTextInput"
    }
  },
  "order-config.title#static-page": {
    "props": {
      "formTitle": "Order Configuration for Static Page"
    }
  }
}
Block nameDescription
order-config.submitRenders a Submit button.
order-config.dropdownRenders the a dropdown field.
order-config.radiogroupRenders a radiogroup field.
order-config.textRenders a text field.
order-config.textareaRenders a text field with a wider range of available characters.
order-config.checkboxRenders a checkbox field.

Props

Check out the description of the available props below.

Prop nameTypeDescriptionDefault ValueBlock name
pointerstringPath to which the block must point in the formFields prop in order to properly work.undefinedorder-config.dropdown, order-config.radiogroup, order-config.text, order-config.textarea, and order-config.checkbox
formFieldsobjectObject responsible for defining the form fields.undefinedorder-config.form

The formFields object contains the following props:

Prop nameTypeDescriptionDefault Value
namestringName of the field (only used as an identifier in your code).undefined
typeenumValue type accepted by the field. Possible values are string and number.string
fieldTypeenumInput type accepted by the field. Possible values are: text, textarea, select, radio, and checkbox.text
labelstringField name shown to users.undefined
showInTitlebooleanWhether to display the value type accepted by the field on its name (true) or not (false).false
optionsobjectField options to be defined in case select, radio, or checkbox values were declared in the fieldType prop.undefined

The options object contains the following props:

Prop nameTypeDescriptionDefault Value
labelstringOption name shown to users.undefined
valuestringOption value.undefined

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles
formSubmitButton
formSubmitContainer
formErrorServer
formErrorUserInput
loader
orderConfigFormWrapper
formObject
title
titleValues
titleWrapper
wrapper

Contributors ✨

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!


Did this page help you?