Custom Fields

Dynamicweb Ecommerce comes with a set of standard fields for both products and product groups – fields such as Name, Price, Manufacturer, Description, etc. These are fields which are typically used across most industries. When the standard fields are not enough – e.g. when you need to store industry-specific information – you can create custom fields for storing that information.

The following custom field types are related to the product catalog:

  • Product group fields are used to extend product groups with custom fields
  • Product Fields are used to extend all products on a solution. They should be used for properties with global relevance, e.g. to store an external id from an ERP system.
  • Product Categories are sets of fields related to a certain category of product, e.g. apparel or wrenches. They are applied to product groups, and extend only products in that group and (optionally) subgroups

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

Product group fields are a type of custom fields, which becomes available on all product groups (Figure 2.1).

Figure 2.1 Product group fields are available on all product grops on a solution

To create a product group field:

  • Go to Settings > Ecommerce > Product catalog > Product group fields
  • Click New field in the toolbar to open the edit view (Figure 2.2)
Figure 2.2 Creating a new product group field

From here, you must:

  • Specify a name and a 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. Read more about template tags for product groups below.
  • Select a field type for the field
  • Enter a description - a helptext which will be shown next to the field when editing a group
  • Decide if the field requires validation or not (i.e. if it is required or not)

Product fields are a type of custom field which are added to all products - they are added to a special section on the product details view (Figure 3.1).

Figure 3.1 Product fields are added to all products on a solution, and serve many purposes

To create a custom product field:

  • Go to Settings > Ecommerce > Product catalog > Product fields
  • Click New field in the toolbar to open the Product field view (Figure 3.2)
Figure 3.2 The edit product field view

Fill in the values:

  • Specify a name and a system name for the field
  • Provide a template tag-value for the field - use this tag in your templates to render the field content in frontend
  • Select a field type (see below)
  • Enter a description -  a helptext which is shown next to the product field when editing a product
  • If this is an administrative field which should not be shown in frontend, check the Do not render checkbox

The Field settings section is used to quickly configure the fields settings for this custom field. Fields settings control whether the field is obligatory or not, if it is allowed to differ across variants and languages, and so on.

The Field Display Groups section allows you to add the field to or remove it from field display groups.

Product Categories are a way for you to create collections of custom fields – product category fields – which can be used to e.g. extend a subset of products, either via inheritance (categories) or by being explicitly added to each product (properties).

Three different types of product categories can be created:

  • Category field collections are used to extend all products in a product group with custom fields.
  • Property field collections are used as containers for fields which are added ad-hoc to products via PIM.
  • Reference field collections are used as containers for fields which are used in multiple other product categories – like color or width.

These different field collection types are described in more detail later in this article.

To create a product category:

  1. Go to Settings > Ecommerce > Product Catalog > Product categories
  2. Click New in the toolbar to open the edit product category view (Figure 4.1)
  3. Provide a Name
  4. Select a field type for the category:
    1. Category
    2. Property
    3. Reference
  5. Save
Figure 4.1 A product category

Once the category has been saved, you must add at least one category field to it. To create a product category field click Add new field and fill in the field settings (Figure 4.2).

Here you must:

  • Name the category
  • Add a number of product category fields with a name and a field type
  • (Optional) provide a description
  • (Optional) set the field to Hide if empty and/or Do not render

The Do not render checkbox makes it possible to mark a field as an administrative field only – when it is checked, this field will be left out of the loops which render product category fields in frontend.

Figure 4.2 A product category field

The Settings section defines basic properties:

  • Enter a Name, a system name, and a template tag
  • Select a field type
  • (Optional) Provide a description
  • Check Hide if empty to hide this field on products where it does not have a value – this effectively makes it into a product property
  • Check Do not render to mark this as an administrative field which is left out of loops in frontend

The Field section specifies what type of field this is:

  • An ordinary field
  • A reference to another field.

If you select Reference here the dropdown allows you to choose between all fields located in so-called Reference field collections, which are described in more detail later in this article. When a reference field is selected all basic settings are retrieved from that field.

The Field settings section allows you to quickly configure the fields settings for this field.

