Rune Grønkjærs Blog
Abonnér på mit feed

Tea Commerce lingo and concepts

THIS ARTICLE IS WRITTEN FOR TEA COMMERCE 1.x

UPDATED: 10. june 2011 This blog post was written to give a not so technical approach to all the concepts and terms used in Tea Commerce. An e-commerce system can be a big bite to swallow. I don’t believe that this is the case with Tea Commerce, so the following explanations shows how simple Tea Commerce really is.

Do not forget to poke me a comment if I’m too unclear on any of the details or if there is anything I need to explain. It is important that this text is just as you need it.

Table of contents

What is Tea Commerce?

Tea Commerce is an e-commerce system for Umbraco. Tea Commerce can be used for most online webshops of medium size and smaller. The low purchase price makes Tea Commerce attractive for most projects. Setup costs and the learning curve is far lower than other e-commerce systems, since it is built around a fast and flexible front end implementation.

Read more

  1. Tea Commerce own website
  2. Tea Commerce on our.umbraco.org

Order

An order is our concept of the cart and all the information belonging to it. The order contains information about order lines, delivery country, currency, VAT group, delivery method, order properties, payment method etc. An order has different stages that it can be at. In this way, the shop owner can keep track of the orders. The order contains numerous prices calculated with the current VAT group and the current currency.

Order property

Order properties are extra information associated with an order. Examples could be personal customer information or information on gift wrapping paper etc. Order Properties can not be removed, but you decide which ones to use in the UI .

The developer can add properties with the methods updateOrderProperty and updateOrderProperties.

In the administration you can also change the order properties, just not with the above two methods, as they only belong to the frontend. The frontend methods can only edit orders not yet finalized . To edit finalized orders you must use the methods updateOrderPropertyAdmin and updateOrderPropertiesAdmin.

Order Lines

Order Lines are products on the order. An order line is not a product, but contains information about the product and a quantity. In Tea Commerce product information is automatically copied to the order line when a product is put in the cart. The developer can choose freely which product properties to transfer to the order line.

The order line also contains the ID of the product node that represent the product. With this in hand, the developer, in her xslt, can pull all the information from the product that she needs. This can not be done in the JavaScript per standard. There you must rely on the information that has been attached to the order line.

Order online properties

As mentioned in the order line section, the order line information is automatically transferred from the product when the order line is added to the cart. That way you can take a snap shot of the product at the time it is put in the cart. This could be important, as the product could be Deleted or changed at a later date. It will be important to know how the product looked when it was attached to the order.

The information is handled exclusively on the server and can not be changed from the client side. This ensures data integrity, so you always know that you can trust the order line’s data.

From version 1.0.2.0 of Tea Commerce it is possible to assign dynamic information to order lines. This type of information can be assigned when the order line is added to the order with either the addOrderLine or overwriteQuantity methods. They can also be added or updated on an existing order line with the methods updateOrderLineProperty and updateOrderLineProperties.

This information is “unsafe” as they are added from the client and therefore cannot be relied on. We can not, because any user has access to calling the JavaScripts and thus alter the information. For this reason we recommend that the option is only used when you do not need to rely on the data or if you validate the data on the server.

To validate the data you can use the Tea Commerce Event model . In that you can sign up to events such as when an order line is added or an order line information is added to the order line. In the event you can then examine the data. You will then be able to change the order line and / or throw an error which can then be used on the client side.

Products

Products in Tea Commerce is handled as normal Umbraco nodes / pages in the content area. This means that if you can do it in Umbraco, you can also do it in Tea Commerce. It gives the developer an freedom to build her products, exactly to the customers needs. It also means that you can convert an existing product catalogue into a web shop in a very short time.

All the plugins you, as developer, would to use on normal Umbraco pages can also be used with Tea Commerce products. So you can eg use the Universal Media Picker to select images, movies, documents etc, which can then be associated with each product.

Products in Tea Commerce may thus be anything ranging from conventional physical products to digital products. With the Tea Commerce event model you can further customize the order lines, in the security of the server.

Prices

The price concept is extremely simple in Tea Commerce . You create some text boxes on your products, and lets the Tea Commerce Administration know about what the fields’ Umbraco aliases are. Then Tea Commerce will fetch the price when the product is added to the cart.

