Walkthrough: Adding customer preferences to the Retail online sample store [AX 2012]

Updated: April 30, 2014

Applies To: Microsoft Dynamics AX 2012 R3

To make the new customer preference data available in SharePoint pages, you must modify code in Retail SDK\Online Channel\Storefront\Storefront.sln. First, you add code to make the new fields available in the data model and the view model. Then you modify the web controls, and then you modify the store pages to enable display, entry, and modification of the new fields. Finally, you rebuild and redeploy the solution.

You make the new field available on the Customer control, which is included on the Account page and the Edit Profile. On the Account page, the field is read-only. Customers can edit the field on the EditProfile page.

These walkthroughs illustrate adding a field to a retail channel that enables customers to opt in to receive special offers by email. In this scenario, the retailer wants to indicate whether customers wish to receive email about special offers, either in an online store or in a modern POS client. The walkthroughs should be completed in the following order:

  1. Walkthrough: Adding a table for customer preferences to the AX 2012 database

  2. Walkthrough: Extending the CRT to add customer preference data for Retail clients

  3. Walkthrough: Extending retail data distribution infrastructure for customer preferences

  4. Walkthrough: Adding customer preferences to the Retail online sample store (online store only)

In the SharePoint.Web.Services project of the Storefront.sln solution, you modify ViewModel\Customer.cs and ObjectModel\Customermapper.cs. You modify the Javascript files Customer.js and CustomerDisplay.js inStorefront\Scripts\Scripts\ViewModel.

To modify the view model

  1. Open the Retail SDK\Online channel folder and open Storefront.sln. and navigate to Modify Customer.cs in SharePoint.Web.Services\ViewModel\Customer.cs by adding the following code at the end of the file:

  2. Open Customer.cs in SharePoint.Web.Services\ViewModel.

  3. Add the following code at the end of the file:

           [DataMember]
            public Enum EmailOptIn { get; set; }
    

