David Harlow
Dec 21, 2017
  4289
(4 votes)

Extending Episerver Forms: Postcode Lookup Tool

A common requirement from clients we have at Redweb is the ability to extend Episerver forms to provide a postcode lookup tool, which is now an occurring component of any form requiring an address. Despite Episerver Forms providing a simplistic block-based approach to building a form, there is no native method for enabling the different elements to interact with one another.

To create our postcode lookup form element, we built a view consisting of a text input for the postcode and a hidden dropdown to display the response of an asynchronous API request to a postcode lookup service. Once a dropdown value has been selected, the relevant input elements within that form will need populating with its respective data.

To ensure that we populate the correct fields with the correct data, we built several mapping properties onto the form element that represent the different properties of the address that is returned by the postcode lookup service.

    [ContentType(
        DisplayName = "Postcode Address Lookup",
        GUID = "{A4EE6053-3932-4300-8B3B-7BABF9AEAB67}",
        Order = 4000)]
    [AvailableValidatorTypes(Include = new Type[] { typeof(PostcodeValidator) })]
    public class PostcodeLookupElementBlock : ValidatableElementBlockBase
    {
        [Display(
            Name = "Company Mapping",
            Description = "Specify the element for the company input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 10
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string CompanyMapping { get; set; }

        [Display(
            Name = "Building Number Mapping",
            Description = "Specify the element for the building number input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 20
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string BuildingNoMapping { get; set; }

        [Display(
            Name = "Address Line 1 Mapping",
            Description = "Specify the element for the address line 1 input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 30
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string AddressLine1Mapping { get; set; }

        [Display(
            Name = "Address Line 2 Mapping",
            Description = "Specify the element for the address line 2 input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 40
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string AddressLine2Mapping { get; set; }

        [Display(
            Name = "Address Line 3 Mapping",
            Description = "Specify the element for the address line 3 input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 50
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string AddressLine3Mapping { get; set; }

        [Display(
            Name = "Town Mapping",
            Description = "Specify the element for the town input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 60
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string TownMapping { get; set; }

        [Display(
            Name = "County Mapping",
            Description = "Specify the element for the County input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 70
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string CountyMapping { get; set; }

        [Display(
            Name = "Country Mapping",
            Description = "Specify the element for the Country input element",
            GroupName = PropertyGroupNames.Configuration,
            Order = 80
        )]
        [EditorDescriptor(EditorDescriptorType = typeof(FormPropertyEditorDescriptor))]
        public virtual string CountryMapping { get; set; }
    }

As can be seen, these properties use a custom editor descriptor attribute which utilises a selection factory to build a SelectItem object of all the names of all other elements within the current form so that the user can simply map the different parts of an address to their respective element block.

    public class FormPropertySelectionFactory : ServiceBase, ISelectionFactory
    {
        private Injected<IContentRepository> ReadWriteContentService { get; set; }

        /// <summary>
        /// Gets the selections.
        /// </summary>
        /// <param name="metadata">The metadata.</param>
        /// <returns></returns>
        public IEnumerable<ISelectItem> GetSelections(ExtendedMetadata metadata)
        {
            var fieldList = new List<SelectItem>();
            var form = metadata.FindOwnerContent().ParentLink;

            // Get all children properties of form that are text inputs
            var children = ReadWriteContentService.Service
                .GetChildren<ElementBlockBase>(form)
                .OfType<TextboxElementBlock>();

            foreach (var field in children)
            {
                fieldList.Add(new SelectItem { Value = field.FormElement.ElementName, Text = field.Label});
            }
            return fieldList;
        }
    }
    public class FormPropertyEditorDescriptor : EditorDescriptor
    {
        public override void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)
        {
            SelectionFactoryType = typeof(FormPropertySelectionFactory);
            ClientEditingClass = "epi-cms/contentediting/editors/SelectionEditor";

            base.ModifyMetadata(metadata, attributes);
        }

    }

Ensuring that the value of the property selected represents a value that can be used to easily locate the separate form elements via a front-end framework, we can then populate these form elements with their respective data returned from the API request.

Using this approach allows us to provide a customizable postcode lookup tool which enables the use of as many, or as few aspects of an address as required, whilst also retaining Episerver Form’s block-based structure.

Image CMSpostcode.png

Image postcode.png

Dec 21, 2017

Comments

Dec 22, 2017 09:29 AM

good work :-)

OlivierG
OlivierG May 28, 2021 06:10 PM

Hi David,

I know this is an old post, but can provide insights on how we would implement the actual connection to the api?

Thanks!

Please login to comment.
Latest blogs
Content Delivery API – The Case of the Duplicate API Refresh Token

Creating a custom refresh provider to resolve the issues with duplicate tokens in the DXC The post Content Delivery API – The Case of the Duplicate...

David Lewis | Sep 29, 2022 | Syndicated blog

New Optimizely certifications - register for beta testing before November 1st

In January 2023, Optimizely is making updates to the current versions of our certification exams to make sure that each exam covers the necessary...

Jamilia Buzurukova | Sep 28, 2022

Optimizely community meetup - Sept 29 (virtual + Melbourne)

Super excited to be presenting this Thursday the 29th of September at the Optimizely community meetup. For the full details and RSVP's see the...

Ynze | Sep 27, 2022 | Syndicated blog

Preview multiple Visitor Groups directly while browsing your Optimizely site

Visitor groups are great - it's an easy way to add personalization towards market segments to your site. But it does come with it's own set of...

Allan Thraen | Sep 26, 2022 | Syndicated blog