Using a dynamic data source with selector components

In some instances, selector form components may benefit from a dynamic source of data. For example, if you need to enable selection from a list of objects, pages, custom table items, or other volatile data.

Connecting a drop-down list to a dynamic data source

The following example demonstrates how to connect a drop-down list form component to a dynamic data source:

1. Open your project in Visual Studio.
2. Create a new form component,and register it in the system.
3. In the model class:
   1. Inherit from SelectorFormComponent<TProperties>.
   2. Override the IEnumerable<SelectListItem> GetItems method and implement your data retrieval logic.
   3. (Optional) Cache the results of the operation.

using System.Web.Mvc;
using System.Linq;
using System.Collections.Generic;

using CMS.DocumentEngine;

using Kentico.Forms.Web.Mvc;

using LearningKit.FormBuilder.FormComponents;
using LearningKit.FormBuilder.FormComponentProperties;

[assembly: RegisterFormComponent(CustomDropDownComponent.IDENTIFIER, typeof(CustomDropDownComponent), "Drop-down with custom data", IconClass = "icon-menu")]

namespace LearningKit.FormBuilder.FormComponents
{
    public class CustomDropDownComponent : SelectorFormComponent<CustomDropDownComponentProperties>
    {
        public const string IDENTIFIER = "CustomDropDownComponent";

        // Retrieves data to be displayed in the selector
        protected override IEnumerable<SelectListItem> GetItems()
        {
            // Perform data retrieval operations here
            // The following example retrieves all pages of the 'DancingGoatMvc.Article' page type 
            // located under the 'Articles' section of the Dancing Goat sample website
            DocumentQuery query = DocumentHelper.GetDocuments("DancingGoatMvc.Article")
                                .Path("/Articles/", PathTypeEnum.Children)
                                .Columns("DocumentName", "DocumentGUID")
                                .OnSite("DancingGoatMvc")
                                .Culture("en-us")
                                .LatestVersion();

            var sampleData = query.TypedResult.Select(x => new { Name = x.DocumentName,
                                                                 Guid = x.DocumentGUID.ToString() });

            // Iterates over retrieved data and transforms it into SelectListItems
            foreach (var item in sampleData)
            {
                var listItem = new SelectListItem()
                {
                    Value = item.Guid,
                    Text = item.Name
                };

                yield return listItem;
            }
        }
    }
}

4. In the properties class, inherit from SelectorProperties. Optionally, you can implement additional properties required for further customization.

   CustomDropDownComponentProperties.cs

   Copy

   
   
   
    using Kentico.Forms.Web.Mvc;
   
    namespace LearningKit.FormBuilder.FormComponentProperties
    {
        public class CustomDropDownComponentProperties : SelectorProperties
        {
            // Implement any required custom properties here
        }
    }
   
   
    

5. Create a new _CustomDropDownComponent view under ~/Views/Shared/FormComponents that renders a drop-down list populated with the retrieved data. 

   _CustomDropDownComponent.cshtml

   Copy

   
   
   
    @using Kentico.Forms.Web.Mvc
    @using LearningKit.FormBuilder.FormComponents
   
    @model CustomDropDownComponent
   
    @{
        var htmlAttributes = ViewData.GetEditorHtmlAttributes();
    }
   
    @* Invoking a Get operation on the component's 'Items' property executes the GetItems method. *@
    @Html.DropDownListFor(x => x.SelectedValue, Model.Items, null, htmlAttributes)
   
   
    

   The SelectedValue and Items properties, inherited from SelectorFormComponent<TProperties>, hold the value selected by a user, and the list of items to be displayed in the drop-down list, respectively.

The form component dynamically retrieves the specified data when instantiated and populates the corresponding drop-down selector.