For each currency you have in the system, there must be an equivalent price. When the price is retrieved from the product, the system will retrieve all prices for the product, and store them on the order line. This is only done the first time the product is placed in the cart, since the customer must be confident that the price he saw when he chose the product will also be the price he can see on his confirmation page and e-mail.

A product does not need to have a price. In this case it will just be free. With the Tea Commerce event model you can change on the order lines prices, should you desire it. That way you will be able to create conditional and dynamic pricing.

Country / delivery country

Defines the country or area you want to be able to deliver the products of the webshop. Small stores will often only have one delivery country wich then have to be created in the administration. Countries are very important since they provide a wide range of default settings that every order has when first created. VAT group and currency are two fixed standards that must always be chosen on a country. With them the order will be able to calculate the correct prices for each order lines, as well as for the entire order.

You can further choose to set a standard delivery method and payment method on the country. Doing so will have them added to the order when it is created. This can be handy if you only have one to choose from and do not want your customer or client side to select it. The order must have a payment method attached for goToPayment to work.

What delivery and payment methods can be chosen on the country depends on whether they are legal in that country. This must be set on each delivery and payment method. With the JavaScript method setCurrentCountry you can change the country selected on the order.

Currency

All prices in Tea Commerce have a currency attached in one way or another. That way you will be able to run with different prices for different currencies. Currencies are not unique and you could therefore have several Euro currencies if you want to differentiate prices between euro nations.

Currencies has a culture name associated wich is used to format the prices in that currency. What culture you choose is optional as long as it is following the .NET standards. With the JavaScript method setCurrentCurrency you can change the currency on the order.

Order Status

Order status is solely a means for the shop owner to keep track of he’s orders. Tea Commerce do not use them, other than setting all new orders to the default status. The webshop owner may change the status of each order in the Tea Commerce Administration. Here you will also be able to search in the orders on a specific status.

VAT Groups

VAT Groups are a way to control the VAT on various product groups, or different delivery countries. If the webshop have regional VAT registered offices, you can sell goods with that country’s VAT.

VAT Groups are affiliated with a country, which will be the standard VAT for a new order. It will furthermore be associated with individual products and delivery and payment methods. In this way, you can put special VAT groups on all parts of an order. Usually you will be able to make do with having one VAT group, as all products will be sold with the same VAT group.

Products can have a VAT group attached. To do that you must add the “Tea Commerce VAT group picker” data type to the products document type. It offers a dropdown where the admin user can choose among the available VAT groups.

Delivery Methods

Delivery methods are how the web shop can deliver its products to the customer. If the webshop has only one delivery method, you could set it as default on the delivery country. That way, you do not have to let the client handle the choosing of the delivery method. If you have multiple delivery methods, you can let the customer choose a delivery method and use the JavaScript method setShippingMethod to send the new delivery method to the server.

All delivery methods has to be associated to one or more countries in order to be valid. The delivery methods the client can choose from, is reflected by the country, which is set on the order.

For each country and each currency you can set a delivery fee and an amount over which the delivery will be free.

Payment Methods

Payment Methods are how a user can pay for his order. If the webshop has only one payment method, you could set it as default on the delivery country. That way, you do not have to let the client handle the choosing of the payment method. If you have multiple payment methods, you can let the customer choose a payment method and use the JavaScript method setPaymentMethod to send the new payment method to the server.

Payment methods may be associated with a payment provider (Eg QuickPay or paypal). If the payment method has a pay provider associated the user will be sent to the given payment gateway provider when goToPayment is called. If the order does not have a payment provider it is expected that payment will be handled manually at a later date and the order is automatically completed after which the user is sent to the standard confirmation page that is selected in general options in the Tea Commerce Administration.

All payment methods must be linked to one or more countries to be valid. The payment methods, the client can choose from, are reflected by the country , which is selected on the order.

For each country and each currency you can set a payment fee. An order MUST have a payment method attached. This is to let Tea Commerce know where to send the custommer when he is to pay for the order.

Payment providers

Payment providers are external companies that offer online credit card payments. Tea Commerce uses a provider-based approach to implementing new payment providers. This means that every .NET developer can create and use new payment providers with Tea Commerce.

Payment providers may be associated with payment methods which then ensures that the customer will be able to pay with the provider. Without a payment method the payment providers will not be used.

Note that you must have an account at the payment provider you wish to use. The information from the account you can enter into the Tea Commerce Administration under the payment method that uses the provider.

