Since Vendr was released last March, the most requested feature has got to have been the ability to do Multi-Variants, allowing products to have multiple options such as color, size, etc. Well, we listened and in 1.5.0 Multi-Variants will be coming and here’s what you can expect.

Multi-Variants

The Vendr Multi-Variants feature will be powered by a new Variants Editor property editor that you can attach to your product content nodes. The editor itself is based on the Umbraco Block List editor format so under the hood we make use of the new data structure and a lot of Umbraco’s block editor API’s. What this means is that your variants can be completely customized to your needs, adding any supporting data you need to record against your variants simply by defining a document type and linking it with the editor. We are also hoping that by basing our editor on the block editor data structure, it means we can take advantage of improvements made in core, such as optimized persistence / searching.

Our Variants Editor isn’t just a regular property editor though. We know that managing variant data is a complex task and so having variants mingled in with the product content fields would be kind of distracting, so we’ve done something fairly unique and used a bit of Umbraco magic to allow our editor to actually render itself as a content app. By doing this it gives a focused tab on which to manage your multi-variants and allows us to create a much richer content management experience. 

All you have to do is add the variants editor as a property on your product doc type and we hook up the rest.

Product Attributes

Before you can go creating variants though, there is another concept that you need to understand and that is product attributes.

Product attributes are essentially lists of options that can be used to create your variant combinations from, for example things like color, size or fit if you were selling clothing. Each product attribute consists of a name, and a series of attribute values for the given options, so continuing the previous example, the color attribute might have a series of values like red, blue, green and size might have values of large, medium and small.

In order to manage these product attributes, we’ve created a new Options node inside the Commerce section, beneath each store. From this section you can define as many product attributes + values as you need, and you can even provide label translations if you're working with a multi-lingual setup.

Product Attribute Presets

Linked with product attributes, we’ve also come up with the concept of product attribute presets. What product attribute presets do is to allow you to define groups of product attributes / values based on a specific “theme” which are then displayed at point of product variant creation so that you can choose from a smaller, focused list of product attributes than if you were just presented with every possible option.

Creating Variants

With your product attributes defined (and optional product attribute presets), and your variants editor defined on your product document type, you are now ready to start creating your product variants.

With your product node open, you’ll now see the new Variants content app in the top right corner, which from there you can click the Create Product Variants button to launch the create dialog.

From the create dialog, you’ll then be presented with a list of product attributes from which you can select all the combinations you want to create variants for. If you have setup any product attribute presets, these will be presented first, and selecting a preset will show a smaller list of product attributes / values to choose from. To create the variants, check the checkbox against the attribute values and click Select, at which point rows will be automatically created in the variants table for every combination of the selected attributes.

Managing Variants

With variants defined in the variants table, you can manage the content for each variant by clicking the SKU of the row which will then launch the content editor for that variant. From here you’ll be presented with all the fields you defined on your variants doc type and can add and save all the information you require. 

In the variants table view, we've also added filtering features so you can filter by attribute values, and search for specific variant SKU’s to easily locate items. Additionally the table also supports sorting on the table columns, so you can also order the results as you need.

You can change a variants attribute combination at any time by clicking the cog icon on the row and selecting a new combination, and lastly you can remove a variant by clicking the trash can icon against the row.

Variant Fields

Whilst you are free to add any fields you like to your variant, there are a few fields that you might want / need to add. 

The only required field is an SKU field with the alias sku. All the following fields are optional, with Vendr falling back to the parent node if one isn’t found.

• Price [price] - The fixed price of the product variant. Should use a Vendr Price input field. 
• Price Adjustment [priceAdjustment] - Used instead of a price field to create a dynamic price by adding the adjustment amount to the parent products price. Should use a Vendr Price input field and can contain negative values.
• Stock [stock] - Allows for individual variant stock management.

Value Converter

Once you’ve defined your variants, you’ll then want to be able to access that data on the front end. To do this the variants editor comes with a built in value converter allowing you to access a strongly typed collection of all the defined variants from the parent product node. 

The property value will be of type ProductVariantCollection which contains a series of ProductVariantItem entities. Each of these entities has a Config property which contains details of the product attribute combination for the variant, and a Content property of type IPublishedElement from which you can access the variants data. The Content property can also be cast to a models builder model type for strongly typed access to the variant content too.

public class ProductVariantItem
{
    public Udi ContentUdi { get; }
    public IPublishedElement Content { get; }
    public ProductVariantConfig Config { get; }
}