To map the new field to the object model

  1. You modify SharePoint.Web.Services/ObjectModel/ CustomerMapper.cs to create a mapping between the new fields in the data model and the view model.

  2. You add the new fields to ConvertToViewModel and ConvertToDataModel methods.

    Add the following lines of code to the ConvertToViewModel method after the first If statement.

    bool emailOptIn = false; /// NEW Code
                var emailOptInExtensionProperty = customer.ExtensionProperties.Where(c => c.Key == "EMAILOPTIN").FirstOrDefault();
                if (emailOptInExtensionProperty != null)
                {
                    int intEmailOptIn = (int)emailOptInExtensionProperty.Value.GetPropertyValue(); // NEW Code
                    emailOptIn = intEmailOptIn == 0 ? false : true;
                }
    
    
  3. Add the following code after the statement LoyaltyCardNumber – customer.LoyaltyCardNumber,.

    EmailOptIn = emailOptIn // NEW Code
    

    The following example shows the ConvertToViewModel method after adding the code.

    internal static ViewModel.Customer ConvertToViewModel(DataModel.Customer customer)
            {
                if (customer == null)
                {
                    throw new ArgumentNullException("customer");
                }
                bool emailOptIn = false; /// NEW Code
                var emailOptInExtensionProperty = customer.ExtensionProperties.Where(c => c.Key == "EMAILOPTIN").FirstOrDefault();
                if (emailOptInExtensionProperty != null)
                {
                    int intEmailOptIn = (int)emailOptInExtensionProperty.Value.GetPropertyValue(); // NEW Code
                    emailOptIn = intEmailOptIn == 0 ? false : true;
                }
    
                ViewModel.Customer vmCustomer = new ViewModel.Customer()
                {
                    AccountNumber = customer.AccountNumber,
                    Addresses = ConvertToViewModel(customer, customer.Addresses),
                    Email = customer.Email,
                    FirstName = customer.FirstName,
                    LastName = customer.LastName,
                    MiddleName = customer.MiddleName,
                    Phone = customer.Phone,
                    PhoneExt = customer.PhoneExt,
                    RecordId = customer.RecordId,
                    Url = customer.Url,
                    PrimaryAddress = AddressMapper.ConvertToViewModel(customer.GetPrimaryAddress(), customer),
                    LoyaltyCardNumber = customer.LoyaltyCardNumber,
                    EmailOptIn = emailOptIn // NEW Code
                };
    
                return vmCustomer;
            }
    
  4. Add the following line of code to the UpdateDataModel method.

    dataModelCustomer["EMAILOPTIN"] = Convert.ToInt64(customer.EmailOptIn); ///NEW Code
    
    

    The following example shows where the line is added.

    internal static DataModel.Customer UpdateDataModel(DataModel.Customer dataModelCustomer, ViewModel.Customer customer)
            {
                if (customer == null)
                {
                    throw new ArgumentNullException("customer");
                }
    
                if (dataModelCustomer == null)
                {
                    throw new ArgumentNullException("dataModelCustomer");
                }
    
                dataModelCustomer.Email = customer.Email;
                dataModelCustomer.FirstName = customer.FirstName;
                dataModelCustomer.LastName = customer.LastName;
                dataModelCustomer.MiddleName = customer.MiddleName;
                dataModelCustomer.Phone = customer.Phone;
                dataModelCustomer.PhoneExt = customer.PhoneExt;
                dataModelCustomer.Url = customer.Url;
                dataModelCustomer.Language = "en-us"; // only support en-Us in the UI at this time 
                dataModelCustomer. ["EMAILOPTIN"] = Convert.ToInt64(customer.EmailOptIn); ///NEW Code
    
    
    
    
    
  5. Add the following example code to ConvertToDataModel immediately before the return statement:

                dmCustomer["Age"] = customer.Age;
                dmCustomer["SpecialOffers"] = customer.SpecialOffers;
    
    

To modify Customer.js

  1. Open Customer.js in the Scripts\Scripts folder of Storefront.sln.

  2. Add the following code to the function updateCustomer.

    /// NEW Code
                if ($view.find('.msax-EmailOptInCheckBox').is(':checked')) {
                    customer.EmailOptIn = true;
                }
                else {
                    customer.EmailOptIn = false;
                }//NEW code
    

    The following example shows the function after the code is added.

       // Update a customer
        this.UpdateCustomer = function () {
            if (!Microsoft.Trigger($view, "UpdateCustomer")) {
                return;
            }
    
            validator.Validate($view);
            // NEW Code
            if ($view.find('.msax-EmailOptInCheckBox').is(':checked')) {
                customer.EmailOptIn = true;
            }
            else {
                customer.EmailOptIn = false;
            } //NEW code
    
            if (validator.IsValid) {
                services.UpdateCustomer(customer);
            }
        }
    

To modify CustomerDisplay.js

  1. Open CustomerDisplay.js in the Scripts\Scripts folder of Storefront.sln.

  2. Add the following code to the Initialize function.

    // NEW Code
            if (customer.EmailOptIn) {
                $view.find('.msax-EmailOptInCheckBox').prop('checked', true);
            }
            else {
                $view.find('.msax-EmailOptInCheckBox').prop('checked', false);
            }
    
            $view.find('.msax-EmailOptInCheckBox').attr("disabled", true);//NEW code
    
    

    The following example shows the Initialize function after adding the code.

    // CustomerViewModel constructor.
        function Initialize() {
            // Attach the Render event to the AfterRefresh
            // event so when the data is loaded it will be
            // displayed immediately.
            services.OnGetCustomerSuccess(onGetCustomerSuccess);
            services.OnGetCustomerFailure(onGetCustomerFailure);
            
            binder = new Microsoft.Dynamics.Retail.SharePoint.Web.UI.TemplateBinder(
                $view.find('.msax-CustomerDisplayTemplate'),
                $view.find('.msax-CustomerDisplayContainer'));
    
            // Set the customer control to refresh upon page load,
            me.GetCustomer();
        }
    
        // bind the customer to the display only fields
        this.BindCustomerDisplayData = function (customer) {
            $view.find('.msax-CustomerDisplayAddress1').text(customer.FirstName + ' ' + customer.MiddleName + ' ' + customer.LastName);
            $view.find('.msax-CustomerDisplayAddress2').text(customer.PrimaryAddress.StreetNumber + ' ' + customer.PrimaryAddress.Street);
            $view.find('.msax-CustomerDisplayAddress3').text(customer.PrimaryAddress.City + ' ' + customer.PrimaryAddress.State + ' ' + customer.PrimaryAddress.ZipCode);
            $view.find('.msax-CustomerDisplayAddress4').text(customer.PrimaryAddress.Country);
            $view.find('.msax-CustomerDisplayPrimaryEmail').text(customer.Email);
            $view.find('.msax-CustomerDisplayLoyaltyNumber').text(customer.LoyaltyCardNumber);
            // NEW Code
            if (customer.EmailOptIn) {
                $view.find('.msax-EmailOptInCheckBox').prop('checked', true);
            }
            else {
                $view.find('.msax-EmailOptInCheckBox').prop('checked', false);
            }
    
            $view.find('.msax-EmailOptInCheckBox').attr("disabled", true); //NEW code
    
        }
    

To modify SharePointWebControls/Customer/Customer.cs

  1. Open Customer.cs in the SharePoint.Web.Controls/Customer folder.

  2. Add the following code to the RetailWebControl class.

    private HtmlInputCheckBox emailOptIn; // NEW code
    

    The following example shows the after adding the code to the RetailWebControl class.

    public class Customer : RetailWebControl
        {
            private HtmlInputText firstName;
            private HtmlInputText lastName;
            private HtmlInputText email;
            private HtmlInputText phone;
    
            private HtmlInputText street;
            private HtmlInputText city;
            private HtmlInputText state;
            private HtmlInputText zipCode;
            private HtmlInputText country;
            private HtmlInputCheckBox emailOptIn; // NEW code
    
    
  3. Add the following two code blocks to the GetCustomerTemplate method.

    • This code creates the checkbox.

      ///NEW code
                  this.emailOptIn = ControlFactory.CreateCheckBox("msax-EmailOptInCheckBox");
                  this.emailOptIn.AddAttribute(AXDataBindAttributes.Value, "EmailOptIn");
                  HtmlLabel emailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, null, this.emailOptIn);
                  HtmlFieldPanel emailOptInContainer = ControlFactory.CreateFieldPanel(emailOptInLabel, this.emailOptIn, "msax-CustomerEmailOptIn"); //NEW code
      
      
    • This code adds the control to the container.

      contactInfo.Controls.Add(emailOptInContainer);
      
      
  4. The following example shows the GetCustomerTemplate method with the new code added.

    private HtmlTemplate GetCustomerTemplate()
            {
                // Create the master template to put the shopping cart table in.
                HtmlTemplate template = new HtmlTemplate();
                template.AddCssClass("msax-CustomerTemplate");
    
                this.CssClass = "msax-CustomerControl";
    
                
                HtmlFieldSet contactInfo = ControlFactory.CreateFieldSet("msax-ContactInfoControls");
                HtmlParagraph contactInfoParagraph = ControlFactory.CreateParagraph("msax-ContactInfoHeader");
                contactInfoParagraph.InnerText = ControlResources.CustomerContactInformation;
    
                // Create the controls     
                this.email = ControlFactory.CreateTextBox("msax-EmailTextBox");
                this.email.AddAttribute(AXDataBindAttributes.Value, "Email");
                this.email.AddRegularExpressionValidator(ControlResources.CustomerEmailNotSpecified, @"\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*");
                this.email.MaxLength = 255;
                HtmlLabel emailLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmail, null, this.email);
                HtmlFieldPanel emailContainer = ControlFactory.CreateFieldPanel(emailLabel, this.email, "msax-CustomerEmail");
                
                this.firstName = ControlFactory.CreateTextBox("msax-FirstNameTextBox");
                this.firstName.AddAttribute(AXDataBindAttributes.Value, "FirstName");
                this.firstName.AddRequiredFieldValidator(ControlResources.CustomerFirstnameNotSpecified, "");
                this.firstName.MaxLength = 100;
                HtmlLabel firstNameLabel = ControlFactory.CreateLabel(ControlResources.CustomerFirstName, null, this.firstName);
                HtmlFieldPanel firstNameContainer = ControlFactory.CreateFieldPanel(firstNameLabel, this.firstName, "msax-CustomerFirstName");
    
                this.lastName = ControlFactory.CreateTextBox("msax-LastNameTextBox");
                this.lastName.AddAttribute(AXDataBindAttributes.Value, "LastName");
                this.lastName.AddRequiredFieldValidator(ControlResources.CustomerLastnameNotSpecified, "");
                this.lastName.MaxLength = 100;
                HtmlLabel lastNameLabel = ControlFactory.CreateLabel(ControlResources.CustomerLastName, null, this.lastName);
                HtmlFieldPanel lastNameContainer = ControlFactory.CreateFieldPanel(lastNameLabel, this.lastName, "msax-CustomerLastName");
    
                this.phone = ControlFactory.CreateTextBox("msax-PhoneTextBox");
                this.phone.AddAttribute(AXDataBindAttributes.Value, "Phone");
                this.phone.MaxLength = 255;
                HtmlLabel phoneLabel = ControlFactory.CreateLabel(ControlResources.CustomerPhone, null, this.phone);
                HtmlFieldPanel phoneContainer = ControlFactory.CreateFieldPanel(phoneLabel, this.phone, "msax-CustomerPhone");
    
                /// NEW code
                this.emailOptIn = ControlFactory.CreateCheckBox("msax-EmailOptInCheckBox");
                this.emailOptIn.AddAttribute(AXDataBindAttributes.Value, "EmailOptIn");
                HtmlLabel emailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, null, this.emailOptIn);
                HtmlFieldPanel emailOptInContainer = ControlFactory.CreateFieldPanel(emailOptInLabel, this.emailOptIn, "msax-CustomerEmailOptIn");
                /// NEW code
    
                // Add the individual controls to the fieldset       
                contactInfo.Controls.Add(contactInfoParagraph);
                contactInfo.Controls.Add(emailContainer);
                contactInfo.Controls.Add(firstNameContainer);
                contactInfo.Controls.Add(lastNameContainer);
                contactInfo.Controls.Add(phoneContainer);
    
                contactInfo.Controls.Add(emailOptInContainer); //NEW code
    
                HtmlFieldSet primaryAddressInfo = ControlFactory.CreateFieldSet("msax-AddressInfoControls");
                HtmlParagraph primaryAddressInfoParagraph = ControlFactory.CreateParagraph("msax-AddressInfoHeader");
                primaryAddressInfoParagraph.InnerText = ControlResources.CustomerAddressInformation;
    
    

