Custom fields

Dynamicweb Ecommerce comes with a set of standard order and order line fields – fields such as OrderId, Price, Completion date, Comment, etc. When the standard fields are not enough – e.g. if you need to store industry-specific information – you can create custom fields for storing that information.

The following custom field types exist for orders:

  • Order fields are used to add information to the whole order
  • Order line fields are used to add information to a single order line

Other parts of the system also have custom fields available - see the relevant sections for more information.

System Names & IDs

Please note that we recommend that you use only aphanumeric characters in system names and ids - that is, [A-Z], [a-z] and [0-9]. In list options we aso recommend that you avoid certain characters - like [,], [|], [<], [>], [@], [#], [&], [?], [\], [/], ['], [*], [~], and ["] - as these may be interpreted erroneously by either the system or a browser.

With custom order fields, you can create input fields to be filled by customers during checkout, for example:

  • An input field for entering coupon or promotional codes
  • A checkbox for requesting an additional service (e.g. a product catalog) with the order (Figure 2.1)
  • A text field, for entering order comments

And so on – if you can dream it, you can do it! Provided that you dream about creating custom order fields, of course.

Here’s how to make that dream come true.

Figure 2.1 An example of a custom order field

Custom order field are created by going to Settings > Ecommerce > Orders > Order fields and clicking New in the toolbar to open the order field defintion (Figure 3.1).

Figure 3.1 Creating a custom order field

From here you must:

  • Specify a name and a unique system name for the field
  • Provide a template tag-value for the field. Use this value in your templates to render the field content on the frontend
  • Select a field type for the field (see table below)

The field types available to you are:

Field type

Function

Text (5-255)

Standard text field where you can type between 5 and 255 characters

Long text

Inserts a text box where you can type several thousand characters.

Checkbox

Inserts a checkbox

Date

Inserts a drop down where a date can be selected

Date/time

Inserts a drop down where a date and time can be selected

Integer

Inserts a field where integers can be entered

Decimal number

Inserts a field where decimal numbers can be entered

Link

Inserts a field where you can enter a link to another web page or a file in your File Manager

File Manager

Inserts a field where you can select a file from your File Manager

Once you have created one or more order fields, you can add them to your shopping cart by modifying the templates used during the checkout process.

Read more about the checkout process in the Shopping Cart documentation, and about the CustomOrderFields template tags in the template tag documentation.

When a product is added to a cart, it is created as an order line.

Order line fields are used to allow customers to provide more information about an order before checkout.

For instance, shops which sell goods by certain measurements – e.g. cables or fabric – may find it useful to allow the customer to specify how many meters or inches of a product they wish to order, either on the product details page (Figure 4.1).

Figure 4.1 A custom order line field on a product details page

Or in the shopping cart (Figure 4.2).

Figure 4.2 A custom order line field in the shopping cart

To use order line fields you must:

  • Create order line fields in the backend
  • Configure one or more product groups to use the fields
  • Change your templates to render the fields in the frontend

To create an order line field go to Settings > Ecommerce > Orders > Order line fields and click New in the toolbar to open the order line field definitions (Figure 5.1)

Figure 5.1 Creating an order line field

From here you must:

  • Provide a name and a system name for the field
  • Specify a field length in characters

To use an order line field you must attach it to a product group - read more in the product groups documentation.

Rendering order line fields in frontend

Order line fields can be rendered both on the product details page and in the shopping cart. This allows customers to enter the field values both before adding the product to the cart and when the product is in the cart.

  • To render order line fields from the product details template, use the Product.OrderLineFields loop. This is optional (but recommended).
  • To render order line fields from the shopping cart template, use the Order.OrderLineFields loop. This is required.

If the same product with the same order line data is added to the cart twice the two product instances are stacked as one product, unless they are parts lists (which are always show as separate products).

If two instances of the same product with different order line data are added to the cart, they are listed as two separate products.

database

These are the database tables associated with custom order fields:

EcomOrderField

Contains order field definitions from Settings -> Ecom -> Orders -> Order fields.

Field name Data type Length
OrderFieldId nvarchar 255
OrderFieldName nvarchar 255
OrderFieldSystemName nvarchar 255
OrderFieldTemplateName nvarchar 255
OrderFieldTypeId int 4
OrderFieldTypeName nvarchar 255
OrderFieldLocked bit 1
OrderFieldSort int 4
OrderFieldAutoId int 4

EcomOrderLineFields

Contains order line field definitions from Settings -> Ecom -> Orders -> Order line fields.

Field name Data type Length
OrderLineFieldSystemName nvarchar 255
OrderLineFieldName nvarchar 255
OrderLineFieldLength int 4
OrderLineFieldAutoId int 4
EcomOrderLineFieldsSorting int 4

EcomOrderLineFieldGroupRelation

Contains information about which orderline fields are associated to products in a specific group.

Field name Data type Length
OrderLineFieldGroupRelationSystemName nvarchar 255
OrderLineFieldGroupRelationGroupId nvarchar 255
OrderLineFieldGroupRelationAutoId int 4
OrderLineFieldGroupRelationShopID nvarchar 255