public class ProductVariantConfig
{
    public IDictionary<string, string> Attributes { get; set; }
}

Vendr also ships with a helper extension method on the ProductVariantCollection class, GetInUseProductAttributes(storeId) which provides a convenient way to get a list of all attributes + values used by the variants collection. This comes in handy when rendering out the list of options on the front end, ensuring only attributes in use are displayed.

public class InUseProductAttribute
{
    public string Alias { get; }
    public ReadOnlyTranslatedValue<string> Name { get; }
    public IReadOnlyCollection<InUseProductAttributeValue> Values { get; }
}

public class InUseProductAttributeValue
{
    public string Alias { get; }
    public ReadOnlyTranslatedValue<string> Name { get; }
}

public class ReadOnlyTranslatedValue<T>
{
    public T GetDefaultValue()
    public bool HasValue(string languageIsoCode)
    public T GetValue(string languageIsoCode, bool fallbackToDefault = true)
    public bool TryGetValue(string languageIsoCode, out T value)
    public T this[string languageIsoCode]
}

API Updates

The last piece of the multi-variants puzzle are a few updates to Vendr’s API. This is largely around the AddProduct methods on the Order entity which now have additional signatures that take both a productReference and a productVariantReference which must both be supplied when adding a variant item to an order.

Order lines have also been updated to expose a new Attributes property which provides a collection of attribute combinations for the order lines product so that these can be rendered on carts and checkouts. The "uniqueness" logic for an order line has also been updated to take these attributes into account.

With both of these changes, updates have also been made to the IProductAdapter / IProductSnapshot interfaces and built-in implementations in order to support product variants and attributes, as has the product and price freezer services.

The built-in stock property editor has also had a slight overhaul in order to support both regular product and product variants, and a new IStockService interface has been created should anyone need to provide an alternative implementation.

Breaking Changes

There are a small number of breaking changes, but these have tried to be kept to a minimum.

The major break is that Vendr 1.5.0 will have a minimum Umbraco version dependency of 8.10.+ due to the inclusion of some PR’s we contributed in order to support the variants property editor rendering as a content app.

On the product service, we previously shipped some convenient GetProduct helper methods which negated the need to pass a languageIsoCode, but these have had to be removed as it would cause a signature conflict now that a productVariantReference is being passed. This just means that any call to GetProduct must also now pass a languageIsoCode, which in most cases should get the language from the current thread's culture.

Updates have also been made to the IProductAdapter interface, with an additional GetProductSnapshot method accepting a productVariantReference and, GetProductReference has been changed to TryGetProductReference.

If you are using multi-variants, then you will also need to update your cart + checkout flows as well as any confirmation email templates that render order lines to also now output attribute values from the order lines Attributes property.

What to test?

Multi Variants is quite a big new feature and it does touch on a few areas such as adding products to orders and the order calculation process + stock management so it would be great to have people test these areas to make sure they function as expected.

1. The variants editor property editor, making sure it performs the required tasks for variant management
2. The variants editor value converter to ensure the correct data is returned and is accessible in a way that makes sense.
3. The API updates to make sure these haven’t been inadvertently affected by the changes.
4. Any templates that render order lines have been updated to render the Attributes collection

How to get access to Vendr 1.5.0 Release Candidate

The Vendr 1.5.0 RC release is available now from our dev NuGet feed at https://nuget.outfield.digital/prerelease/vendr/v3/index.json.

This should be added to Visual Studio as a NuGet source and then the latest Vendr 1.5.0-rc build can be installed as normal (Be sure to make sure you have the "Include prerelease" checkbox checked).

In addition to the above package files, you can also access a copy of the Vendr Demo Store updated to use Vendr 1.5.0 RC for download from our GitHub repository.

How to feedback

Any issues found whilst testing the release candidate should be reported on our issue tracker, highlighting in the issue title that it is specifically related to the 1.5.0 RC.

If developers have any questions on implementing the changes from the release candidate, these should be asked on the Umbraco developer portal support forums.

When will Vendr 1.5.0 be released

Vendr 1.5.0 will be released in 4 weeks time on Thursday 11th of February 2021. If any issues are found during the RC period however this may push back the release date, but we want to ensure we give developers/agencies enough time to test things before we make the full release.

Update: 2021-02-11

Inline with the above paragraph, Vendr 1.5.0 has been released today - 11th of February 2021. If you wish to access the full 1.5.0 version, rather than the RC, then please follow the below link.

https://our.umbraco.com/packages/website-utilities/vendr/