Read and Write Custom Properties for an Order

OVERVIEW

This article will help you as a developer in cases where you need to integrate with external applications to save and read additional information about an order.  For example, these could include properties that systems such as an ERP or CRM might need in order to properly communicate information about an order to fulfill it.

REQUIREMENTS

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

• Visual Studio 2012 or newer
• Understanding of C#
• Familiarity with building ASP.Net applications

GETTING STARTED

You should have a project ready to insert code to complete your application, such as a DNN CMS module, or a custom workflow.

READ AND WRITE CUSTOM PROPERTIES FOR AN ORDER

Before you can write or successfully add your code, you will first need to ensure that your project imports the following assemblies.

• Hotcakes.Commerce.dll
• Hotcakes.Modules.dll
• Hotcakes.Web.dll

We are finally at the point of writing some code to add, update and list your own custom properties to Hotcakes Commerce orders.  If you were to use the example you are about to see the same way it was generated, it would allow you to submit, save, and list custom properties for an order, like shown in the image below.

The examples below are thoroughly commented and assume you are writing a web forms interface.  However, this can still apply to pretty much any server-side code examples.  The code behind is the most important part of the sample.

• HTML
• Codebehind

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="CustomOrderProperties.ascx.cs" Inherits="CodeSamples.CustomOrderProperties" %>
<%@ Register tagPrefix="dnn" tagName="Label" src="~/controls/labelcontrol.ascx" %>

 

 

using System;
using System.Linq;
using DotNetNuke.Entities.Modules;
using Hotcakes.Commerce;
using Hotcakes.Commerce.Extensions;
using Hotcakes.Commerce.Orders;

namespace CodeSamples
{

    public partial class CustomOrderProperties : PortalModuleBase
    {

        #region Private Properties

        // any unique key to identify your orginaization
        private const string DEVELOPERID = "YOURUNIQUEID";

        private HotcakesApplication _HccApp = null;
        /// 
        /// Required to access most of the Hotcakes API
        /// 
        private HotcakesApplication HccApp
        {
            get
            {
                if (_HccApp == null) _HccApp = HccAppHelper.InitHccApp();
                return _HccApp;
            }
        }

        #endregion

        protected void Page_Load(object sender, EventArgs e)
        {
            // simply setting a default order number to work with for the sample
            txtOrderNumber.Text = "1";
            // bind data to the view
            BindData();
        }

        protected void AddCustomProperty(object sender, EventArgs e)
        {

            // perform a search based upon the order number
            var results = HccApp.OrderServices.Orders.FindByCriteria(new OrderSearchCriteria()
            {
                OrderNumber = txtOrderNumber.Text.Trim()
            });

            // only proceed if there are results
            if (results != null && results.Count > 0)
            {
                // get an actual order from the search results
                var order = HccApp.OrderServices.Orders.FindForCurrentStore(results[0].bvin);
                // set an object to see if the property exists already
                var prop = order.CustomProperties.GetProperty(DEVELOPERID, txtPropertyName.Text.Trim());

                if (prop != null)
                {
                    // update an existing order property
                    order.CustomProperties.SetProperty(DEVELOPERID, txtPropertyName.Text.Trim(),
                        txtPropertyValue.Text.Trim());
                }
                else
                {
                    // create a new order property
                    order.CustomProperties.Add(DEVELOPERID, txtPropertyName.Text.Trim(), txtPropertyValue.Text.Trim());
                }

                // update the order to save the new property
                HccApp.OrderServices.Orders.Update(order);
            }

            BindData();
        }

        private void BindData()
        {
            // only proceed if there is an order number to work with
            if (!string.IsNullOrEmpty(txtOrderNumber.Text))
            {
                // perform a search based upon the order number
                var results = HccApp.OrderServices.Orders.FindByCriteria(new OrderSearchCriteria()
                {
                    // pass in an order number from the form field
                    OrderNumber = txtOrderNumber.Text.Trim()
                });

                // only proceed if there are results
                if (results != null && results.Count > 0)
                {
                    // generate a collection of custom properties matching your unique developer id
                    var props =
                        results[0].CustomProperties.Where(
                            y => y.DeveloperId.Trim().ToLowerInvariant() == DEVELOPERID.ToLowerInvariant());

                    // only proceed if there is at least one property
                    if (props.Any())
                    {
                        // bind the properties to the view
                        grdProperties.DataSource = props;
                        grdProperties.DataBind();
                    }
                }
            }
        }

    }

}