To modify SharePointWebControls/Customer/CustomerDisplay.cs

  1. Open CustomerDisplay.cs

  2. Add the following code line to the header.

    using System.Web.UI.HtmlControls; /// NEW Code
    
    
  3. Add the following code to the GetCustomerTemplate method.

    /// NEW code
                HtmlLabel displayEmailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, "msax-CustomerDisplayEmailOptInLabel");
                HtmlInputCheckBox displayEmailOptIn = ControlFactory.CreateCheckBox("msax-CustomerDisplayEmailOptIn");
                /// NEW code
    
    
  4. Add the following code to the GetCustomerTemplate method.

    /// NEW Code
                displayFieldSet.Controls.Add(displayEmailOptInLabel);
                displayFieldSet.Controls.Add(displayEmailOptIn);
                /// NEW Code
    
    
  5. The following example shows the new code added to the GetCustomerTemplate method.

    private HtmlTemplate GetCustomerTemplate()
            {
                // Create the master template to put the shopping cart table in.
                HtmlTemplate template = new HtmlTemplate();
                template.AddCssClass("msax-CustomerDisplayTemplate");
    
                this.CssClass = "msax-CustomerDisplayControl";
    
                HtmlFieldSet displayFieldSet = ControlFactory.CreateFieldSet("msax-CustomerDisplayControls");
    
                HtmlLabel displayAddressLabel = ControlFactory.CreateLabel(ControlResources.CustomerDisplayAddressLabel, "msax-CustomerDisplayAddressLabel");
                HtmlSpan displayAddressLine1 = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayAddress1");
                HtmlSpan displayAddressLine2 = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayAddress2");
                HtmlSpan displayAddressLine3 = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayAddress3");
                HtmlSpan displayAddressLine4 = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayAddress4");
                HtmlSpan displayAddressLine5 = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayAddress5");
                
                HtmlLabel displayEmailLabel = ControlFactory.CreateLabel(ControlResources.CustomerDisplayPrimaryEmail, "msax-CustomerDisplayPrimaryEmailLabel");
                HtmlSpan displayEmail = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayPrimaryEmail");
    
                /// NEW code
                HtmlLabel displayEmailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, "msax-CustomerDisplayEmailOptInLabel");
                HtmlInputCheckBox displayEmailOptIn = ControlFactory.CreateCheckBox("msax-CustomerDisplayEmailOptIn");
                /// NEW code
    
                displayFieldSet.Controls.Add(displayAddressLabel);
                displayFieldSet.Controls.Add(displayAddressLine1);
                displayFieldSet.Controls.Add(displayAddressLine2);
                displayFieldSet.Controls.Add(displayAddressLine3);
                displayFieldSet.Controls.Add(displayAddressLine4);
                displayFieldSet.Controls.Add(displayAddressLine5);
    
                /// NEW Code
                displayFieldSet.Controls.Add(displayEmailOptInLabel);
                displayFieldSet.Controls.Add(displayEmailOptIn);
                /// NEW Code
    
                displayFieldSet.Controls.Add(displayEmailLabel);
                displayFieldSet.Controls.Add(displayEmail);
    
                template.Controls.Add(displayFieldSet);
                            
                return template;
            }
        }
    

