606 views
In this article, we will review the Autocomplete UI Type control in detail to understand what capabilities we have available to us with and without further customisation.
What Does the Autocomplete UI Type Control Do?
The Autocomplete control provides the user with a list of potentially search matches to identify the entity with only a partial match. This occurs only when 4 or more characters have been entered into the field.
Upon selection, the entity is converted from its user-friendly display name to the raw entity id value required by the system.
The Implementation Behind the Autocomplete Control?
Commerce Engine Configuration
The autocomplete control is configured by setting a ViewProperty’s UiType to “Autocomplete”. In addition to this there are two policies that need to be added to the ViewProperty, which are required to complete its configuration.
The first policy is the SearchScopePolicy, which is utilised to retrieve the index name from, which is set in the Plugin.Search.PolicySet-1.0.0.json in the Commerce Engine. Using the GetPolicyByType method, pass in the typeof entity that the is configured to the policy’s EntityTypeNames property.
Note: Only the Catalog Items Scope is supported by default.
var searchScopePolicy = SearchScopePolicy.GetPolicyByType(context.CommerceContext, context.CommerceContext.Environment, typeof(SellableItem));
The second policy is a generic policy that will be utilised by BizFx to apply some post-search filtering to the search results. This policy must have the PolicyId of “EntityType” and will contain a list of up to two models.
The first model’s name must be set as the name of the entity without the “Entity-“ prefix (“SellableItem”, “Category”, or “Catalog”). This is known as the policy scope in BizFx.
The second model’s name is only applicable for sellable items and can only be set as “SearchVariants” if you want the variants to be included in the search results for selection. All other values will be ignored and you cannot set multiple entities to be included in the autocomplete list.
var policy = new Policy(new List<Model>()
{
new Model() { Name = "SellableItem" },
new Model() { Name = "SearchVariants" }
})
{
PolicyId = "EntityType"
};
BizFx Implementation
The sc-bizfx-autocomplete.component.ts file that is shipped with the BizFx SDK is where some of the magic happens. A couple of magic strings and magic indexes are the keys to processing the translating the ViewProperty configuration into search parameters and post-search filtering.
In short, when 4 or more characters are available in the text field, the text is added as the search term parameter, and the search index name, which is extracted from the SearchScopePolicy, is added as the scope parameter, passed into the Commerce Engine’s Search API, querying the top 100 results. The results are then processed by the BizFx component by filtering out entities that don’t match the entity type, specified in the policy scope model from the EntityType policy. The results are then added to the list of results that will populate the autocomplete dropdown, using the displayname as the display name and the entityid as the value.
Where SearchVariants have been configured for sellable item searches, the BizFx component iterates over the pipe separated variantdisplayname and variantid fields to create variant entries in the autocomplete list.
Note: As BizFx uses the displayname field to render the autocomplete item list, the order and customer indexes, which do not contain a displayname field cannot be configured with autocomplete functionality without customisation. Alternatively, the Search entity views in the Customers Manager and Orders Manager are available.
Search Configuration
In the Solr core’s managed-schema, copies fields over to the _text_ field, which is used to construct the search query in the Commerce Engine.
The catalog item scope index contains the Catalog, Category, and Sellable Item data, based on the SearchScopePolicy configuration of the Entity Type Names from the Commerce Engine SDK. Search queries will attempt to match fields copied into the _text_ field in the search provider’s index schema.
<copyField source="displayname" dest="_text_"/> <copyField source="variantid" dest="_text_"/> <copyField source="variantdisplayname" dest="_text_"/> <copyField source="productid" dest="_text_"/> <copyField source="name" dest="_text_"/>
Note: I have only looked into the Solr configuration, so for those using Azure Search there may be some investigation work required to identify its search configuration.
What Configurations are Available for the Autocomplete Control?
Catalog Search
The catalog search is not used by the business tools by default. Instead, due to the low catalog entity count, the underlying code logic for associating a catalog to a price book or promotion book utilises the IFindEntitiesInListPipeline to populate a dropdown list control.
Note: Only the displayname and name fields will be present in the catalog entity indexes.
var searchScopePolicy = SearchScopePolicy.GetPolicyByType(context.CommerceContext, context.CommerceContext.Environment, typeof(Catalog));
var modelList = new List<Model>()
{
new Model() { Name = "Catalog" }
};
var entityTypePolicy = new Policy()
{
PolicyId = "EntityType",
Models = modelList
};
var policyList = new List<Policy>() { searchScopePolicy, entityTypePolicy };
var viewProperty = new ViewProperty(policyList)
{
Name = "Catalog Search",
UiType = UiTypes.Autocomplete
};
entityView.Properties.Add(viewProperty);
Category Search
The category search will return results for categories, regardless of the catalog it resides in.
Note: Only the displayname and name fields will be present in the category entity indexes.
var searchScopePolicy = SearchScopePolicy.GetPolicyByType(context.CommerceContext, context.CommerceContext.Environment, typeof(Category));
var modelList = new List<Model>()
{
new Model() { Name = "Category" }
};
var entityTypePolicy = new Policy()
{
PolicyId = "EntityType",
Models = modelList
};
var policyList = new List<Policy>() { searchScopePolicy, entityTypePolicy };
var viewProperty = new ViewProperty(policyList)
{
Name = "Category Search",
UiType = UiTypes.Autocomplete
};
entityView.Properties.Add(viewProperty);
Sellable Item Search
The sellable item search has two configurations available. One without variants included in the search results, and one with variants.
Sellable Item without Variants Search
var searchScopePolicy = SearchScopePolicy.GetPolicyByType(context.CommerceContext, context.CommerceContext.Environment, typeof(SellableItem));
var modelList = new List<Model>()
{
new Model() { Name = "SellableItem" }
};
var entityTypePolicy = new Policy()
{
PolicyId = "EntityType",
Models = modelList
};
var policyList = new List<Policy>() { searchScopePolicy, entityTypePolicy };
var viewProperty = new ViewProperty(policyList)
{
Name = "Sellable Item Search",
UiType = UiTypes.Autocomplete
};
entityView.Properties.Add(viewProperty);
Sellable Item with Variants Search
var searchScopePolicy = SearchScopePolicy.GetPolicyByType(context.CommerceContext, context.CommerceContext.Environment, typeof(SellableItem));
var modelList = new List<Model>()
{
new Model() { Name = "SellableItem" },
new Model() { Name = "SearchVariants" }
};
var entityTypePolicy = new Policy()
{
PolicyId = "EntityType",
Models = modelList
};
var policyList = new List<Policy>() { searchScopePolicy, entityTypePolicy };
var viewProperty = new ViewProperty(policyList)
{
Name = "Sellable Item Search with Variants",
UiType = UiTypes.Autocomplete
};
entityView.Properties.Add(viewProperty);