Guides

CheckoutContext

A class responsible for sharing information between various CheckoutManagers.

πŸ“˜

CheckoutContext Version

The CheckoutContext maintains a "version" to ensure that any changes the customer makes to their basket after entering into the checkout process, e.g. adds an additional item or adjusts the quantity of an item, are not missed in shipping and taxation calculations.

Instantiation

var basket = CurrentCustomer.Basket();

// using default settings
var context = CheckoutContext.CreateCheckoutContext(CurrentCustomer, basket.VersionKey);

By default all of the following settings are set to true.

/// <summary>
    /// Defines checkout context settings.
    /// </summary>
    public interface ICheckoutContextSettings
    {
      /// <summary>
        /// Gets or sets the invoice number prefix to be added to the generated invoice in the invoice builder.
        /// </summary>
        string InvoiceNumberPrefix { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether or not to apply taxes to generated invoice.
        /// </summary>
        bool ApplyTaxesToInvoice { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether raise customer events.  Defaults to false
        /// </summary>
        /// <remarks>
        /// In some implementations, there may be quite a few saves to the customer record.  Use case for setting this to 
        /// false would be an API notification on a customer record change to prevent spamming of the notification. 
        /// </remarks>
        bool RaiseCustomerEvents { get; set; }
      
        /// <summary>
        /// Gets or sets a value indicating whether reset the customer manager data on version change.
        /// </summary>
        bool ResetCustomerManagerDataOnVersionChange { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether reset the payment manager data on version change.
        /// </summary>
        bool ResetPaymentManagerDataOnVersionChange { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether reset the extended manager data on version change.
        /// </summary>
        bool ResetExtendedManagerDataOnVersionChange { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether reset the shipping manager data on version change.
        /// </summary>
        bool ResetShippingManagerDataOnVersionChange { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether reset the offer manager data on version change.
        /// </summary>
        bool ResetOfferManagerDataOnVersionChange { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether to empty the basket on payment success.
        /// </summary>
        bool EmptyBasketOnPaymentSuccess { get; set; }
    }

To override the default settings

var settings = new CheckoutContextSettings()
{
  ResetCustomerManagerDataOnVersionChange = false,
  RaiseCustomerEvents = true,
  EmptyBasketOnPaymentSuccess = false
};

var basket = CurrentCustomer.Basket();

// using custom settings
var context = CheckoutContext.CreateCheckoutContext(CurrentCustomer, basket.VersionKey, settings);

In most cases, developers will not need to programatically instantiate the CheckoutContext as it is handled internally when instantiating the BasketCheckoutManager (Checkout) with the GetCheckoutManager([optional settings]) extension method.

Whats going on internally?

When the CheckoutContext first gets instantiated, a copy is made of all items in customers ItemCache (in most cases basket contents) so that it can be manipulated without actually affecting the users basket. Additional line items that are not specifically associated with the customer, such as shipping line items, are added to this internal copy.

The version key (GUID) is checked between the basket and the copy whenever the context is instantiated. Every Basket.Save() generates a new basket version which will in turn force a re-synchronization of the ItemCache copy maintained in the CheckoutContext.

The CheckoutContextChangeSettings are used to determine which additional objects, such as stored customer addresses, invoice notes, etc. when the CheckoutContext gets reset.

Properties

NameDescription
MerchelloContextGets the current IMerchelloContext (singleton)
ServicesGets the Merchello ServiceContext (singleton)
GatewaysGets the Merchello GatewayContext (singleton)
ItemCacheGets the IItemCache. This is a temporary collection of line items that is generally copied from the basket that can be modified while preparing the final invoice.
CustomerGets the ICustomerBase associated with the checkout.
VersionKeyGets the checkout version key. Generally used to ensure version consistency between the checkout manager and the basket.
IsNewVersionGets a value indicating whether this context is a new checkout version.
CacheGets Umbraco's IRuntimeCacheProvider - exposed for use in testing and Task Chains but generally is just a reference to ApplicationContext.Current.ApplicationCache.RuntimeCache
SettingsGets the ICheckoutContextSettings