Fields in a product category can be sorted via drag and drop.

A category field collection is used to add a set of custom fields to a subset of products – e.g. bikes or shirts. Once created, this type of product category is attached to a product group, extending all the products inside the group with the fields in the product category.

For example, if you sell two types of products in your shop – bikes and shirts – you could create two product categories:

  • Bikes – containing fields such as frame material, color, gears, breaks, etc.
  • Shirts – containing fields such as washing instructions, color, fabric, pattern, etc.

This type of collection is therefore ideal for scenarios where products are placed in a category-based group structure, and where the set of secondary properties are well-defined from the beginning.

After a product category has been created it can be attached to a product group via the product group settings (Figure 5.1).

Figure 5.1 Using a product category collection

To do so:

  • Right-click a product group and select edit group in the context menu
  • Use the product category dropdown to select the category
  • Click OK
  • Save

This causes two things to happen:

  • All products in this group now have the product category fields available
  • The product group now has a section for setting default values for the fields (Figure 5.2)
Figure 5.2 Default product category field values

Default values set here may be overridden or restored when editing a product.

A property field collection is used as a container for product properties; fields which are available on all products in PIM and Ecommerce but not shown unless it has a value or has been explicitly added. Product property fields will show in Ecommerce but can only be added via PIM or an integration setup.

Once a property field collection has been created, the field can be added manually from Dynamicweb PIM.

Product properties are ideal for scenarios where secondary product data is non-hierarchal and/or disorganized. Please be aware that using product properties may lead to performance issues – in many cases it is advised to explore alternatives, e.g. regular product category fields.

A reference field collection is used as a container for reference fields – fields which may be referenced by fields in category field collections or property field collections (Figure 7.1).

Figure 7.1 A reference field collection

When indexed, a reference field contains all the values from the fields which reference it – this makes it possible to create a single facet and use it to filter products belonging to several product categories, e.g. a Color field which is used across three separate product category fields.

Ordinary category fields can be converted to reference fields using the Convert to reference field button in the toolbar, but the process cannot be reversed.

Reference field collections are ideal in scenarios where the same field needs to exist across several product categories, or as data destinations on integrated solutions where end users create new product categories from a central collection of reference fields on the fly. Reference fields cannot themselves refer to other reference fields.

To see where a reference field is referenced click the Show usage button.

Dynamicweb is born with a set of standard field types for creating custom fields – they are:

Field type

Function

Text (5-255)

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

Editor

Inserts a WYSIWYG editor where you write a text using various text editing tools.

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

List box

Inserts a list of options that can be selected/deselected. List type & options must be defined.

For more advanced scenatios, you can also create custom field types. They allow you to attach a provider to the field type and define a unit of weightlength, or volume for each Ecommerce language.

This makes it possible to automatically convert from e.g. feet to meters or gallons to litres (Figure 8.1).

Figure 8.1 A custom field type used to convert from inches to mm

Conversions are based on the value entered in the default Ecommerce language, and the Fields settings must be configured so values entered in this field is not allowed to be specified separately for each language.

To create a customfield type go to Settings > Ecommerce > Product Catalog > Field types and click New in the toolbar to open the edit field type interface (Figure 8.2).

Figure 8.2 Defining a custom field type

Configure the field type:

  • Enter a name and a system name
  • Select a Type of field – current options are:
    • Length
    • Volume
    • Weight
  • Configure the provider parameters:
    • Specify the number of decimals to use
    • Select a unit to use for each Ecommerce language on the solution

Once created, the custom field type is available for selection when you create custom product fields and product category fields.

Database

These are the database tables associated with Products and related features in Dynamicweb.

These are the tables associated with Product Categories:

EcomProductCategory

Contains Ecom product categories as defined in Settings -> Ecom -> Product catalog -> Product categories.

Field name Data type Length
CategoryId nvarchar 50
CategoryAutoId int 4
CategoryProductProperties bit 1
CategoryType int 4

EcomProductCategoryTranslation

Contains translated data for a product category (CategoryTranslationCategoryId) in different languages (CategoryTranslationLanguageId).

