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.

Order Fields

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.

Order line fields

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