Save Custom Fields During Add to Cart, Checkout, and Place Order

OVERVIEW

If you haven't found out already, Hotcakes is insanely flexible in how it can allow you to make it work for your unique needs.  This article helps you to save custom information when a customer chooses to add a product to the shopping cart, go to the checkout page, or submit their order.  

REQUIREMENTS

The following pre-requisites will be necessary to accomplish the goals of this article:

• General understanding of REST and API’s
• Understanding of C# and/or JavaScript
• Visual Studio 2012 or newer

GETTING STARTED

This article takes advantage of three of the extension points available to you in Hotcakes.  It is strongly suggested that you first become familiar with custom viewsets and the action delegate pipeline prior to attempting to perform the steps outlined here.

SAVING CUSTOM INFORMATION IN VIEWS

Saving custom information during the workflow of your customers is quite easier than you might think, despite there being a couple of places to enable it.  This method allows you to use any API or data source that you want to save custom information submitted by customers.  

Architecture

You will use two extension points to make this happen.  First, you will need to update the respective view to include the form fields that you want to display to your customers.  The other extension point is the action delegate pipeline.  This extension point allows you to parse the form and take any programmatic action on the values found in the form submission - including your custom fields!

Here is a grid to help you determine which modifications to make, depending on the use case you're trying to achieve.

Use Case	Integration Method	View Path for Custom Fields
Add to Cart button clicked	BeforeProductAddedToCart	~\Portals\_default\HotcakesViews\VIEWSETNAME\Views\Products\Index.cshtml
Checkout clicked	BeforeProceedToCheckout	~\Portals\_default\HotcakesViews\VIEWSETNAME\Views\Cart\Index.cshtml
Place Order clicked	BeforeCheckoutCompleted	~\Portals\_default\HotcakesViews\VIEWSETNAME\Views\Checkout\Index.cshtml

It is worth noting that while the primary view file for each use case was listed, you could also add a new partial view and include that in your view like the sample below, assuming your partial view file name is CustomFields,cshtml and that you put it in the same folder as the Index.cshtml file.

@Html.Partial("_CustomFields", Model)

Save & Display Submitted Information

In general, if you want to display the custom values to the merchant in the store administration, you will want to either save a public and/or private order note, or update the product type properties.  Any of these methods will end up being displayed to the merchant in some way.

You can also save information to custom product properties and order properties, and while the values would not immediately appear to merchants during their day to day activities, these areas are incredibly useful for integration or sending to other systems and API's.  Don't let yourself feel restricted though.  You can of course use a combination of any of the mentioned methods.

Regardless to which step you are choosing to save custom information from customers, the steps are nearly identical.

Example Use Case

Let's assume that you as a merchant need to ask the customer for the date that they would like the product(s) shipped.

The following code samples assume that you want to add a public and private order note to an order upon check out.  This would directly align with the "Checkout clicked" use case mentioned above.  If you're applying this logic to one of the other use cases, simply use the other file(s)/method(s) mentioned above.

• Checkout View Changes
• Action Delegate Code

The example below adds a labeled Textbox to the view and sets it's initial value to 7 days in the future.  The HTML shown isn't all required.  All you really need is the input tag.

@functions
{

    string getDefaultDate()
    {
        return DateTime.Now.AddDays(7).ToShortDateString();
    }

}
<div class="dnnFormItem">
    <!-- in many stores, you might want to localize the label below -->
    <label class="dnnLabel">Date Needed:</label>
    <input name="dateNeeded" id="dateNeeded" maxlength="10" value="@Html.Raw(getDefaultDate())"/>
</div>

The example below parses the form for the expected field, validates the value, and then adds a new note to the order for the customer and the merchant.  You may need to include a new reference to System.Web in your project.

public IntegrationResult BeforeCheckoutCompleted(HotcakesApplication hccApp, Hotcakes.Modules.Core.Models.CheckoutViewModel model)
{

    // get a reference to the submitted form
    var form = HttpContext.Current.Request.Form;
            
    // grab the date needed from the form fields
    var strDateNeeded = form["dateNeeded"];
            
    // validate the date
    var dteDateNeeded = DateTime.MinValue;
    var dateIsValid = DateTime.TryParse(strDateNeeded, out dteDateNeeded);

    // if the date isn't valid...
    if (!dateIsValid) 
    {
        // do not let the customer proceed
        return new IntegrationResult
        {
            IsAborted = true,
            AbortMessage = string.Format("The date you need the order by needs to be in a valid date format.")
        };                
    }

    // get an instance of the shopping cart to work with
    Order basket = SessionManager.CurrentShoppingCart(hccApp.OrderServices, hccApp.CurrentStore);

    // add a private note to the order for store administrators to see
    basket.Notes.Add(new OrderNote
    {
        IsPublic = false,
        Note = string.Format("<strong>CUSTOM INSTRUCTIONS:</strong> The customer needs the order by {0}", dteDateNeeded.ToShortDateString())
    });

    // add a public note for the customer to see
    basket.Notes.Add(new OrderNote
    {
        IsPublic = true,
        Note = string.Format("You said that you need the order by {0}", dteDateNeeded.ToShortDateString())
    });

    // save the notes to the order
    hccApp.OrderServices.Orders.Update(basket);

    // all is well, allow the customer to proceed
    return new IntegrationResult
    {
        IsAborted = false
    };

}