Field name Data type Length
CategoryTranslationCategoryId nvarchar 50
CategoryTranslationLanguageId nvarchar 50
CategoryTranslationCategoryName nvarchar 255
CategoryTranslationAutoId int 4

EcomProductCategoryField

Contains individual field definitions for product categories (FieldCategoryId).

Field name Data type Length
FieldId nvarchar 255
FieldCategoryId nvarchar 50
FieldTemplateTag nvarchar 255
FieldType int 4
FieldDefaultValue nvarchar Max
FieldPresentationType nvarchar 50
FieldSortOrder int 4
FieldAutoId int 4
FieldDoNotRender bit 1
FieldHideEmpty bit 1
FieldForeignCategoryId nvarchar 50

EcomProductCategoryFieldTranslation

Contains translated field definitions (FieldTranslationFieldId) for categories (FieldTranslationFieldCategoryId) in different languages (FieldTranslationLanguageId).

Field name Data type Length
FieldTranslationFieldId nvarchar 255
FieldTranslationFieldCategoryId nvarchar 50
FieldTranslationLanguageId nvarchar 50
FieldTranslationFieldLabel nvarchar 255
FieldTranslationFieldOptions nvarchar Max
FieldTranslationAutoId int 4
FieldTranslationDescription nvarchar Max

EcomProductCategoryFieldGroupValue

Contains category field (FieldValueFieldID) values set on product groups (FieldValueGroupId, FieldValueGroupLanguageId).

Field name Data type Length
FieldValueFieldId nvarchar 255
FieldValueFieldCategoryId nvarchar 50
FieldValueGroupId nvarchar 255
FieldValueGroupLanguageId nvarchar 50
FieldValueValue nvarchar Max

EcomProductCategoryFieldValue

Contains category field (FieldValueFieldID) values set on products (FieldValueProductID, FieldValueProductVariantID, FieldValueProductLanguageID).

Field name Data type Length
FieldValueFieldId nvarchar 255
FieldValueFieldCategoryId nvarchar 50
FieldValueProductId nvarchar 30
FieldValueProductVariantId nvarchar 255
FieldValueProductLanguageId nvarchar 50
FieldValueValue nvarchar Max
FieldValueAutoId int 4
FieldValueSortOrder int 4

These are the database tables related to custom product fields:

EcomProductField

Contains product field definitions from Settings -> Ecom -> Product catalog -> Product Fields.

Field name Data type Length
ProductFieldId nvarchar 255
ProductFieldName nvarchar 255
ProductFieldSystemName nvarchar 255
ProductFieldTemplateName nvarchar 255
ProductFieldTypeId int 4
ProductFieldTypeName nvarchar 255
ProductFieldLocked bit 1
ProductFieldSort int 4
ProductFieldListPresentationType int 4
ProductFieldAutoId int 4
ProductFieldDoNotRender bit 1

EcomProductFieldTranslation

Contains translations of product fields (ProductFieldTranslationFieldID) to various languages (ProductFieldTranslationLanguageID).

Field name Data type Length
ProductFieldTranslationID int 4
ProductFieldTranslationFieldID nvarchar 255
ProductFieldTranslationLanguageID nvarchar 50
ProductFieldTranslationName nvarchar 255
ProductFieldTranslationDescription nvarchar Max

EcomFieldOption

Contains option values for product fields (EcomProductField) of type list. Linked on FieldsOptionFieldID.

Field name Data type Length
FieldOptionId nvarchar 255
FieldOptionFieldId nvarchar 255
FieldOptionName nvarchar 255
FieldOptionValue nvarchar 255
FieldOptionIsDefault bit 1
FieldOptionSort int 4
FieldOptionAutoId int 4

EcomFieldOptionTranslation

Contains translation data for Ecom field options (EcomFieldOption). Links field options (EcomFieldOptionTranslationOptionID) to language (EcomFieldOptionTranslationLanguageID).

Field name Data type Length
EcomFieldOptionTranslationID int 4
EcomFieldOptionTranslationOptionID nvarchar 255
EcomFieldOptionTranslationLanguageID nvarchar 50
EcomFieldOptionTranslationName nvarchar 255