Product Definitions

The Ucommerce Catalog Foundation holds all the catalog information in your installation and as such serves as the most important foundation in Ucommerce. This post will give you an idea of one of the most basic building blocks of the Catalog Foundation: Product Definitions… but first some basics.

Products, Product Families, and Variants. Oh My!

Before we get into the nitty-gritty of things we need to get the terminology right so we agree on what is what.

Products are straightforward and they represent a single product in the system with no variants associated.

Product Families are pretty much the same as a product but differ in that they’ve got variants associated with them, hence the product family.

A variant represents a single product much like a stand-alone product, but they cannot stand by themselves. Variants are always associated with a product family.

Ucommerce supports both products and product families and the good news is you don’t have to go with one over the other. You simply decide on a per product basis whether or not to support variants. So you might have some products be stand-alone products and others be product families. Whatever works for your scenario.

Product Definitions

Before you can start using catalogs you need to perform some setup to determine the data you will be working with, i.e. the taxonomy of your site, the various types of products you will support on the site, and finally your pricing scheme.

Product definitions are the most fundamental building blocks of the Ucommerce Catalog Foundation. If you are familiar with Umbraco think of them as Document Types for products. Basically, a product definition determines what data you are working with in Ucommerce, both via the UIs and the APIs.

Each product definition in Ucommerce represents a different type of product available through your store. Say you are selling Software and Shirts as in the screenshot below. A software requires a completely different set of data to sell from a Shirt. Notice that Software has different properties from the Shirt.

With product definitions you can tailor Ucommerce to your client’s needs.

Adding a New Product Definition

Ucommerce supports as many product definitions as you need. Simply right-click the Product Definitions node and click create to add a new definition. Each of the product definitions must be named uniquely so you can find it later on.

Adding New Properties to Product Definitions

You can add new properties by right-clicking the product definition and clicking Create. Just as you would do when creating a new content node in Umbraco. As you can see the product definition needs a name which will be your key for reference the product definition from code as well the identifier for the product type.

The product family check-box indicates whether the product definition allows variants or not. A product family is basically a product with variants associated with it while a non-product family (product) represents just a single product.

Once created you’ll have the opportunity to change the metadata of the property to suit your needs.

Multilingual Properties

If you need to maintain the data of the property in multiple languages you can tick off the multilingual check-box. This will give you a field per language configured in the CMS.

If you specify a property to be multilingual the property will show up under the multilingual tabs when you go and edit products.

Display on Website

A true/false value which is set on the property when accessed via the API.

Variant Properties

Determines whether the property should be a variant property that you maintain under a product family. If one or more exist the product will turn into a product family automatically and enable you to create multiple variants associated with the product family.

Setting the property as a variant property will add the Variants tabs to the editor to any product based on the product definition and will enable you to create variations of a product as part of a product family.

Render in Editor

Sometimes you need data that you don’t want the user to edit. Ticking this check box will tell Ucommerce not to render this property as part of the editor UI essentially giving you metadata that you can use and maintain from the API without having to worry about the user tampering with it.

Data Types

Each of the properties created in the previous paragraphs is based on data types, which you select when you create them. Ucommerce comes with a number of built-in data types such as ShortText, LongText, Number, Boolean, Enum, and Image.

Data types include string, number, bool, and enum which is a special type which enables you to predefine a list of values allowed for the user to select, e.g. colors, sizes, basically data with a finite number of options to choose from.

Validation Expressions

Data types can have validation expressions associated with them to validate user input when editing in the product editor. A validation expression is a standard regular expression evaluated whenever a user clicks the save button.

In Conclusion

The Product Definition is the secret sauce which makes the Ucommerce Catalog Foundation extremely powerful enabling you to model the reality you face be it as a developer creating an e-commerce solution for a client or for yourself.

An important aspect about a product definition is that you can change your mind whenever you please. If you start out without variants nothing is holding you back from moving your properties around even after you start creating products based on that product definition. Ucommerce will simply reflect the changes you need without you having to create your products from scratch.