Modify the following files in SharePoint.Web.Storefront/Controls project:

  • ControlResources.Designer.cs

  • ControlResources.resx

      /// <summary> NEW code
        ///   Looks up a localized string similar to Email for special offers:.
        /// </summary>
        internal static string CustomerEmailOptIn
        {
            get
            {
                return ResourceManager.GetString("CustomerEmailOptIn", resourceCulture);
            }
        }
        /// NEW code

The following example shows where the new code is added in ControlResourcesDisigner.cs.

  
        /// <summary>
        ///   Looks up a localized string similar to Share my information with Contoso partners..
        /// </summary>
        internal static string CustomerShareInformation {
            get {
                return ResourceManager.GetString("CustomerShareInformation", resourceCulture);
            }
        }

        /// <summary> NEW code
        ///   Looks up a localized string similar to Email for special offers:.
        /// </summary>
        internal static string CustomerEmailOptIn
        {
            get
            {
                return ResourceManager.GetString("CustomerEmailOptIn", resourceCulture);
            }
        }
        /// NEW code

        /// <summary>
        ///   Looks up a localized string similar to State:.
        /// </summary>
        internal static string CustomerState {
            get {
                return ResourceManager.GetString("CustomerState", resourceCulture);
            }
        }
        

Add text for the labels and messages to Storefront/Controls/ControlResources.resx as shown in the following table:

Name

Value

Comment

CustomerEmailOptIn

Email for special offers

Checkbox for EmailOptIn


Announcements: To see known issues and recent fixes, use Issue search in Microsoft Dynamics Lifecycle Services (LCS).

Community Additions

ADD
Show: