Shopping Cart

The Shopping Cart app is the main entry point for the ordering process. By adding the Shopping Cart app to a paragraph on a page, customers will be able to:

  • Add products to the cart
  • Complete the checkout process defined on the cart – typically providing shipping details, selecting a payment provider and a shipping provider, and completing the order
  • Receive order confirmation on site and by email

In short, the Shopping Cart app is absolutely essential to an Ecommerce solution!

Implementers will be happy to learn that the Shopping Cart is very easy to interact with, with numerous tags and loops available for adding, removing and displaying products located in a shopping cart.

Once a Shopping Cart app has added to a paragraph, you have access to all the app settings (Figure 2.1) and configuration options which control the app behavior.

Figure 2.1 Shopping cart moduile settings

With the basic settings you can:

  • Select a shop to which this shopping cart belongs
  • Optionally select an order context if this is a context cart (read more below)
  • Check the Checkout to quote box if this is a quotes cart

If you don’t select a shop explicitly, the orders created will go to the shop set as the default shop in your settings. Please note that we recommend that you always explicitly select a shop.

The Order steps settings (Figure 3.1) let you to configure existing or add new order steps to your checkout process.

Figure 3.1 The order steps area

Read more about creating and customizing order steps below.

With the notification emails settings (Figure 4.1) you can set up email notifications for customers, site admins, etc.

Figure 4.1 You can configure notification emails for e.g. customers or admins with these settings

To set up a  notification email click Add notification to open the email notification window (Figure 4.2).

Figure 4.2 The email notification setup window

From this window, you can:

  • Specify a recipient email or you can check the For Customer Email Address checkbox or the For Delivery Email Address to use one or both of the the emails provided by the user
  • Select, edit or create an email-template to use
  • Specify a sender name and sender email and an encoding to use
  • Select an attachment (e.g. a Terms and Conditions pdf) to send with each notification email

Please note, that in order to use email notifications, you must have an email server configured on your solution.

Tip: You can use {OrderID} in the subject to insert the order number in the confirmation email.

The field validation settings (Figure 6.1) allow you to select which validation rules should be applied to the order on checkout.

Figure 6.1 The field validation settings

You can:

  • Force the customer to accept your terms and conditions
  • Check for stock status, so you won’t end up selling more than you can deliver. You can use the placeholder {ProductName} in your error message to render the actual product name of the product which causes the validation to fail.
  • Select and add custom validation groups – you can read more about creating custom validation groups in the implementing section of this document.

When a custom validation group is selected and added to the Shopping Cart, you can specify a localized error message to display when a field is invalid (Figure 6.2). This means that you don’t need to have language-specific validation groups created.

On stock level validation and product reservation

If you use stock level validation on the cart, consider using product reservation as well. With product reservation, a product added to the cart becomes unavailable to other customers for an amount of time.

Read more in this article on the advanced configuration settings regarding product reservation.

The newsletter setting (Figure 7.1) allows you to ask users for permission to send them emails.

Figure 7.1 The newsletter settings

If checked, the section of the order step Information-template starting with <!--@If Defined(Ecom:Cart.UseNewsletterSubscription)--> (or corresponding razor code) will be rendered during checkout. 

“Would you like to subscribe to our newsletter?”

It may be a good idea to change the wording of the text being rendered – for legacy reasons (newsletter v3 integration) it ask users if they want to subscribe to a newsletter, but actually it simply sets the email permission for the user to true, and therefore lets you send all kinds of emails to them, not just newsletters.

The Empty cart settings (Figure 8.1) control what a user will see when they view an empty cart.

Figure 8.1 The empty cart settings

You have three options:

  • Redirect to an internal page lets you select a specific page on your website to redirect users to
  • Show template allows you to select a custom template to show instead of the cart. You can then add cool stuff to the template, of course, like suggested or personalized products and news.
  • Take no special action does exactly what it says, and simply displays the first step of the order process as with a full cart. However, you can use the Ecom:Order.IsEmpty tag to test for and do stuff if a cart is empty.

The User management settings (Figure 9.1) allows you to control how the cart interacts with user management.

Figure 9.1 The user management settings

You can:

  • Enable or disable auto-filling order fields with the user details of a logged in user
  • Allow new users to create a new user during checkout – and specify which user group these new users should belong to, and which error messages should be displayed during the user creation process if something goes wrong'
  • Activate updating existing users  with the information based on a matching email

To setup creating a user during checkout, select the InformationCreateUser.html template as step 2 in your order steps section – or create or modify a custom template to suit your purposes and use that.

Note that If a user is logged in to extranet on two separate computers, the shopping cart content will be automatically synchronized.

Saving an address to user management

Dynamicweb supports saving an address on a logged in user on checkout. Look at the InformationSaveCart.hmtl template for example code.

The address will be saved to the addresses section of the user, if it doesn’t match an existing address.

If your solution has multiple shops attached, you will have access to the payment & delivery settings (Figure 10.1).

Figure 10.1 The payment and delivery settings

With these settings, you can specify which payment and delivery providers you want available for this particular cart.

This is useful if, for instance, you don’t want to list Danish payment providers on your American website.

To make a delivery or payment method available on a particular cart, move it from the list of available methods (left column) to the list of selected methods (right column).

The behavior settings (Figure 11.1) control cart behavior in a variety of situations, as outlined below.

Figure 11.1 The behavior settings

You can control:

  • If the cart should show the first order step or show the last visited step for users returning to the cart after leaving the order flow.
  • How the cart selects which shipping and payment methods should be available – the options being customer country, delivery country, or delivery country if a delivery address has been selected.
    • Prices in the shopping cart are recalculated when the billing or delivery country is changed. VAT is recalculated when a new bulling country is set, and Taxes are recalculated when a new delivery country is set.
  • If products which have become unavailable should be removed or ignored
  • If you want to use an image pattern from a product catalog in the cart

Dynamicweb Ecommerce uses a special query string parameter – cartcmd – when adding, removing, or otherwise modifying a product in a cart.

You can use cartcmd in either a direct link or when submitting a form, with one of the following values:

Query string value

Description

Example

add*

Adds the requested product to the cart

Url example:
cartcmd=add&productid=PROD25&Quantity=1

Add multiple products to the cart at the same time

Use the ProductLoopCounter to add a long list of orderlines,

Example using form.submit (here, just a single product):
CartCmd=addMulti
&ProductLoopCounter1=1
&ProductID1=T16@@SHOP3
&VariantID1=
&UnitID1=
&Quantity1=2

emptycart

Empties the cart.

You can link to a specific page after emptying the cart:

<a href="Default.aspx?ID=123&cartcmd=emptycart">

This empties the cart, then shows the requested page.

converttoorder

Converts a cart to an order (without going through payment/checkout).

Useful for integration purposes, if payment is handled outside Dynamicweb Ecommerce

updateorderlines

Updates the quantity of several orderliness, using the parameter QuantityOrderLineOL[ID]=quantity

 

?cartcmd=updateorderlines
&QuantityOrderLineOL1=20

incorderline

Increases the quantity of an item in the cart

 

decorderline

Decreases the quantity of an item in the cart. When the quantity reaches zero, the item is removed from the cart.

 

delorderline

Removes an item from the cart

 

orderline

Used with values “key” and “quantity” to update the quantity on an orderline directly from the OrderLineID.

?CartCmd=orderline
&key=OL28
&quantity=4

addwithpoints

Adds a single item to the cart with loyalty points.

 
loadorder Loads an abandoned cart based on an order secret which must be send along with the command. "/Default.aspx?CartCmd=loadorder&LoadingOrderId=" + @GetString("Ecom:Order.ID") + "&LoadingOrderSecret=" + @GetString("Ecom:Order.LoadingOrderSecret")
* In context of BOM product

cartcmd=add&productid=PROD25&Quantity=1
&PROD26Quantity=2
&PROD27Quantity=3

will add 1 of PROD25, 2 of PROD26 and 3 of PROD27.

So the syntax of multiple is [ProductId][Quantity]

For examples on how to use cart commands, please see below - or check out the standard Ecommerce templates.

All cart commands support using redirect=false to prevent redirects when adding to cart using e.g. Ajax.

 

There are three ways you can create a simple add-to-cart button:

  • Create a form using the Ecom:Product.Form.Clean tag, which outputs a set of hidden-fields (Figure 2.1) containing the information needed when adding a product to the cart
  • Create a form and supply the information manually – at the minimum the ProductID, VariantID, UnitID, cartcmd=add, and optionally the PageID you want to redirect users to after adding the product to the cart
  • Create an <a href> link with the relevant parameters - at the minimum cartcmd=add, productID, and often PageID (optional)
Figure 2.1 Using the Ecom:Product.Form.Clean tag to output hidden-fields for an add-to-cart button

With the cart command addmulti you can let your customers add more than one product to the shopping cart with a single click.

All you have to do is change the product list template:

  • Insert a form tag around the entire products loop
  • Add a hidden field which act as cart command for the addMulti function;
     <input type="hidden" name="CartCmd" id="CartCmd" value="addMulti" />
  • Insert a form field handler tag inside the product loop:
  •  
  • Insert an quantity input field and change the default name to "Quantity<!--@Ecom:Product.LoopCounter-->

Example:

<form name="multiForm" id="multiForm" method="post"> <input type="hidden" name="CartCmd" id="CartCmd" value="addMulti" /> <!--@LoopStart(Products)--> <!--@Ecom:Product.Form.Multi.HiddenFields--> <!--@Ecom:Product.Number--> - <!--@Ecom:Product.Name--> <!--@Ecom:Product.Price.Price--><br /> <input type="text" name="Quantity<!--@Ecom:Product.LoopCounter-->" value="1" /> <!--@LoopEnd(Products)--> </form>

To finish things off then simply let users submit the form when adding products to the shopping cart.

The shopping cart app is born with a set of order steps – Show cart, Information, Checkout and Receipt – which together constitute the standard checkout process (Figure 4.1).

Figure 4.1 Customizing the checkout process

Think of the order steps as a virtual breakdown of the information that a user needs to supply and receive during the process of creating an order.

Each step handles a different kind of exchange of information.

You can, of course, customize the checkout process to suit your needs – by customizing, removing or introducing steps as needed – the only required step is the checkout step.

So, if you want to, you can have all your data on a single page, or you can break it down as you want.

You can add, edit, or remove steps by clicking the appropriate icons next to the order step to open the edit step window (Figure 4.2) – an order step simply consists of a name and a template.

Figure 4.2 Editing an order step

Dynamicweb ships with a number of templates showcasing how to use the different Ecommerce functionalities.

For a detailed overview of the tags and loops available for the shopping cart app, see the template tag reference.

There’s a saying in software: Never trust user input.

For an open system like an Ecommerce website, this is even more important – and that’s why we have data validation on the shopping cart. This is not only useful for stopping malicious users from submitting bad data, it’s also a helping hand to users who make mistakes. All it takes is a comma instead of a dot in an email address, and suddenly you have missing order confirmations, tracking codes, and so forth.

Here’s how to validate user data on the Shopping Cart.

To force users to enter valid data, Dynamicweb Ecommerce ships with a feature called Validation groups.

A validation group contains a number of validation fields, which define rules that are applied to a field in the checkout flow.

To create a validation group:

  • Go to Settings > Ecommerce > Orders > Validation groups
  • Click New in the toolbar

This opens the Edit view (Figure 6.1).

Figure 6.1 Creating a validation group

From here, you can:

  • Name the validation group
  • Add fields (standard order fields, custom order fields, and custom order line fields)
  • Define one or more rules, consisting of an operator and possibly a parameter, which need to return true for the field content to be considered valid
  • If two rules are created for a field, define if all or only one of the rules must validate

The operators available to you are:

Operator

Description

Required

Checks that the field is not empty

Contains/Does not contain

Checks for the presence/absence of a specific value

Equals/Does not equal

Checks the field for an exact value (and either approves or rejects it)

Is integer/Is numeric

Checks that the field contains an integer (whole numbers) or is numeric (whole numbers and decimals)

Minimum length/Maximum length

Checks the minimum of maximum length of a field value (in characters)

Is less/greater than

Checks against a minimum or maximum value. Works for both numbers and alphanumeric characters

Is valid email

Checks if the value is a valid email address

Regular expression

Allows you to enter a regular expression and check the field value against that. This allows you to check for a variety of formats, e.g. postal codes, phone numbers, and so forth.


For more details in regular expressions, please see .NET’s rules for regular expressions.

Once your validation group has been created, you can add it to a shopping cart as described in the Basic Concepts section of this document.

Localizing validation group names

Validation group names can be localized. Create a validation group in the default language, then change to another language using the language selector in the toolbar, and enter a name for the group in that language. Don’t forget to save the localized name.

Read more about working with internationalization here.

Order step validation exists to make sure users cannot modify the underlying HTML of your checkout process to skip order steps.

To prevent this from happening:

  • Go to Settings > Ecommerce > Advanced Configuration > Shopping Cart
  • Check the Enable step validation checkbox (Figure 7.1)
Figure 7.1 Order step validation

This ensures that no orders will be marked as Completed before it has passed the payment step.

It’s advisable to combine this with making the Payment method ID field a required in your validation group.

You can read more about the advanced settings in this article.

Address validation lets you set up and manage address validation methods based on address validation providers.

When a customer progresses through the checkout process, their billing and delivery addresses are then validated against the information provided by the address validation provider.

Dynamicweb currently supports using the Avalara address validation provider, which can be used with the Avalara Tax provider, and the FedEx address validation provider, for use with the FedEx shipping provider.

To set up address validation:

  • Go to Settings > Ecommerce > Orders > Address validation
  • Click new in the toolbar

This opens the Address vaidator settings window (Figure 8.1).

Figure 8.1 Creating an address validator

From here, you must:

  • Name the address validator
  • Activate the address validator by checking the Active checkbox
  • Select one or more countries for which the validator should be active
  • (Optional) Select one or more user groups for which address validation should not be used
  • Select your address validation provider
  • Fill out any parameters required by the provider – these will vary depending on the provider you use.

To implement the address validator in your order flow you have access to the AddressValidators loop and associated tags. For an example, refer to the InformationAddressValidation.html template (located in Files/Templates/eCom7/CartV2/Step).

