Track Order Form Widget

The Track Order Form widget adds a small form to your page, such as a "Track your order" or help page. Customers enter their email address and order number and click Track Order, and the widget looks up the order and shows its delivery progress as a series of steps.

It works like the Track Order widget, but the customer types in their order details, so you don't need to output them on the page. Use it on pages where you don't already know which order the customer is looking for.

Prerequisites

• Your DigitalGenius widget ID.
• Your region: eu or us.
• A DigitalGenius flow that handles track order requests. The widget sends a track_order event with the values the customer entered, and the flow must reply with the order's tracking status. This is the same event the Track Order widget sends, so the same flow works for both.
• Access to edit the HTML of the page the widget is displayed on.

Installation

Add the following code to your page, at the position where the widget should appear. Replace your-widget-id with your widget ID, and update env to match your region if required.

<div id="track-order-form"></div>

<script>
  window.DG_SDK_CONFIG = {
    widgetId: 'your-widget-id',
    env: 'eu',
    widget: {
      targetDOMNode: '#track-order-form',
      type: 'trackOrderForm',
    },
  };
</script>
<script src="https://chat.digitalgenius.com/init-sdk.js"></script>

The widget is rendered inside the <div id="track-order-form"></div> container. By default it shows an Email field, an Order number field and a Track Order button.

Configuration

The following properties are set within the widget object.

Form fields

fields sets which fields the customer fills in. Each field has:

If fields is omitted, the following fields are used:

These match the values the Track Order widget sends, so your flow receives email and order_number in either case.

Example: changing the labels

To use your own wording and add placeholders, list both fields with the default names:

config: {
  fields: [
    {
      name: 'email',
      label: 'Email address',
      type: 'email',
      placeholder: '[email protected]',
    },
    {
      name: 'order_number',
      label: 'Order reference',
      placeholder: 'HB-614357',
    },
  ],
},

Example: different fields

If your flow looks orders up with other details, such as an order number and postcode, list those fields instead. Each value is sent with the field's name, so make sure your flow reads the same keys:

config: {
  fields: [
    { name: 'order_number', label: 'Order number' },
    { name: 'postcode', label: 'Postcode' },
  ],
},

Layout

The form fields sit side by side when there's room, and stack when there isn't, so the form fits wherever you put it.

The delivery progress can be displayed in two layouts:

• horizontal (default): the steps are displayed side by side, joined by a line. This suits the main content area of a page.
• vertical: the steps are stacked, with each step's marker on the left and its label on the right, joined by a line. This suits narrow spaces, such as a sidebar, where the steps would not fit side by side.

Both layouts show the same information: a marker and label for each step.

config: {
  layout: 'vertical',
},

Order statuses

orderStatuses defines the steps in the delivery progress. Each step has:

• status: the tracking status returned by your flow, for example In Transit. Matching ignores case and surrounding spaces.
• label: the text shown to the customer for that step.

Steps before the order's current status are shown as complete, the current status is highlighted, and later steps are shown as upcoming.

If orderStatuses is omitted, the following steps are used:

For example, to add an extra step and use your own wording:

orderStatuses: [
  { status: 'Order Placed', label: 'Order placed' },
  { status: 'Ready for Shipment', label: 'Order processing' },
  { status: 'Ready for Pickup', label: 'Awaiting pick-up' },
  { status: 'In Transit', label: 'Shipped' },
  { status: 'Delivered', label: 'Delivered' },
],

If the flow returns a status that isn't in orderStatuses, no step is highlighted and an error is logged to the browser console.

Behaviour

• Clicking the button: the browser checks that required fields are filled in and email addresses are valid. If not, it shows a message next to the field and the form isn't sent.
• Sending the form: the form is replaced by a loading indicator and loadingText while the order is looked up. Spaces around each value are removed before it's sent.
• Tracking found: the delivery progress is shown in place of the loading indicator.
• Tracking not found: if sending the request fails, or no response is received within 30 seconds, the form is shown again with errorText below it. The values the customer entered are kept, so they can correct them and try again.

Styling

The widget renders inside a shadow DOM, so the styles on your page don't affect it directly. By default it inherits your page's font and text colour, and uses a transparent background. Sizes are set in em, so the widget scales with your font size.

To change the colours, use config.style:

config: {
  style: {
    accentColor: '#1f9d55',
    inactiveColor: '#d4d4d4',
  },
},

To limit the widget's width, set --dg-max-width on the container:

#track-order-form {
  --dg-max-width: 32rem;
}

For further changes, the form's elements can be styled from your page with the ::part() selector, using the parts form, field, label, input, button and error:

#track-order-form::part(input) {
  border-radius: 0;
}

Troubleshooting

If the widget does not appear, check that:

• The <div id="track-order-form"></div> container is on the page and placed before the scripts.
• targetDOMNode matches the container, including the # prefix.
• type is set to 'trackOrderForm'.
• widgetId is correct and env matches your region.

If a field is missing, check the browser console. An error is logged for any field without a name, or with the name name.

If the error message is shown after sending the form, check that your flow handles the track_order event and reads the same keys as the fields' names.