E-mail templates

When sending emails to the customer and to the webshop you can set up the mail’s html in our template. The template is an ordinary xslt file with the posibilities which comes with it. From the xslt you have access to the order and can therefore base the e-mail’s html on all the usual information.

Order template

When each order is listed in the Tea Commerce Administration it is done using an xslt that the developer has full access to. With the xslt you can customize the order looks to fit the webshop needs 100%. So you can display just the information that is important and remove all the useless stuff. From the xslt you have access to the order and can therefore use all the same information, used on the website.

The only thing to note is that it is risky to draw details from the product node, since this can evolve over time. The Convention will therefore be only to use the information you have stored on the order.

Inventories

Inventories for each product is the only non Umbraco-style set on a product. When the developer creates the document type for her product the data type “Tea Commerce Stock” must be used. This will provide a textfield in wich you can enter the decimal of the available inventory. Tea Commerce Stock data type will then save the entered number in a database table from which it can be quickly retrieved and corrected.

That we use an extra database table to save the stock affects two things. One is that you can not use the products property stock directly from the node, since it does not contain any useful data. Instead, you use have two methods respectively in the JavaScript API and the xslt extension. The JavaScript method is named getStock and the xslt extension sister is called GetStock.

Stock is not required on a product, so you can leave out the special data type from the document type. If it is on the product, you do not have to fill it out. In either case the product will behave as having infinite stock.

Tea Commerce uses an optimistic stock management. This means that the stock is only altered when an order is finalized.

Caching

Tea Commerce uses an advanced form of caching to ensure as few database queries as possible. All objects is cached in the RAM’s so they are available for user fast. In order not to overload the cache objects are removed after a short period of time unless they are being used.

Orders are cached, but can only be accessed by the user / customer who owns them. All general settings are cached as well. They are shared between all users/customers/admins, since they are common to all.

To maintain consistency in the data both in the database, but also in the cache, all changes on the object structure is addressed in both database and cache.

Finalized order

A finalized order is Tea Commerce’s concept for an paid order. When the customer arrives at the confirmation page, the order was finalized. A finalized order can no longer be edited from the client side, but can still be accessed with the method getFinalizedOrder.

Event Model

Tea Commerce’s event model is the way. NET developers can hook into different events and then change the order. The Event model opens up for creating highly sophisticated webshops that can do exactly what you want. With a little imagination and a skilled programmer there is not much that can not be done.
My blog post about the Event Model explains much more about the technical part.

Tea Commerce Administration

Tea Commerce has its own area inside the Umbraco administration. The green leaf in bottom of the Umbraco Administration provides access to all Tea Commerce settings. You also have the opportunity here to see all orders old as well as new.

Nice to know

What is umbracoLanguageId used for?

It is used to store the order line’s properties in all possible languages​​. If you make a shop with more languages the properties ​​will be saved in all languages.

Why not order properties?

The observant reader may have noticed that the language ID is only being sent with the order line properties and not the order properties. Order properties are considered general and not presumed to belong to a particular language.

TIP: If you still need to have a order property in several languages​​, you can choose to name your property with the language id. Eg “name1″ “name2″ and “name3 ‘, where the figure is the language id. In the rare event that you need it, this solution will do the job.

How do I access properties in the different languages ?​

The values ​​you get with your order, be it in JavaScript or XML’en is only in one language. The language is the order language, which you can access directly on the order with the value umbracoLanguageId in the XML and UmbracoLanguageId in the JavaScript.

You can change the order language with the new JavaScript method TeaCommerce.setOrderUmbracoLanguage(umbracoLanguageId, async, successfn, errorfn). As soon as you call it, all the property values are ​​changed to the new language.

Can I have a language-independent order line property

Yes, the properties automatically added by Tea Commerce are not necessarily tied to a language. In this case, their value is always available, regardless of order languages​​.
If you want to add an order line property not belonging to a particular language simply send 0 (zero) as language ID

Tea Commerce links

This post was written in .NET, Ajax, e-commerce, Tea Commerce, Umbraco. Ad permalink to favorites. Follow all comments with RSS feed for this posts. Drop a comment or a trackback: Trackback URL. | Læs denne side på dansk dansk version

Drop a comment

Your email is never published nor shared. Required fields are marked *

*
*

You can use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Dansk version