With order contexts carts, you can create more than one type of shopping cart for a shop, website or solution. This makes it possible to e.g. create a Daily, a Weekly and a Monthly cart on a website, or to create a specific Quotes cart – read more about quotes here.

To create an order context cart:

  • Go to Settings > Ecommerce > Orders > Order contexts
  • Click New order context from the menu
  • Name the order context and select the shop(s) it should to work with (Figure 9.1)
  • Save the order context
Figure 9.1 Creating a new order context

You can create any number of context carts for your solution - daily carts, weekly carts, quotes carts, etc.

Once created, you will be able to select the context cart in the Context Cart dropdown of the shopping cart app settings - or you can select a context cart as the default cart in shop settings.

Once an order context has been associated with a shop, you should set that shop to be the shop context for your solution.

To so do:

  • Go to App > Websites and select your website to open the website settings
  • Click the Ecommerce button in the ribbon bar to open the Ecommerce website settings (Figure 10.1)
  • Select the shop context in the Shop dropdown menu
Figure 10.1 Setting a default shop context on a website

You can now associate your order context with the shop context of the website in the templates used on your site.

If nothing is selected in the shop-dropdown, order context carts are not rendered in frontend, since the system won’t know what the shop context is (and therefore will assume there are no order contexts to render).

Adding products to a context cart

In order to use your context carts in the frontend, you must render buttons which add products to your context cart. Use the OrderContexts loop and associated tags to do so.

From Settings > Ecommerce > Advanced configuration > Shopping Cart you have access to a number of advanced configuration options for the Shopping Cart app.

Read about the settings in this article.

Database

These are the database tables relevant for the Shopping Cart app and related functionality. 

EcomAddressValidatorSettings

Contains settings for providers in Settings -> Ecom -> Orders -> Address Validation.

Field name Data type Length
AddressValidatorSettingId int 4
AddressValidatorName nvarchar 255
AddressValidatorActive bit 1
AddressValidatorProviderSettings nvarchar Max
AddressValidatorUserGroupIds nvarchar Max

EcomValidationGroups

Contains validation groups as defined in Settings -> Ecommerce -> Orders -> Validation groups.

Field name Data type Length
ValidationGroupId nvarchar 50
ValidationGroupName nvarchar 255
ValidationGroupAutoId int 4
ValidationGroupDoNotValidateIfAllFieldsAreEmpty bit 1

EcomValidationGroupsTranslation

Contains translations (EcomValidationGroupsTranslationValidationGroupLanguageID) of validation groups (EcomValidationGroupsTranslationValidationGroupID).

Field name Data type Length
EcomValidationGroupsTranslationValidationGroupID nvarchar 50
EcomValidationGroupsTranslationValidationGroupLanguageID nvarchar 50
EcomValidationGroupsTranslationValidationGroupName nvarchar 255

EcomValidations

Contains field definitions (ValidationFieldName) for validation rules and keeps track of which validation groups it belongs to (ValidationGroupId).

Field name Data type Length
ValidationId nvarchar 50
ValidationGroupId nvarchar 50
ValidationFieldName nvarchar 255
ValidationUseAndOperator bit 1
ValidationFieldType nvarchar 255
ValidationAutoId int 4

EcomValidationRules

Contains validation rule definitions (ValidationRuleId) and keeps track of which fields (ValidationRuleValidationId) belong to a rule.

Field name Data type Length
ValidationRuleId nvarchar 50
ValidationRuleValidationId nvarchar 50
ValidationRuleType nvarchar 255
ValidationRuleParameters nvarchar Max
ValidationRuleAutoId int 4

EcomSavedForLater

Registers products (SavedForLaterProductId, SavedForLaterVariantId, SavedForlaterLangugageId) marked as Saved for Later during a session (SavedForLaterSessionId).

Field name Data type Length
SavedForLaterId int 4
SavedForLaterProductId nvarchar 30
SavedForLaterVariantId nvarchar 255
SavedForLaterLanguageId nvarchar 50
SavedForLaterSessionId int 4
SavedForLaterDateAdded datetime 8

These database tables are associated with order context carts:

EcomOrderContexts

Field name Data type Length
OrderContextId nvarchar 50
OrderContextName nvarchar 255
OrderContextAutoId int 4

EcomOrderContextAccessUserRelation

Field name Data type Length
OrderContextAccessUserAccessUserId int 4
OrderContextAccessUserOrderContextId nvarchar 50
OrderContextAccessUserOrderId nvarchar 50
OrderContextAccessUserRelationAutoId int 4

EcomOrderContextShopRelation

Field name Data type Length
OrderContextShopRelationContextId nvarchar 50
OrderContextShopRelationShopId nvarchar 50
OrderContextShopRelationAutoId int 4